Getting Started

The O3 Code CLI (o3-code) is a single static binary that drives the same backend as the desktop app. Use it to manage workspaces, tasks, automations, and the local host server from your terminal or from CI.

Install

Desktop app

The desktop app includes the O3 Code CLI. When the app launches, it writes an app-managed shim at ~/.o3/code/bin/o3-code, and O3 Code terminals prepend ~/.o3/code/bin to PATH automatically.

To use the bundled CLI from a normal shell, add the directory to your shell profile:

export PATH="$HOME/.o3/code/bin:$PATH"

Standalone install

curl -fsSL https://code.o3.dev/cli/install.sh | sh

The script auto-detects your platform (macOS Apple Silicon or Linux x86_64), installs O3 Code under ~/o3-code by default, and adds ~/o3-code/bin to your shell PATH.

Homebrew

brew install o3dotdev/tap/o3-code

Sign in

o3-code auth login

The CLI starts a loopback callback server on 127.0.0.1:51789 (or 51790 through 51793 if earlier ports are busy), opens your browser to the consent page, and stores a session token at ~/.o3/code/config.json.

If you belong to multiple organizations, you'll be prompted to pick one. To skip the prompt and pick directly:

o3-code auth login --organization acme

For CI or other non-interactive environments — where there's no browser to complete the OAuth flow — use an API key instead. You can either store it once with auth login --api-key:

o3-code auth login --api-key sk_live_…
o3-code auth whoami

…or set O3_CODE_API_KEY per-invocation without writing anything to disk:

export O3_CODE_API_KEY=sk_live_…
o3-code auth whoami

API keys are issued from the Settings → API Keys page in the desktop app.

Verify your session

o3-code auth whoami

Signed in as Satya Patel (you@example.com)
Organization: Acme
Auth: Session (expires in 32 min)

Run your first commands

List the projects in your organization:

o3-code projects list

If your repo isn't there yet, register it on this machine — clone from a Git URL or import an existing checkout:

# Clone from a URL
o3-code projects create --name "my-app" --local \
  --clone https://github.com/org/my-app.git \
  --parent-dir ~/code

# Or register an existing local checkout
o3-code projects create --name "my-app" --local --import ~/code/my-app

If the project already exists in your org but isn't on this machine, attach to it instead of creating a duplicate:

o3-code projects setup <id-from-projects-list> --local --parent-dir ~/code

Then create a workspace against it:

o3-code workspaces create \
  --project prj_… \
  --name "fix-login-bug" \
  --branch fix/login-bug \
  --local

Trigger an automation immediately:

o3-code automations list
o3-code automations run aut_…
o3-code automations logs aut_…

Output modes

Every command prints a TTY-friendly view by default. Two flags switch the shape of the output for scripting:

o3-code tasks list --status in_progress --json | jq '.[].title'
o3-code workspaces list --quiet | xargs -L1 o3-code workspaces delete

When the CLI detects an agent or CI environment (CLAUDE_CODE, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CODEX_CLI, GEMINI_CLI, O3_CODE_AGENT, or CI set to a non-empty value), it defaults to JSON output unless you pass --quiet.

Local vs. remote hosts

Commands that touch a host accept --host <id> to pick which host handles the request, or --local for this machine. Local-targeted calls go straight to the host server over loopback (offline-friendly); remote calls route through the cloud API and the relay.

o3-code hosts list
o3-code workspaces list
o3-code workspaces list --host h_…
o3-code workspaces list --local

Mutating host commands (projects create, projects setup, workspaces create) require an explicit --host or --local — there's no default. workspaces list is organization-wide when neither --host nor --local is provided; pass --local to restrict it to this machine.

Where state lives

~/.o3/code/config.json                            # auth, active organization
~/.o3/code/host/<organizationId>/manifest.json    # host server endpoint + token
~/.o3/code/host/<organizationId>/host.db          # local host server DB

O3_CODE_STATE_ROOT relocates the whole tree, matching the desktop app.

Next steps

Continue to the CLI reference for every command, flag, and output shape.