Skip to main content
Last updated: 2026-09-06
orca agents manages agent profiles: the runtime, model, prompt, tools, skills, and MCP servers that define an agent. Agents are created and updated from a YAML or JSON agent document. Every subcommand accepts the global flags. Subcommands that take an optional [name] open an interactive picker when the name is omitted in a terminal; in a pipe or script the name is required (exit code 2).

​
orca agents list

Lists the agents in the current tenant. The terminal view adds a published column from a second request; if that request fails the column shows ? and the listing still succeeds.
Plain (piped) output is one tab-separated row per agent: name, runtime, model, published.

​
orca agents get

Shows one agent. With --json the full profile object is printed; the plain view prints name, runtime, model, and skills.

​
orca agents changes

Shows the change history for a profile, newest first. Each entry records when the change happened, the action (created, updated, deleted), the fields that changed, and the redacted before and after snapshots (in --json output only). The server returns up to 200 entries; --limit trims client-side.

​
orca agents create

Creates an agent from an agent document. Unknown keys in the document produce warnings on stderr but do not block the create unless --strict is set.

​
orca agents update

Replaces an agent’s profile with the contents of the document. The target defaults to the name field in the document; pass a different [name] to rename an existing agent (the old name is the positional, the new name is in the file).

​
orca agents delete

Deletes an agent. Prompts for confirmation in a terminal; in a script --yes is required or the command refuses (exit code 2).

​
orca agents publish

Publishes an agent to the public chat gateway so it can be reached with a chat key. See Publishing. The --json output is the published-agent record, including publicUrl. After publishing, issue a chat key with orca agents keys create <name>.

​
orca agents unpublish

Takes a published agent off the gateway. Clients using its chat keys start failing immediately.

​
orca agents keys

Chat keys authenticate callers of a published agent through the gateway. They are separate from tenant API keys, which authenticate the CLI itself.

​
orca agents keys list

Lists chat keys for a published agent with their label, creation time, last use, and state (active, expires <time>, or revoked).

​
orca agents keys create

Issues a chat key. The plaintext token is shown exactly once. In a terminal it is revealed with a prompt; when stdout is a pipe, stdout carries only the token; with --json the full issued-key record is printed.

​
orca agents keys revoke

Revokes a chat key by id. Takes effect immediately.
Verified against orca-cli cli-v0.5.0.