> ## Documentation Index > Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt > Use this file to discover all available pages before exploring further. # orca agents > Create, inspect, update, publish, and delete agent profiles, and manage chat keys for published agents. > **Last updated: 2026-09-06** `orca agents` manages [agent profiles](/concepts/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](/cli/agent-documents). Every subcommand accepts the [global flags](/cli/reference/overview#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 ```bash theme={"dark"} orca agents list [--limit ] [--offset ] [--all] ``` 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. | Flag | Type | Default | Description | | -------------- | ------- | ------- | ------------------------------------------------------------------ | | `--limit ` | integer | `10` | Page size | | `--offset ` | integer | `0` | Page offset | | `--all` | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) | ```bash theme={"dark"} orca agents list --all --json | jq -r '.[].name' ``` Plain (piped) output is one tab-separated row per agent: `name`, `runtime`, `model`, `published`. ## orca agents get ```bash theme={"dark"} orca agents get [name] ``` Shows one agent. With `--json` the full profile object is printed; the plain view prints `name`, `runtime`, `model`, and `skills`. ```bash theme={"dark"} orca agents get researcher --json ``` ## orca agents changes ```bash theme={"dark"} orca agents changes [--limit ] ``` 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). | Flag | Type | Default | Description | | ------------- | ------- | --------- | -------------------------------------------------- | | `--limit ` | integer | unlimited | Cap the number of entries shown (must be positive) | The server returns up to 200 entries; `--limit` trims client-side. ## orca agents create ```bash theme={"dark"} orca agents create -f [--strict] ``` Creates an agent from an [agent document](/cli/agent-documents). | Flag | Type | Default | Description | | ------------------- | ------- | -------- | --------------------------------------------------------- | | `-f, --file ` | string | required | Agent document (YAML or JSON). Use `-` to read from stdin | | `--strict` | boolean | `false` | Treat schema warnings as errors | Unknown keys in the document produce warnings on stderr but do not block the create unless `--strict` is set. ```bash theme={"dark"} orca agents create -f agent.yaml cat agent.yaml | orca agents create -f - --json ``` ## orca agents update ```bash theme={"dark"} orca agents update [name] -f [--strict] ``` 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). | Flag | Type | Default | Description | | ------------------- | ------- | -------- | --------------------------------------------------------- | | `-f, --file ` | string | required | Agent document (YAML or JSON). Use `-` to read from stdin | | `--strict` | boolean | `false` | Treat schema warnings as errors | ```bash theme={"dark"} orca agents update -f agent.yaml orca agents update old-name -f renamed.yaml ``` ## orca agents delete ```bash theme={"dark"} orca agents delete [name] [--yes] ``` Deletes an agent. Prompts for confirmation in a terminal; in a script `--yes` is required or the command refuses (exit code 2). | Flag | Type | Default | Description | | ------- | ------- | ------- | ---------------------------- | | `--yes` | boolean | `false` | Skip the confirmation prompt | ```bash theme={"dark"} orca agents delete researcher --yes --json ``` ```json theme={"dark"} { "name": "researcher", "deleted": true } ``` ## orca agents publish ```bash theme={"dark"} orca agents publish [name] [--slug ] [--visibility ] [--expose-tool-events] ``` Publishes an agent to the public chat gateway so it can be reached with a chat key. See [Publishing](/concepts/publishing). | Flag | Type | Default | Description | | --------------------------- | ------- | ---------------- | ---------------------------------------- | | `--slug ` | string | server-generated | Public slug | | `--visibility ` | string | server default | One of `private`, `org`, `public` | | `--expose-tool-events` | boolean | `false` | Include tool frames in the public stream | The `--json` output is the published-agent record, including `publicUrl`. After publishing, issue a chat key with `orca agents keys create `. ```bash theme={"dark"} orca agents publish support-bot --slug support --visibility public --json ``` ## orca agents unpublish ```bash theme={"dark"} orca agents unpublish [name] [--yes] ``` Takes a published agent off the gateway. Clients using its chat keys start failing immediately. | Flag | Type | Default | Description | | ------- | ------- | ------- | ---------------------------- | | `--yes` | boolean | `false` | Skip the confirmation prompt | ## orca agents keys Chat keys authenticate callers of a published agent through the gateway. They are separate from [tenant API keys](/cli/reference/keys), which authenticate the CLI itself. ### orca agents keys list ```bash theme={"dark"} orca agents keys list [--limit ] [--offset ] [--all] ``` Lists chat keys for a published agent with their label, creation time, last use, and state (`active`, `expires