> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Install, authenticate, and learn the global conventions of the vetta CLI.

The `vetta` CLI is the primary way to operate Vetta from a terminal, scripts, and CI. It defaults to machine-readable JSON so it composes with `jq`; pass `--human` for tables.

It is a thin shell over the [TypeScript SDK](/docs/sdk/typescript), which is a thin shell over the [API](/docs/api/overview) — one route table, three spellings. Every command below has a method with the same name and a page in the API reference.

## Install

```bash theme={"system"}
npm i -g @usenaive-sdk/vetta-cli
vetta --version
```

## Authenticate

```bash theme={"system"}
vetta login --api-key sk_live_...                  # CI: a scoped API key
vetta login --email you@acme.com --password ...    # person: exchanges for a session token
vetta whoami                                       # show the active principal and organization
vetta logout
```

There is no browser-based login. `vetta login` takes **either** `--api-key`, **or** both `--email` and `--password`; the organization is learned from the credential, so you never pass an `org_` id. See [`vetta auth`](/docs/cli/auth).

For CI, use an [API key](/docs/platform/organizations#api-keys) instead of an interactive login:

```bash theme={"system"}
export VETTA_API_KEY=sk_live_...
vetta whoami
```

## Global flags

| Flag                   | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| `--json`               | Machine-readable JSON output (default).                      |
| `--human`              | Human-friendly tables and colors.                            |
| `--org <id>`           | Run against a specific organization.                         |
| `--api-key <key>`      | Override the stored credential.                              |
| `--profile <name>`     | Use a named credential profile.                              |
| `--api-base-url <url>` | Point at a different API deployment.                         |
| `--version`            | Print the CLI and API versions.                              |
| `--help`               | On a group, list its commands; on a command, list its flags. |

## Conventions

The CLI is consistent so command names transfer between groups:

* **Verbs & pluralization.** Resource groups are singular (`agent`, `session`, `webhook`); list/get/create/update/delete are the shared verbs; `members` live **under `org`** (`vetta org members …`).
* **Ids** use the canonical `xxx_` prefixes on the wire (`agt_`, `ses_`, `cmp_`, `skl_`, `dep_`, `whk_`, `led_`, `key_`, `org_`, `usr_`).
* **Pause/resume vs enable/disable.** A *running* thing is paused/resumed (a computer sandbox, a deployment schedule). A *config flag* is enabled/disabled (a webhook endpoint). They never mix.
* **Unknown flags are an error.** A flag a command does not accept exits `2` before anything is sent, and the message lists the flags that command does take. A misspelled filter can never quietly widen your query.
* **Money.** `--budget-usd`, `--max-task-usd`, and `--usd` take decimal-dollar strings and convert client-side to integer micro-USD; JSON output amounts are integer `*_micro_usd` (`1 USD = 1_000_000` micro-USD).

## Command groups

The CLI ships **30 groups**. `vetta --help` prints them (with the four aliases below); `vetta <group> --help` lists a group's commands; `vetta <group> <command> --help` lists that command's flags.

| Group         | Reference                                               | What it does                                                                               |
| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `auth`        | [vetta auth](/docs/cli/auth)                                 | Sign in, inspect the credential, sign out.                                                 |
| `agent`       | [vetta agent](/docs/cli/agents)                              | Create, version, roll back, and inspect agents.                                            |
| `team`        | [vetta team](/docs/cli/team)                                 | Compose a coordinator agent with a version-pinned roster.                                  |
| `board`       | [vetta board](/docs/cli/board)                               | Read and move cards on a team's shared board.                                              |
| `models`      | [vetta models](/docs/cli/models)                             | List the models an agent can run on.                                                       |
| `session`     | [vetta session](/docs/cli/sessions)                          | Create, send, stream, and manage runs.                                                     |
| `computer`    | [vetta computer](/docs/cli/computer)                         | Provision and control sandboxes, and drive a sandbox's browser (`vetta computer browser`). |
| `browser`     | [vetta browser](/docs/cli/browser)                           | Saved logins that outlive a session, and who may reopen them.                              |
| `media`       | [vetta media](/docs/cli/media)                               | Generate images and video, cut clips, transcribe, speak; search models and stock photos.   |
| `skill`       | [vetta skill](/docs/cli/skills)                              | Push and version skills.                                                                   |
| `file`        | [vetta file](/docs/cli/files)                                | Upload inputs, download published outputs.                                                 |
| `app`         | [vetta app](/docs/cli/apps)                                  | Hosted apps by hand, and the builds a project declaration provisioned.                     |
| `db`          | [vetta db](/docs/cli/database)                               | A fullstack app's database: SQL, tables, migrations.                                       |
| `storage`     | [vetta storage](/docs/cli/storage)                           | A fullstack app's object store: buckets and objects.                                       |
| `naive`       | [naive](/docs/cli/naive)                                     | Claim a blueprint repo and apply its `naive.config`.                                       |
| `deploy`      | [vetta deploy](/docs/cli/deployments)                        | Schedule agents with cron.                                                                 |
| `webhook`     | [vetta webhook](/docs/cli/webhook)                           | Subscribe endpoints; rotate secrets; inspect deliveries.                                   |
| `org`         | [vetta org](/docs/cli/org)                                   | Organizations and members.                                                                 |
| `keys`        | [vetta keys](/docs/cli/keys)                                 | Scoped API keys.                                                                           |
| `plan`        | [vetta plan](/docs/cli/billing#the-plan)                     | The monthly plan — the right to use the organization at all.                               |
| `credits`     | [vetta credits](/docs/cli/billing#the-balance)               | Balance, top-ups, and the usage ledger.                                                    |
| `audit`       | [vetta audit](/docs/cli/audit)                               | The control-plane audit trail.                                                             |
| `proxy`       | [vetta proxy](/docs/api/proxy#from-the-cli)                  | The endpoint for a Messages-format client, and a one-shot call.                            |
| `identity`    | [vetta identity](/docs/cli/identity)                         | Personas, grants, and OAuth connections.                                                   |
| `domain`      | [vetta identity domain](/docs/cli/comms)                     | Sending/receiving domains.                                                                 |
| `email`       | [vetta identity email](/docs/cli/comms)                      | Persona inboxes and messages.                                                              |
| `phone`       | [vetta identity phone](/docs/cli/phone)                      | Persona phone numbers and SMS.                                                             |
| `connections` | [vetta identity connections](/docs/cli/identity#connections) | Connector auth configs.                                                                    |
| `social`      | [vetta identity social](/docs/cli/social)                    | Social publishing for a persona.                                                           |
| `vault`       | [vetta vault](/docs/cli/vault)                               | Write-only credentials agents use but never see.                                           |

`domain`, `email`, `phone`, `connections`, and `social` are reached as three-word `vetta identity <group> <command>` spellings.

### Top-level aliases

`run`, `login`, `logout`, and `whoami` are shorthands for `session run`, `auth login`, `auth logout`, and `auth whoami`.

### Capabilities that are present but blocked

A command can exist and still be refused by something outside the platform. These are reported, not retried around:

| Surface                     | State                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `vetta identity phone send` | Refused `compliance_pending` until the carrier approves the number's messaging campaign. Inbound works throughout. |
| `vetta identity email send` | Answers `501 not_implemented` where no comms provider is configured for the deployment.                            |

## Convenience: run

The `run` command is create-session + send + stream + wait-for-idle in one line. It exits with a code derived from the terminal `stop_reason` (non-zero on `awaiting_*`, `budget_paused`, `max_iterations`, `interrupted`, or `error`), so CI can branch on the outcome — see the [exit-code table](/docs/cli/sessions#run-exit-codes).

```bash theme={"system"}
vetta run --agent nightly-triage --message "Summarize what changed in main today" --window priority
```

## Declarative config (GitOps)

Agents are declarative, so you can keep them as checked-in **`.agent.yaml`** files and sync them from CI. `apply` upserts by name (last write wins); `show --format yaml` exports the live config for round-tripping.

```bash theme={"system"}
vetta agent apply -f ./agents/            # sync every *.agent.yaml
```

See [Define an agent as a file](/docs/concepts/agents#define-an-agent-as-a-file).