CLI Overview

The naive CLI is built for agentic use — every command returns structured JSON with result data, contextual next steps, and guidance for autonomous operation.

Installation

npm install -g @usenaive-sdk/cli

Output modes

Machine JSON is the default. Human-readable output is opt-in — it is never inferred from isTTY, because a pty-wrapped agent looks exactly like a terminal.

	How
Machine JSON (default)	nothing to do; or `--json` to force it
Human, one command	`--human`
Human, persistently	`naive config output human`
Show the current setting	`naive config show`

--json and --human are the only two global flags. stdout is always JSON.parse-able in machine mode; banners, update notices and deprecation notices go to stderr.

Active user

Naive is multi-tenant. Every subject-scoped command acts on a tenant user. By default that is the API key’s default user, so solo usage needs no setup.

naive use alice_user_id           # select a subject
naive cards list                  # acts on alice
naive use --clear                 # back to the key's default

--user <id> is not a global flag. It exists only on the commands that declare it — approvals, connections, vault, logs, loops, env, module add, agent-profiles provision and mobile proxy-set. On anything else it is an invalid_input error. Use naive use <id> or NAIVE_ACTIVE_USER_ID instead. Full resolution order on the use page.

See users and account-kits for managing tenants.

Active project

A tenant user (a child project) lives in a project. Every organization has a default one, so this is opt-in — with nothing selected the CLI acts exactly where it always did.

naive projects list
naive projects use <project_id>          # persisted; sent as X-Naive-Project-Id
naive use <user_id> --project <id>       # both selections in one command
naive --project <id> users list          # global flag: this command only

See projects.

Agent-Native Output

Every command returns a structured JSON response:

{
  "success": true,
  "action": "email.send",
  "result": { "id": "provider-message-id", "message_id": "naive-message-uuid" },
  "next_steps": [
    { "command": "naive email inbox", "description": "Monitor inbox for replies" },
    { "command": "naive email read naive-message-uuid", "description": "View sent message details" }
  ],
  "hints": [
    "Email sent successfully",
    "Cost: 0.016 credits"
  ],
  "related_commands": ["naive email inbox", "naive email read"]
}

Exit codes

Exit	Meaning
`0`	Success
`1`	The command failed (`success: false` on stdout)
`2`	`naive teams plan --detailed-exitcode` found a diff
`3`	At least one card is `unverified` — opt-in, `naive teams` only, hermes tenants only

Exits 2 and 3 are opt-in and exist only on naive teams. Exit 3 is unreachable for a tenant on the durable runtime (its task states do not include unverified); the command warns on stderr in that case — see exit codes on naive teams.

Configuration

Config is stored at ~/.naive/config.json, written mode 0600 — it holds an API key and a 30-day session token.

{
  "api_key": "nv_sk_live_...",
  "base_url": "https://api.usenaive.ai",
  "agent_id": "uuid",
  "company_id": "uuid",
  "company_name": "Acme Corp",
  "active_user_id": "tu_8f21",
  "output": "human"
}

The config is automatically populated when you register or login:

naive register --name "My Agent" --email me@example.com --password mypassword
# or
naive login --email me@example.com --password mypassword

Environment Variables

Variable	Description
`NAIVE_API_KEY`	Override API key (for CI/headless use)
`NAIVE_BASE_URL`	Override API URL (default: `https://api.usenaive.ai`)
`NAIVE_ACTIVE_USER_ID`	The subject tenant user — how a hosted agent’s container gets its scope
`NAIVE_HUMAN`	Set to `1` for human-readable output
`NAIVE_NO_UPDATE_NOTIFIER`	Suppress the “update available” banner

Command Groups

The durable runtime

Group	Commands	Description
Teams	28 subcommands — `teams submit`, `board`, `runs`, `watch`, `apply`, `approvals`, `decide`, `plan`, `roster`, `cost`, …	Declare a team, send it work, watch it, decide what it asks for. Addressing is `(company, tenant, team)` and `--tenant` is required on every subcommand except `list`. What works depends on the tenant’s runtime: 18 of the 28 serve real rows for a durable tenant, 12 for a hermes tenant; the other 10 answer `501 not_configured` and name what is missing on the runtime that tenant is on.

Knowledge

Group	Commands	Description
Brain	`brain list`, `create`, `connect`, `disconnect`, `rm`, `query`, `recall`, `remember`, `think`, `graph`, `timeline`, `forget`, `add`, `note`, `replace-doc`, `docs`, `doc`, `rm-doc`, `attach`, `consolidate`, `proposals`, `writebacks`, `status`, `metrics`	The company’s brains — which agent works out of which, documents, semantic memory, and the attach/consolidate/propose run loop

