CLI overview

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, which is a thin shell over the API — one route table, three spellings. Every command below has a method with the same name and a page in the API reference.

Install

npm i -g @usenaive-sdk/vetta-cli
vetta --version

Authenticate

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. For CI, use an API key instead of an interactive login:

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

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.

vetta agent apply -f ./agents/            # sync every *.agent.yaml

See Define an agent as a file.

Getting started

Building & running

Organization

Identity

CLI overview

Install

Authenticate

Global flags

Conventions

Command groups

Top-level aliases

Capabilities that are present but blocked

Convenience: run

Declarative config (GitOps)

​Install

​Authenticate

​Global flags

​Conventions

​Command groups

​Top-level aliases

​Capabilities that are present but blocked

​Convenience: run

​Declarative config (GitOps)

Install

Authenticate

Global flags

Conventions

Command groups

Top-level aliases

Capabilities that are present but blocked

Convenience: run

Declarative config (GitOps)