# CLI overview

> Install, authenticate, and the loop you will actually live in

The Zavu CLI drives everything the API does, plus the things only a terminal can:
scaffolding a function, running a tool handler locally, and asking an agent what
it would say before anyone hears it.

```bash
npx zavudev --help
```

No install needed — `npx` fetches it. If you use it daily:

```bash
npm i -g zavudev     # then just `zavu`
```

> **Note:**
> The package and the binary are both `zavudev`. `npx zavudev <cmd>` always runs
> the published version; a global install gives you the same `zavudev <cmd>`.

## Authenticate

```bash
npx zavudev login       # opens your browser, saves a fresh API key
npx zavudev whoami      # which project and team you are pointed at
npx zavudev logout
```

Credentials land in `~/.zavu/credentials.json`.

### Without a browser

For CI, a container, or a coding agent, set the key in the environment instead.
No `login`, no writable home directory:

```bash
export ZAVUDEV_API_KEY=zv_live_…
npx zavudev agents list
```

| Variable | Effect |
|---|---|
| `ZAVUDEV_API_KEY` | Used instead of the saved credentials file |
| `ZAVUDEV_API_BASE_URL` | Points at a non-production deployment |
| `CI` / `ZAVU_NO_ANIMATE` | Disables terminal animation (also off automatically when output is piped) |

## The loop

Most of what you do is free and instant. Only the last step costs anything.

```mermaid
flowchart LR
    A["npx zavudev agents pull"] --> B["edit index.ts"]
    B --> C["npx zavudev fn invoke --tool"]
    C --> D["npx zavudev deploy"]
    D --> E["npx zavudev agents test"]
    E --> B
    E --> F["a real message or call"]
```

| Command | Cost | What it tells you |
|---|---|---|
| `npx zavudev fn invoke --tool` | free | A handler does what you think, without deploying |
| `npx zavudev deploy` | free | Your declarations are live |
| `npx zavudev agents list` | free | What actually landed |
| `npx zavudev agents test` | free | What the agent would reply |
| `npx zavudev calls create` | billed | Everything else |

## Reading the output

**Warnings before the checkmark.** `npx zavudev deploy` prints its summary and any
warnings *above* the success line, and exits non-zero when your declarations
were not synced. Those warnings cover the cases where a green deploy did not do
what it looks like.

**Errors name the field.** A rejected body tells you which one:

```
✗ Invalid request body [invalid_request]
  steps.0.nextStepId: Expected string, received null
```

**`--json` for scripting.** Most list and read commands take it. Tables are for
humans; `--json` is stable.

**Exit codes.** `0` success, `1` failure, `2` a local invoke whose target was
not found. Safe to use in CI.

## Getting help

```bash
npx zavudev --help
npx zavudev agents --help
npx zavudev agents create --help
npx zavudev help agents create   # same thing, any depth
```

## Command groups

| Group | What it covers |
|---|---|
| [`agents`](https://www.zavu.dev/docs/guides/cli/agents) | Create, test, connect, and inspect agents |
| [`functions`](https://www.zavu.dev/docs/guides/cli/functions) (alias `fn`) | Scaffold, deploy, invoke, logs, secrets, rollback |
| `calls` | Voice calls and transcripts — see [agents](https://www.zavu.dev/docs/guides/cli/agents#calls) |
| `messages` | Send and inspect messages |
| `senders` | Sender profiles: numbers, WhatsApp, email |
| `contacts`, `broadcasts`, `templates` | Contacts, campaigns, WhatsApp templates |
| `phone-numbers` | Search, buy, assign |
| `email-domains` | Add and verify sending domains |
| `10dlc`, `addresses`, `documents`, `urls` | Compliance |
| `sub-accounts`, `invitations` | White-label projects and onboarding |
| `balance`, `introspect`, `exports` | Account and utilities |

Every group answers `--help` with its own subcommands and flags. That is the
authority — this site describes the same thing in prose.