Legacy orchestration — deprecated, still working, frozen

Every group below keeps answering exactly as before, prints a deprecation banner on stderr, and is not scheduled for removal.

Group	Commands	Replacement
CEO	`ceo run`, `message`, `status`, `sessions`, `stream`, `team-approve`	`naive teams say` / `show` / `runs` / `watch`
Tasks	`tasks list`, `create`, `show`, `complete`, `block`, `unblock`, `comment`, `run`, `dispatch`, `stats`	`naive teams submit` / `board` / `task` / `unblock`
Objectives	`objectives list`, `create`, `show`, `update`, `pause`, `abandon`	`naive teams submit --task <id>`
Employees	`employees list`, `hire`, `fire`, `configure`	`naive teams roster` (the provisioning verbs have no replacement)
Cron	`cron create`, `list`, `trigger`, `pause`, `remove`	`naive teams schedule` / `unschedule`
Loops	`loops list`, `create`, `get`, `update`, `run`, `remove`	`naive teams schedule`
Memory	`memory add`, `list`, `remove`	`naive brain remember` / `recall` / `forget`

Authentication & account

Group	Commands	Description
Auth	`register`, `login`, `auth google`, `auth email <address>`, `auth session-login`, `auth logout`, `verify` (retired refusal)	Account creation and sign-in. `naive link` no longer exists — see register
Identity	`whoami`, `identity emails`, `identity resources`	Who you are, and what is provisioned
Companies	`companies`, `companies show`, `companies rename`, `companies update`, `companies select`	List and switch companies
Keys	`keys list`, `keys create --name --scope`, `keys revoke <id>`	API key management
Config	`config output <human\|json>`, `config show`	CLI preferences
Status	`status`, `usage --days --limit`	Full status overview; credit transaction history
Billing	`billing plans`, `subscribe`, `upgrade`, `status`, `portal`, `packs`, `topup`	Plans, subscriptions, credit top-ups
Report	`report "<message>" --kind --command --session --stack`	File a bug. Use on `provider_error` / `internal_error` / 5xx — not on self-correctable errors

Project lifecycle (`naive.config.ts`)

Group	Commands	Description
Init / up / down	`init [--force]`, `up [--plan] [--local] [--yes] [--no-deploy]`, `down [--yes]`	Scaffold a `naive.config.ts`, then plan + apply it. `naive up --plan` previews without applying
Agent profiles	`agent-profiles provision <template> --user <id>`, `agent-profiles list`, `get`, `revoke`; `revoke [id]`	Provision and govern a real-world profile per tenant
Modules	`module list`, `module add <name> --user <id>`	Capabilities available to a profile
Environments	`env status`, `env promote --to <env>`, `env reset`, `env use <base_url>`, `env create --tenant --from`	Sandbox/production environments and per-tenant preview sandboxes

Multi-tenant governance

Group	Commands	Description
Projects	`projects list`, `create`, `get`, `use`, `delete`	Scopes inside your organization
Users	`users list`, `create`, `get`, `delete`	Tenant users (child projects)
Account Kits	`account-kits list`, `create`, `assign`	Which primitives and tools a tenant may use
Approvals	`approvals list`, `get`, `approve`, `deny`, `watch`	Human-in-the-loop resolution of gated actions
Connections	`connections list`, `connect`, `disconnect`, `tools`, `execute`	Gmail, Slack, GitHub and 1,000+ apps
Vault	`vault list`, `put`, `reveal`, `delete`, `rotate`	Per-user encrypted credential storage
Logs	`logs tail`, `logs all`	Activity logs, per-user or cross-user
Use	`use <user_id>`, `use --clear`, `use <id> --project <id>`	Select the active subject (and its project)

Primitives

