CLI Reference

Authenticate via browser OAuth and store a session token at ~/.o3/code/config.json.

Single-org accounts are selected automatically. With multiple orgs and a TTY, the CLI prompts; with multiple orgs and no TTY, you must pass --organization or the command exits 1 listing the available slugs.

o3-code auth login
o3-code auth login --organization acme

To sign in with an API key — useful for CI or any environment where the OAuth browser flow isn't an option — pass --api-key. The CLI validates the key, stores it at ~/.o3/code/config.json, and clears any prior OAuth session.

o3-code auth login --api-key sk_live_…
o3-code auth login --api-key sk_live_… --organization acme

◇  Authorized!
│  Satya Patel (you@example.com)
│  Organization: Acme
└  Logged in successfully.

{
  userId: string;
  organizationId: string;
  organizationName: string;
}

Clear stored credentials — both an OAuth session and a stored API key. Does not call the API and does not clear the active organization (your preferred org persists across re-logins).

o3-code auth logout

Logged out.

{ message: "Logged out." }

Show the current user, active organization, and auth source.

o3-code auth whoami

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

{
  userId: string;
  email: string;
  name: string;
  organizationId: string;
  organizationName: string;
  authSource: "override" | "config" | "oauth";
}

If a manifest exists and the PID is alive, returns the existing instance's details. Otherwise spawns the host server binary, polls /trpc/health.check for up to 10 seconds, and writes the manifest. Binds to 127.0.0.1 only.

o3-code start --daemon

{
  pid: number;
  port: number;
  organizationId: string;
}

Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive. The manifest is removed in all cases — including when SIGTERM itself throws.

o3-code stop

// No manifest
{ running: false }

// Manifest existed
{ pid: number; organizationId: string }

healthy reflects a live health.check request (2-second timeout).

o3-code status

// No manifest
{ running: false; organizationId: string }

// Manifest exists but PID is dead
{
  running: false;
  stale: true;
  pid: number;
  organizationId: string;
}

// Running
{
  running: true;
  healthy: boolean;
  pid: number;
  port: number;
  endpoint: string;
  organizationId: string;
  uptimeSec: number;
}

Downloads the matching o3-code-<platform>.tar.gz from GitHub Releases and atomically replaces the install root. Only available in built binaries; running from bun run dev errors out.

o3-code update                     # upgrade to the latest release
o3-code update --check             # show current → target without installing
o3-code update --version 0.1.2     # install a specific version (up or down)

Updated 0.1.4 → 0.1.5 (/Users/you/.local/share/o3-code)

// --check
{
  current: string;
  target: string;
  upToDate: boolean;
  pinned: boolean;
}

// install
{
  current: string;
  target: string;
  updated: boolean;
  installRoot?: string;
}

List organizations available to the current auth context. Marks the active one.

Set the active organization in ~/.o3/code/config.json.

o3-code organization switch acme
o3-code org switch org_…

List members in the active organization.

o3-code organization members list
o3-code org members list -s satya

List projects in the active organization. Org-wide; not host-scoped.

Create a fresh project on a host. Two modes:

• Clone — pass --clone <url> and --parent-dir. The host clones the repo into <parent-dir>/<derived-name>/.
• Import — pass --import <path> to register a repo that already exists on disk.

Either way, a new cloud project record is created and the host's main workspace is ensured.

create always creates a new cloud project, even if your org already has one for the same Git URL. Use projects setup when adopting an existing project on a fresh machine.

o3-code projects create --name "my-app" --local --clone https://github.com/org/my-app.git --parent-dir ~/code
o3-code projects create --name "my-app" --local --import ~/code/my-app

Adopt an existing project onto a host without creating a duplicate cloud record. Counterpart to create for the "new machine, repo already in the org" case.

Find the project ID via projects list.

Idempotent: re-running against a project that's already set up at the same path is a no-op that returns the existing mainWorkspaceId.

# Pick an ID from `o3-code projects list`, then clone it onto this machine
o3-code projects setup 47c31b04-… --local --parent-dir ~/code

# Or register an existing local checkout
o3-code projects setup 47c31b04-… --local --import ~/code/my-app

List hosts registered to the active organization. Host registration happens via o3-code start on each machine — there is no separate registration command.

o3-code hosts list

List workspaces accessible to the active organization. With neither --host nor --local, the list is organization-wide.

Create a workspace on the target host. Specify exactly one of --branch or --pr. If you pass --agent, you must also pass --prompt.

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

o3-code workspaces create \
  --project prj_… \
  --name "review-pr-123" \
  --pr 123 \
  --local

Delete one or more workspaces on the target host.

o3-code workspaces delete ws_a ws_b ws_c

Update a workspace.

o3-code workspaces update ws_… --name "better-name"
o3-code workspaces update ws_… --task-id tsk_…
o3-code workspaces update ws_… --clear-task

Open a workspace in the O3 Code desktop app.

o3-code workspaces open ws_…
o3-code workspaces open ws_… --print

List agents configured on a host. First call on a fresh host seeds the bundled defaults.

o3-code agents list --local
o3-code agents list --host host_…

Launch an agent inside an existing workspace. Resolves the host that owns the workspace and starts the named preset (or HostAgentConfig instance) in a fresh terminal session on that host.

o3-code agents run --workspace ws_… --agent claude --prompt "Audit the login flow"
o3-code agents run --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log

List tasks in the active organization.

o3-code tasks list --assignee-me
o3-code t list -s "auth" --json

Get a task by ID or slug.

o3-code tasks get tsk_…
o3-code tasks get fix-login-bug

Create a task.

o3-code tasks create --title "Audit auth flow" --priority high

Update a task. Same fields as create, all optional.

o3-code tasks update fix-login-bug --priority urgent

Delete one or more tasks.

o3-code tasks delete tsk_a tsk_b

List task statuses in the active organization. Use the returned IDs with tasks list --status, tasks create --status-id, or tasks update --status-id.

o3-code tasks statuses list

List automations in the active organization.

Get an automation's metadata. The prompt body is omitted — use automations prompt get to read it. Use automations logs for run history.

Create an automation. Provide --prompt or --prompt-file; if both are present, the inline --prompt value is used. At least one of --project or --workspace must be provided.

o3-code automations create \
  --name "Weekday triage" \
  --project prj_… \
  --workspace ws_… \
  --rrule "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0" \
  --prompt-file ./prompts/triage.md

Update an automation's metadata (name, schedule, agent, host). All flags optional. Omitting a flag preserves the existing value — undefined means "no change", not "clear". Use automations prompt get or automations prompt set to read or replace the prompt body.

Print an automation's prompt body to stdout. The output is the raw prompt with no trailing newline added, so prompt get and prompt set round-trip byte-exactly.

# Read to a file
o3-code automations prompt get aut_… > prompt.md

# Verify a push landed
o3-code automations prompt get aut_… | diff - ./prompt.md

Replace an automation's prompt body. The new prompt fully overwrites the old one.

# Write from file
o3-code automations prompt set aut_… --from-file ./prompt.md

# Write from stdin
cat ./prompt.md | o3-code automations prompt set aut_… --from-file -

Delete an automation.

o3-code automations delete aut_…

Pause an automation (sets enabled: false).

o3-code automations pause aut_…

Resume an automation (sets enabled: true). The API recomputes nextRunAt on resume.

o3-code automations resume aut_…

Dispatch an automation immediately. Does not wait for completion.

o3-code automations run aut_…

List recent runs for an automation.

o3-code automations logs aut_…