CLI overview

The naive 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/cli
naive --version

Upgrading from @usenaive-sdk/vetta-cli? Run npm rm -g @usenaive-sdk/vetta-cli first, because both packages install the same commands. Your saved login carries over.

Authenticate

read -rs KEY && printf '%s\n' "$KEY" | naive login  # a scoped API key, piped on stdin
naive login --email you@acme.com --password ...    # person: exchanges for a session token
naive whoami                                       # show the active principal and organization
naive logout

There is no browser-based login. naive login takes an API key piped on stdin (recommended — it stays out of your shell history), from NAIVE_API_KEY, or from --api-key; or both --email and --password. The organization is learned from the credential, so you never pass an org_ id. naive login on a new --profile points it at the production API unless you pass --api-base-url; other commands refuse a profile you never logged into. See naive auth. For CI, use an API key instead of an interactive login:

export NAIVE_API_KEY=sk_live_...
naive whoami

Each setting is read from its flag first, then the environment, then the stored profile:

Setting	Flag	Environment
API key	`--api-key`	`NAIVE_API_KEY` (the older `VETTA_API_KEY` is read only when `NAIVE_API_KEY` is unset)
Profile	`--profile`	`VETTA_PROFILE`
API base URL	`--api-base-url`	`VETTA_API_BASE_URL`
Organization	`--org`	`VETTA_ORG`

A variable that is exported but empty counts as unset.

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 (naive 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. naive --help prints them (with the top-level aliases below); naive <group> --help lists a group’s commands; naive <group> <command> --help lists that command’s flags.

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

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

Top-level aliases

run, login, logout, and whoami are shorthands for session run, auth login, auth logout, and auth whoami. claim, template, up, init, catalog, and installs are shorthands for the same commands under naive naive — naive up is naive naive up.

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
`naive identity phone send`	Refused `compliance_pending` until the carrier approves the number’s messaging campaign. Inbound works throughout.
`naive identity email send`	Answers `501 feature_not_configured` 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.

naive 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.

naive 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)