CLI reference

CLI reference

The Zavu CLI ships as the zavudev npm package. Run it with npx zavudev <cmd> — nothing to install — or install it globally (npm i -g zavudev) and call the shorter zavu binary. This reference uses the npx zavudev form throughout.

It auto-discovers the function you're in via .zavu/config.json, so most commands "just work" from inside the function directory.

terminalCopy
npx zavudev --help              # full command tree
npx zavudev <cmd> --help        # per-command flags

Auth

npx zavudev login

Opens the browser to /cli-auth, lets you pick the project, saves the API key to ~/.zavu/credentials.json (chmod 0600).

Environment overrides: ZAVU_DASHBOARD_URL, ZAVU_API_URL.

npx zavudev whoami

Shows the project, team, mode, and the last 4 chars of your API key.

terminalCopy
npx zavudev whoami
npx zavudev whoami --json    # machine-readable

npx zavudev logout

Clears ~/.zavu/credentials.json. The API key stays active server-side — revoke it from the dashboard if needed.

Functions

npx zavudev fn init

Scaffold a new function locally and register it in your Zavu project.

terminalCopy
npx zavudev fn init --template restaurant-booking -y
npx zavudev fn init --name "Order Bot" --slug bella -y

npx zavudev fn push

Fast-sync the local source + dependencies to the function's draft. Does NOT trigger a build. Useful for "save my progress" or to keep the dashboard editor showing the latest code.

terminalCopy
npx zavudev fn push                     # uses index.ts
npx zavudev fn push --source bot.ts     # custom entrypoint
npx zavudev fn push --no-deps           # skip package.json upload

npx zavudev fn deploy (alias: npx zavudev deploy)

Bundle, upload, publish. Reads index.ts + package.json from cwd and posts to /v1/functions/:id/deploy. Polls until status=active.

Output after success includes:

• Public URL (if httpEnabled: true).
• Agents and tools synced (+ created, ~ updated, = unchanged, - removed).
• Warnings (collisions, validation issues).

Calling a function over HTTP

With httpEnabled, a function answers on its public URL. What it accepts depends on what the function declares.

A function whose default export is defineFunction receives the POST body as the event. A function that only declares defineAgent and defineTool has no handler for a bare request and answers 404 {"error":"no_handler"} — to reach one of its tools, name it and pass its arguments under arguments:

terminalCopy
curl -X POST https://fn.zavu.dev/{projectId}/{slug} \
  -H 'content-type: application/json' \
  -d '{"tool":"get_order_status","arguments":{"orderId":"ORD-4417"}}'

The key is arguments. args, input, and parameters are accepted by the dispatcher and then reach your handler empty, which surfaces as a tool_error about a property of undefined rather than as a clear rejection.

A project compiled from the eve layout declares no HTTP handler at all, so enabling HTTP on one produces a URL that 404s for every request. Use npx zavudev invoke --tool <name> there.

npx zavudev fn delete (alias: npx zavudev fn rm)

Permanently destroy a function and cascade everything it owns. Always asks for confirmation — you must type the slug back to proceed.

terminalCopy
npx zavudev fn delete                # uses .zavu/config.json (the cwd)
npx zavudev fn delete fn_abc123      # by id, from anywhere

Cascade:

• The deployed function + its logs (async cleanup).
• Triggers, secrets, deployment history.
• Managed agents + tools created via defineAgent / defineTool.
• Auto-provisioned API key is revoked.

Manual agents/tools (created via dashboard or npx zavudev agents create) are not touched.

npx zavudev fn invoke

Run the function locally with a synthetic event. Same TypeScript, same handler, but no cloud round-trip.

terminalCopy
npx zavudev fn invoke --event message.inbound \
  --data '{"from":"+14155551234","text":"hola"}'

# Call one tool handler directly, without an event:
npx zavudev fn invoke --tool lookup_order --args '{"orderId":"ORD-001"}'

