rightbrain

Command line interface for RightBrain AI.

Authenticate, manage tasks, generate TypeScript types, and run tasks directly from your terminal.

Installation

No installation required. Run with npx:

npx rightbrain@latest <command>

Quick Start

# Authenticate with RightBrain
npx rightbrain@latest login

# Initialize a project (creates config, generates types)
npx rightbrain@latest init

# Run a task
npx rightbrain@latest task run

Commands

login

Authenticate with RightBrain using browser-based OAuth.

npx rightbrain@latest login

Opens your browser to complete authentication. After login, prompts for organization and project selection.

| Flag | Description | | ------------------- | ------------------------------------------------------------------------------------------------ | | --non-interactive | Skip prompts and open browser immediately. Exits after authentication without project selection. |

logout

Log out and clear stored credentials.

npx rightbrain@latest logout

| Flag | Description | | ----------- | ------------------------ | | -y, --yes | Skip confirmation prompt |

init

Initialize RightBrain configuration for your project.

npx rightbrain@latest init

This command:

1. Creates rightbrain.json configuration file
2. Creates or updates .env with credentials
3. Installs @rightbrain/sdk if not present
4. Prompts to select an API key (or creates one)
5. Prompts to select tasks for type generation
6. Runs generate to create TypeScript types

Warns if:

• rightbrain.json already exists
• Git repository has unstaged changes

switch-project

Switch to a different organization and project.

npx rightbrain@latest switch-project

| Flag | Description | | ------------------- | ----------------------------------------- | | --org-id <id> | Organization ID (requires --project-id) | | --project-id <id> | Project ID (requires --org-id) |

Without flags, presents an interactive selection.

whoami

Display current user and selected organization/project.

npx rightbrain@latest whoami

generate

Generate TypeScript types for configured tasks.

npx rightbrain@latest generate

Reads task IDs from rightbrain.json and generates typed interfaces in generatedTaskTypePath (defaults to ./src/generated if src exists, otherwise ./generated).

Requires @rightbrain/sdk >= 0.3.0.

organization

Manage organizations.

organization list

List your organizations.

npx rightbrain@latest organization list

| Flag | Description | | -------- | -------------- | | --json | Output as JSON |

project

Manage projects.

project list

List projects in the current organization.

npx rightbrain@latest project list

| Flag | Description | | -------- | -------------- | | --json | Output as JSON |

task

Manage tasks.

task list

List tasks in the current project.

npx rightbrain@latest task list

| Flag | Description | | ---------------------- | --------------------------------- | | --json | Output as JSON | | -l, --limit <number> | Maximum number of tasks to return |

task get

Get full details for a task, including its active revision configuration.

npx rightbrain@latest task get

| Flag | Description | | ----------------- | -------------- | | -t, --task <id> | Task ID | | --json | Output as JSON |

Without --task, prompts to select from available tasks.

task create

Create a new task.

npx rightbrain@latest task create

| Flag | Description | | ------------------- | ------------------------------------------------ | | -f, --file <path> | Create task from a YAML file | | -d, --direct | Skip prompts, fail on errors (requires --file) |

Without flags, prompts to either open the dashboard or download a YAML template.

YAML format:

name: My Task
description: Task description
llm_model_id: <model-uuid>
system_prompt: |
  You are a helpful assistant.
user_prompt: |
  Process this: {input_param}
output_modality: json
output_format:
  result:
    type: str
    description: The result
enabled: true
file_input_mode: "none"

task update

Update an existing task by creating a new revision from a YAML file.

npx rightbrain@latest task update --file update.yaml

| Flag | Description | | ------------------- | ------------------------------------------ | | -f, --file <path> | YAML file with fields to update (required) | | -t, --task <id> | Task ID to update | | --activate | Activate the new revision immediately | | --json | Output as JSON |

Without --task, prompts to select from available tasks. Use --activate to immediately set the new revision as active.

task run

Run a task.

npx rightbrain@latest task run

| Flag | Description | | -------------------------- | ---------------------------------- | | -t, --task <id> | Task ID to run | | -r, --revision <id> | Specific revision ID | | -i, --input <name=value> | Input parameter (repeatable) | | -f, --file <name=path> | File input (repeatable) | | --image <path> | Image to attach (repeatable) | | -d, --direct | Run without fetching task metadata | | --use-fallback-model | Use fallback model |

Interactive mode (default):

Without flags, prompts for task selection and required inputs based on the task configuration.

Direct mode:

npx rightbrain@latest task run \
  -t "019bb0de-9b73-7d52-650d-2ca7287630da" \
  -i "prompt=Hello world" \
  --image ./photo.jpg \
  -d

Direct mode requires a valid UUID for task ID. Use this in scripts and CI/CD.

Output:

• When piped: JSON
• When interactive: Colored object inspection

model

Manage models.

model list

List available LLM models.

npx rightbrain@latest model list

| Flag | Description | | ----------------------- | -------------------------------------------- | | -p, --provider <name> | Filter by provider (e.g., openai, anthropic) | | --json | Output as JSON | | -c, --compact | Show only ID and name |

Deprecated Commands

The following top-level commands are deprecated and will be removed in a future release. They continue to work but print a deprecation warning.

| Deprecated command | Replacement | | ------------------ | ------------- | | create-task | task create | | run-task | task run | | list-models | model list |

Configuration

rightbrain.json

Project configuration file created by init:

{
  "$schema": "https://app.rightbrain.ai/cli/schema.json",
  "orgId": "${RB_ORG_ID}",
  "projectId": "${RB_PROJECT_ID}",
  "apiKey": "${RB_API_KEY}",
  "taskIds": ["019bb0de-9b73-7d52-650d-2ca7287630da"],
  "generatedTaskTypePath": "./src/generated"
}

| Property | Required | Description | | ----------------------- | -------- | ------------------------------------------------ | | orgId | Yes | Organization ID (UUID) | | projectId | Yes | Project ID (UUID) | | apiKey | * | RightBrain API key | | clientId | * | OAuth2 client ID (alternative to apiKey) | | clientSecret | * | OAuth2 client secret (with clientId) | | taskIds | No | Task IDs for type generation | | generatedTaskTypePath | No | Directory where generated task types are written | | envFile | No | Path to env file (default: .env) | | oauthUrl | No | OAuth2 server URL | | apiUrl | No | API base URL |

* Either apiKey or both clientId and clientSecret required.

Environment variable interpolation:

Use ${VAR_NAME} syntax. Variables are resolved from the env file.

Piped Output

When stdout is piped, the CLI:

• Outputs JSON instead of formatted text
• Routes prompts to stderr
• Suppresses spinners

npx rightbrain@latest task run -t <id> -d | jq .response

License

MIT