> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
npx zavudev --help
```

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

```bash theme={null}
npm i -g zavudev     # then just `zavu`
```

<Note>
  The package is `zavudev` (unscoped) and the binary is `zavu`. Both spellings
  appear below; `npx zavudev <cmd>` and `zavu <cmd>` are the same thing.
</Note>

## Authenticate

```bash theme={null}
zavu login       # opens your browser, saves a fresh API key
zavu whoami      # which project and team you are pointed at
zavu 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 theme={null}
export ZAVUDEV_API_KEY=zv_live_…
zavu 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 theme={null}
flowchart LR
    A["zavu agents pull"] --> B["edit index.ts"]
    B --> C["zavu fn invoke --tool"]
    C --> D["zavu deploy"]
    D --> E["zavu agents test"]
    E --> B
    E --> F["a real message or call"]
```

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

## Reading the output

**Warnings before the checkmark.** `zavu 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 theme={null}
zavu --help
zavu agents --help
zavu agents create --help
zavu help agents create      # same thing, any depth
```

## Command groups

| Group                                             | What it covers                                                       |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| [`agents`](/guides/cli/agents)                    | Create, test, connect, and inspect agents                            |
| [`functions`](/guides/cli/functions) (alias `fn`) | Scaffold, deploy, invoke, logs, secrets, rollback                    |
| `calls`                                           | Voice calls and transcripts — see [agents](/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.