<Note>
`fn invoke` runs your code with [Bun](https://bun.sh). Every other command runs
under plain Node.
</Note>
npx zavudev fn invoke --event message.inbound --json '{"from":"+1...","text":"…"}'

npx zavudev fn logs

Stream CloudWatch logs for the deployed function.

terminalCopy
npx zavudev fn logs                      # last 30 min, exit
npx zavudev fn logs --tail               # follow
npx zavudev fn logs --since 2h --filter "ERROR"

Triggers

Functions can subscribe to Zavu events. The defineAgent/defineTool path covers most agent use cases automatically; use triggers for raw events (message.inbound, broadcast.status_changed, etc).

terminalCopy
npx zavudev fn triggers events                                       # list event types
npx zavudev fn triggers list                                         # current triggers
npx zavudev fn triggers add --events message.inbound                 # any sender
npx zavudev fn triggers add --events message.inbound --senders snd_abc,snd_xyz
npx zavudev fn triggers add --events message.inbound --senders any   # explicit "all"
npx zavudev fn triggers toggle <triggerId>                           # pause
npx zavudev fn triggers toggle <triggerId> --off                     # alias for above
npx zavudev fn triggers rm <triggerId>

The cartesian product applies: --events A,B --senders X,Y creates 4 triggers (2 events × 2 senders).

Secrets

Per-function environment variables. Encrypted at rest. Plaintext never leaves the server after set — list only shows the last 4 chars.

terminalCopy
npx zavudev fn secrets list
npx zavudev fn secrets set OPENAI_API_KEY sk-…       # inline
npx zavudev fn secrets set KEY --from-file ./key.txt # from a file
cat key.txt | npx zavudev fn secrets set KEY -       # stdin (safest)
npx zavudev fn secrets unset OLD_KEY                 # alias: npx zavudev fn secrets rm

Changes take effect on the next npx zavudev deploy. list shows synced: no for secrets that haven't been deployed yet.

Messages

Wraps the SDK's messages resource.

terminalCopy
npx zavudev messages send --to +56912345678 --text "Hello"
npx zavudev messages send --to user@example.com --channel email --subject "Hi" --text "Hey"
npx zavudev messages list --limit 20
npx zavudev messages list --status delivered --to +14155551234
npx zavudev messages get <messageId>

Other API mirrors

The CLI mirrors the full REST API — every resource has its own subcommand. Defaults are sane (pagination 20, JSON output via --json flag).

Every command supports --help. Examples:

terminalCopy
npx zavudev senders list
npx zavudev agents get --sender snd_abc
npx zavudev broadcasts send brd_xyz --at 2026-12-25T10:00:00Z
npx zavudev 10dlc brands create --file brand.json

Agents (detailed)

When a function declares an agent with defineAgent, the agent is created on the sender and managed by the function. These commands let you inspect that state — handy for debugging an agent that isn't responding.

npx zavudev agents get

terminalCopy
npx zavudev agents get --sender <senderId>

Returns the full agent config: enabled, provider, model, systemPrompt, triggerOnChannels, triggerOnMessageTypes, stats. If managedByFunctionId is set, this agent is the live mirror of your defineAgent declaration.

npx zavudev agents executions list

terminalCopy
npx zavudev agents executions list --sender <senderId>
npx zavudev agents executions list --sender <senderId> --status error
npx zavudev agents executions list --sender <senderId> --json

Lists the most recent agent runs. Failed executions are surfaced with their errorMessage truncated below the table. Use --json to get the full payload for parsing.

npx zavudev agents executions get

terminalCopy
npx zavudev agents executions get <executionId> --sender <senderId>

Full detail of one execution: errorCode, errorMessage, responseText, tokens, cost, latency, and the inbound/response message IDs. Use this when you spot an error row in the list and want to know exactly what failed.

npx zavudev agents tools list

terminalCopy
npx zavudev agents tools list --sender <senderId>

Lists the tools attached to the agent. After npx zavudev deploy, the tools you declared via defineTool should appear here with managedByFunctionId set.

npx zavudev agents flows list

terminalCopy
npx zavudev agents flows list --sender <senderId>

Lists the conversational flows attached to the agent.

Environment variables

The CLI respects:

Exit codes

• 0 — success
• 1 — error (invalid args, server rejection, network)
• 130 — Ctrl-C (SIGINT)