orca doctor, topology, bundles, and apps

Last updated: 2026-09-06

These four top-level commands observe the platform rather than change it. orca doctor checks the local install, config, and connectivity and suggests a fix for anything that is off. orca topology, orca bundles, and orca apps each read one part of the conductor’s state and take no flags of their own. Every command accepts the global flags.

orca doctor

orca doctor [--strict]

Runs eleven preflight checks and prints a report. The config is resolved tolerantly, so a corrupt config file is reported as a failing check rather than aborting the run, and an API key is not required to run doctor. The four network probes run concurrently, each with a 3000 ms timeout. The exit code is 1 when any check fails and 0 otherwise; warnings alone do not fail the command.

Flag	Type	Default	Description
`--strict`	boolean	`false`	Treat warnings as failures (exit 1). The informational `color output` warning is exempt

Each check has a status of pass, warn, fail, or skip, a message, and sometimes a fix: a one-line, copy-pasteable remedy shown under a warning or failure. The checks, in report order:

Check	What it verifies
`node version`	The runtime is Node 22 or newer. Fails otherwise (fix: install Node 22 or newer).
`color output`	Informational. Warns when stdout is not a TTY or `NO_COLOR` is set. Never a failure, even under `--strict`.
`config file`	The config file exists and parses. A present but corrupt file fails (fix: repair or remove it, then `orca auth login`). A missing file passes when `ORCA_API_KEY` is set, and warns otherwise (fix: `orca auth login`).
`config permissions`	The config file is readable only by its owner. Fails when group or other bits are set (fix: `chmod 600 <path>`). Skipped on Windows or when there is no file.
`context`	The effective context resolves. Fails when a context named with `--context` or `ORCA_CONTEXT` is not in the config file, unless `ORCA_API_KEY` and `ORCA_API_URL` are both set (fix: `orca context list`). On pass, the message reports where each of `apiUrl`, `gateway`, `dashboard`, and `key` came from: `flag`, `env`, `file`, `default`, or `unset`.
`conductor`	`GET /healthz` on the API URL, unauthenticated. Fails on a missing API URL, a timeout, a network error, or a non-2xx response. The fix hint differs for localhost (is the local conductor running, or unset `ORCA_API_URL`) and remote hosts (check the connection and the status page).
`api key`	An API key is configured (fix: `orca auth login`).
`api key role`	`GET /api/api-keys` with the key, which only a member or higher can read. A 200 passes and names the key’s role and label when the context stores a `keyId`; 401 fails (invalid or revoked); 403 warns (role below member); 404 and 5xx warn; a timeout or network error warns. Skipped without a URL or key.
`billing`	Reads `GET /api/billing/wallet` and `GET /api/spend-cap` to predict whether run creation would be refused, without creating a run. A 503 passes (billing not wired, so the credit gate is inactive); 404 skips; 401 and 403 warn; 5xx fails (billing unreachable, runs blocked fail-closed); a 200 with `configured: false` or a balance at or below zero fails (fix: add or top up credits in the dashboard). Otherwise, if the spend cap is enabled and exhausted this month, it fails with the fix `orca billing cap set <amount>`.
`chat gateway`	A gateway URL is configured and `GET /healthz` on it answers. A missing URL, timeout, or network error warns (fix: set `ORCA_GATEWAY_URL` or `--gateway-url`); any HTTP response, including 404, passes. Only `orca chat` needs the gateway.
`dashboard url`	A dashboard URL is configured for the browser login flow. Warns when unset (fix: set `ORCA_DASHBOARD_URL` or pass `--dashboard-url`); the message notes `(default)` when the baked-in value is in use.

orca doctor --strict --json

With --json an array of { "name", "status", "message", "fix" } objects is printed, in report order; fix is present only when the check carries a remedy. Plain (piped) output is one tab-separated row per check: name, status, message. The terminal view adds a header with the API host and a footer that counts ok, warn, and fail.

orca topology

orca topology

Shows the conductor’s runner pool from GET /api/topology. Each runner is listed by hash with its health (healthy or down), active session count, latency in milliseconds when known, and the last probe error if any. In a terminal the pool is drawn as a tree under a conductor root with a N runners, N healthy summary. See Architecture for how the conductor routes to runners.

orca topology --json

With --json the array of runner records is printed (hash, url, healthy, latencyMs, activeSessions, error, capabilities). Plain (piped) output is one tab-separated row per runner: hash, url, healthy or down, activeSessions, latencyMs (or empty), error (or empty). A conductor running in single-runner mode answers 404, which the CLI reports as a not-found error (exit code 4).

orca bundles

orca bundles

Lists the capability bundles an agent document can attach with an @ reference, such as @fs for storage or @memory for the memory bank. Reads GET /api/capability-bundles and unwraps the bundles array. Each bundle has a value (the @name to use in the document), a label, and a description.

orca bundles --json | jq -r '.[].value'

With --json the array of bundle records is printed. Plain (piped) output is one tab-separated row per bundle: value, label, description.

orca apps

orca apps

Shows Connected Apps providers and the tenant’s connections, read-only. Reads GET /api/connected-apps/providers and GET /api/connected-apps/connections. A 503 from either endpoint (the Connected Apps registry is not configured on this conductor) degrades to an empty list rather than an error; auth failures and other errors still surface. In a terminal, when both lists are empty, the command prints a hint on stderr that no providers are configured (the conductor needs COMPOSIO_API_KEY).

orca apps --json

With --json a single object is printed: { "providers": [...], "connections": [...] }, where a provider has name and configured, and a connection has id, provider, appSlug, scope, status, mcpServerName, and createdAt. Plain (piped) output mixes both shapes, so each row starts with a discriminator: provider, name, configured or not-configured; and connection, id, provider, appSlug, status.

Verified against orca-cli cli-v0.5.0.

Using the CLI

Command reference

orca doctor, topology, bundles, and apps

orca doctor

orca topology

orca bundles

orca apps

​orca doctor

​orca topology

​orca bundles

​orca apps

orca doctor

orca topology

orca bundles

orca apps