> ## 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 Naive Managed Agents 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](https://vetta.sh/docs/sdk/typescript.md), which is a thin shell over the [API](https://vetta.sh/docs/api/overview.md) — 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`](https://vetta.sh/docs/cli/auth).

For CI, use an [API key](https://vetta.sh/docs/platform/organizations.md#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's groups are below. `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](https://vetta.sh/docs/cli/auth.md) | Sign in, inspect the credential, sign out. |
| `agent` | [vetta agent](https://vetta.sh/docs/cli/agents.md) | Create, version, roll back, and inspect agents. |
| `team` | [vetta team](https://vetta.sh/docs/cli/team.md) | Compose a coordinator agent with a version-pinned roster. |
| `board` | [vetta board](https://vetta.sh/docs/cli/board.md) | Read and move cards on a team's shared board. |
| `models` | [vetta models](https://vetta.sh/docs/cli/models.md) | List the models an agent can run on. |
| `session` | [vetta session](https://vetta.sh/docs/cli/sessions.md) | Create, send, stream, and manage runs. |
| `computer` | [vetta computer](https://vetta.sh/docs/cli/computer.md) | Provision and control sandboxes, and drive a sandbox's browser (`vetta computer browser`). |
| `browser` | [vetta browser](https://vetta.sh/docs/cli/browser.md) | Saved logins that outlive a session, and who may reopen them. |
| `mobile` | [vetta mobile](https://vetta.sh/docs/cli/mobile.md) | Cloud Android phones: create, screenshot, tap and type, delete. |
| `data` | [vetta data](https://vetta.sh/docs/cli/data.md) | Search the data catalogue, read a tool's input schema, and run it. |
| `social-data` | [vetta social-data](https://vetta.sh/docs/cli/social-data.md) | The same catalogue's social domain: public social media data, no connected account. |
| `media` | [vetta media](https://vetta.sh/docs/cli/media.md) | Generate images and video, cut clips, transcribe, speak; search models and stock photos. |
| `skill` | [vetta skill](https://vetta.sh/docs/cli/skills.md) | Push and version skills. |
| `file` | [vetta file](https://vetta.sh/docs/cli/files.md) | Upload inputs, download published outputs. |
| `app` | [vetta app](https://vetta.sh/docs/cli/apps.md) | Hosted apps by hand, and the builds a project declaration provisioned. |
| `db` | [vetta db](https://vetta.sh/docs/cli/database.md) | A fullstack app's database: SQL, tables, migrations. |
| `storage` | [vetta storage](https://vetta.sh/docs/cli/storage.md) | A fullstack app's object store: buckets and objects. |
| `naive` | [naive](https://vetta.sh/docs/cli/naive.md) | Claim a blueprint repo and apply its `naive.config`. |
| `deploy` | [vetta deploy](https://vetta.sh/docs/cli/deployments.md) | Schedule agents with cron. |
| `webhook` | [vetta webhook](https://vetta.sh/docs/cli/webhook.md) | Subscribe endpoints; rotate secrets; inspect deliveries. |
| `org` | [vetta org](https://vetta.sh/docs/cli/org.md) | Organizations and members. |
| `keys` | [vetta keys](https://vetta.sh/docs/cli/keys.md) | Scoped API keys. |
| `plan` | [vetta plan](https://vetta.sh/docs/cli/billing.md#the-plan) | The monthly plan (Standard or Pro) — the right to use the organization at all. |
| `credits` | [vetta credits](https://vetta.sh/docs/cli/billing.md#the-balance) | Balance, top-ups, and the usage ledger. |
| `audit` | [vetta audit](https://vetta.sh/docs/cli/audit.md) | The control-plane audit trail. |
| `proxy` | [vetta proxy](https://vetta.sh/docs/api/proxy.md#from-the-cli) | The endpoint for a Messages-format client, and a one-shot call. |
| `identity` | [vetta identity](https://vetta.sh/docs/cli/identity.md) | Personas, grants, and OAuth connections. |
| `domain` | [vetta identity domain](https://vetta.sh/docs/cli/comms.md) | Sending/receiving domains. |
| `email` | [vetta identity email](https://vetta.sh/docs/cli/comms.md) | Persona inboxes and messages. |
| `phone` | [vetta identity phone](https://vetta.sh/docs/cli/phone.md) | Persona phone numbers and SMS. |
| `connections` | [vetta identity connections](https://vetta.sh/docs/cli/identity.md#connections) | Connector auth configs. |
| `social` | [vetta identity social](https://vetta.sh/docs/cli/social.md) | Social publishing for a persona. |
| `vault` | [vetta vault](https://vetta.sh/docs/cli/vault.md) | 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](https://vetta.sh/docs/cli/sessions.md#run-exit-codes).

```bash theme={"system"}
vetta run --agent agt_01j8rk2vq6m4zx9kp7n3c5hwae --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](https://vetta.sh/docs/concepts/agents.md#define-an-agent-as-a-file).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.