Group	Commands	Description
Apps	`apps list`, `create`, `templates`, `show`, `deploy`, `publish`, `deployments`, `retry`, `secrets`, `domains`, `db`, `vercel`, `supabase`, `delete`	Managed web apps, incl. scoped provider API proxies
Domains	`domains`, `connect`, `setup-records`, `verify`, `search`, `purchase`, `zone-records`, `set-record`, `delete-record`	Domain search, purchase, DNS
Email	`email inboxes`, `create`, `delete`, `send`, `inbox`, `read`	Provisioned inboxes; send and receive
Phone	`phone provision`, `list`, `status`, `send`, `messages`, `read`, `assign`, `release`	US numbers + SMS
Search	`search`, `search url`, `search research`	Web search, URL extraction, deep research
LLM	`llm chat`, `llm models`	Gateway-backed LLM completions
Images	`images generate`, `stock`, `status`, `models`	AI image generation and stock photos
Video	`video generate`, `clip`, `clip-status`, `status`, `models`, `pricing`	AI video generation; see clips
Audio	`audio transcribe`, `transcription`, `speak`, `converse`, `models`, `usage`, `request`	Speech to text, text to speech, native audio turns
Voice / Clone	`voice say`, `list`, `status`, `clone`, `revoke`; `clone generate`, `clone status`	Cloned voices and digital-twin talking video. `voice clone` / `voice revoke` are human-only — they need `naive auth session-login`
Browser	`browser` subcommands	Live cloud browser sessions
Social	`social status`, `activate`, `connect`, `accounts`, `post`, `posts`, `publish`, `analytics`	Social media management
Media	`media list`, `get`, `upload`, `update`, `delete`	Media asset manager
SEO · AEO · App data · E-commerce	`seo`, `aeo`, `app-data`, `ecommerce`	Market-data primitives
Business data	`business google`, `trustpilot`, `tripadvisor`, `social`, `tasks-ready`, `task-get`	Backs travel and reviews
Cards	`cards`, `cardholder`, `create-cardholder`, `update-cardholder`, `create`, `details`, `check-payment`, `retry-issue`, `top-up`, `refund`, `cancel`, `assignments`, `assign`, `unassign`, `log-transaction`, `transactions`	Virtual cards
Trading	`trading connect`, `connections`, `account`, `assets`, `positions`, `order`, `orders`, `close`, `cancel`, `quote`	Brokerage link + trade
Payments · Wallet	`payments`, `wallet show/balance/create/fund/transfer/policy/sweep`	x402 stablecoin payments; agent crypto wallet
Verification · Formation	`verification start/list/status/complete/resend`, `formation naics-codes/submit/list/status/documents/download`	KYC and LLC formation
Compute · Queue · Mobile	`compute`, `queue`, `mobile`	Containers, durable queues, cloud mobile devices
Jobs	`jobs`, `jobs get`, `jobs cancel`	Monitor async generation/research jobs

This table lists groups, not every subcommand. naive <group> --help is authoritative and is generated from the same declaration the command tree is built from. A subcommand that is not in --help does not exist, and an unknown subcommand of a known group fails loudly with unknown_subcommand rather than falling through to the group’s help.

Getting Started

# 1. Create account
naive register --name "Research Agent" --email agent@company.com --password s3cur3pw

# 2. Verify connectivity
naive status

# 3. Discover resources
naive identity emails

# 4. Start using primitives
naive search "latest AI developments"
naive email send --from-inbox <uuid> --to team@company.com --subject "Report" --body "..."
naive images generate "product mockup" --model fal-ai/flux/schnell --wait

Error Handling

Errors also return structured JSON with recovery guidance:

{
  "success": false,
  "action": "email.send",
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this operation",
    "hint": "Add credits at https://usenaive.ai/billing"
  },
  "recovery_steps": [
    { "command": "naive usage", "description": "Check credit usage history" },
    { "command": "naive status", "description": "View current balance and tier" }
  ]
}

Four error codes are minted by the CLI and never by the server, so they will not appear in the API reference: cli_outdated (unknown top-level command), unknown_subcommand, upstream_error (a non-JSON gateway response) and deprecated_command (a retired command that makes no request).

Detailed Help

Every command has comprehensive built-in help with examples:

naive --help                    # Full CLI overview
naive email --help              # Email command group
naive email send --help         # Specific command with examples
naive video generate --help     # Parameters, models, costs

CLI Reference

Durable runtime

Multi-tenant

Legacy orchestration (deprecated)

Primitives

Installation

Output modes

Active user

Active project

Agent-Native Output

Exit codes

Configuration

Environment Variables

Command Groups

The durable runtime

Knowledge

Legacy orchestration — deprecated, still working, frozen

Authentication & account

Project lifecycle (`naive.config.ts`)

Multi-tenant governance

Primitives

Getting Started

Error Handling

Detailed Help

​Installation

​Output modes

​Active user

​Active project

​Agent-Native Output

​Exit codes

​Configuration

​Environment Variables

​Command Groups

​The durable runtime

​Knowledge

​Legacy orchestration — deprecated, still working, frozen

​Authentication & account

​Project lifecycle (naive.config.ts)

​Multi-tenant governance

​Primitives

​Getting Started

​Error Handling

​Detailed Help

Installation

Output modes

Active user

Active project

Agent-Native Output

Exit codes

Configuration

Environment Variables

Command Groups

The durable runtime

Knowledge

Legacy orchestration — deprecated, still working, frozen

Authentication & account

Project lifecycle (`naive.config.ts`)

Multi-tenant governance

Primitives

Getting Started

Error Handling

Detailed Help