vonzio CLI

vonzio — a terminal client for Vonzio. Authenticate to any Vonzio instance (default https://app.vonz.io), list and run your agents, and start or resume a chat and keep talking from the terminal with live token streaming.

Install

npm i -g @vonzio/cli      # then: vonzio …  (or the short alias: vz …)
# or run without installing:
npx @vonzio/cli login

vz is a built-in shorthand for vonzio (same binary).

Requires Node ≥ 22.

Quick start

vonzio login                       # device-flow auth (opens the browser)
vonzio chat                        # start a new chat — streams live
vonzio chat "summarize my week"    # new chat, sends the first message
vonzio agents                      # list your agents

Commands

| Command | What it does | |---|---| | vonzio login | Sign in to an instance via device flow (RFC 8628). Works headless/over SSH. | | vonzio logout | Remove the stored token for the current/selected instance. | | vonzio whoami | Show the authenticated account + instance. | | vonzio agents | List your agents. | | vonzio run <agent> "<task>" [--wait] | Run a one-shot task. --wait blocks and prints the result. Task primitive: --schema (structured output), --context smart --files / --workspace <git-url> (give the agent relevant code), and bounds --model/--effort/--max-turns/--budget/--timeout/--allowed-tools/--egress. CI-friendly with --json. | | vonzio chat [workspace-or-prompt] | Start a new chat (optionally with a first message), or resume a <workspace-id>. --agent <id\|name> picks the agent for a new chat. | | vonzio session <id> | Workspace metadata + activity summary (turns, tool calls, tokens). | | vonzio logs <id> | Full event timeline — everything, not just chat turns (--json to pipe). | | vonzio files <id> [path] | Browse the workspace filesystem (/workspace). | | vonzio cat <id> <file> | Print a file from the workspace. | | vonzio pull <id> [dest] | Download the whole workspace locally (defaults to ./<name>). | | vonzio ops | Platform pool / containers / health (admin). |

Run vonzio <command> --help for details.

chat — the flagship

vonzio chat                         # new empty chat with your default agent
vonzio chat --agent DeepResearch    # new chat with a specific agent
vonzio chat "why is the sky blue"   # new chat, auto-sends that message
vonzio chat 36be1271-7fcb-…         # resume / take over an existing workspace

A new chat prints its session id + a web link, so you can jump to the dashboard or resume later from any terminal. In-chat: type to send a turn, Ctrl-C cancels an in-flight turn (again to exit).

Multiple instances

The default instance is https://app.vonz.io. Point at another with --instance (stored under its own profile, so it won't clobber the default):

vonzio --instance https://vonzio.mycorp.com login
vonzio --instance https://vonzio.mycorp.com agents

CI / scripting

Skip interactive login with env vars; use --json for machine-readable output:

export VONZIO_BASE_URL=https://app.vonz.io
export VONZIO_TOKEN=rc_…            # an API token (Settings → API tokens)
vonzio run code-review "review the diff" --wait --json

Exit codes: 0 success · 1 runtime/task failure · 2 bad usage · 3 auth required.

run as a task primitive (structured output + context)

run is the composable building block for automation — give the agent a schema and the relevant code, get machine-readable output back:

# Structured output: the agent fills a JSON Schema → printed under `.structured`
vonzio run reviewer "Review this diff: $(git diff)" --wait --json --schema review.json

# Smart context: pack the changed files + their first-order deps into the agent's
# workspace (not just the diff). --files are read from the local checkout.
vonzio run reviewer "Review the changes" --wait --json --schema review.json \
  --context smart --files "$(git diff --name-only main...HEAD | paste -sd,)"

# Full-repo context instead: attach a git repo (PAT via --git-token or $VONZIO_GIT_TOKEN)
vonzio run reviewer "Audit the auth module" --wait --workspace https://github.com/org/repo --ref main

# Read-only + bounded (good defaults for reviewing untrusted code in CI)
vonzio run reviewer "…" --wait --allowed-tools Read,Grep,Glob --max-turns 6 --budget 1.00

These primitives are what the vonzio review GitHub Action composes — the CLI stays generic; "review" is a product built on top.

How it works

• Device-flow OAuth (RFC 8628) — the token is a normal user-scoped API token, visible + revocable under Settings → API tokens.
• Two transports — REST (/v1) for everything non-realtime; WebSocket (/v1/stream) for chat (live token streaming, tool calls, usage).
• Depends only on the public /v1 contract, so it works against any instance/version.

See docs/SPEC.md for the wire protocol and docs/IMPLEMENTATION.md for the build tracker.

License

MIT