◆ concepts · cli

CLI reference.

Same agent as the desktop app. Pipe it, script it, schedule it from any shell.

$ kuzy

Launch the default UI (Ink — React-in-the-terminal). Streaming tool cards, todo sidebar, worker panel.

bash

kuzy

$ kuzy --cli

Plain Rich-based REPL. Same agent, no Ink UI. Use this in scripts, over SSH, or when Bun isn't installed.

bash

kuzy --cli

$ kuzy --bridge

Run as a stdio JSON-Lines bridge. The Electron desktop talks to Python this way; you can pipe to it from any host.

bash

kuzy --bridge < requests.jsonl > events.jsonl

$ kuzy --mcp-serve

Expose Kuzy as an MCP server. Any compatible MCP client can query session history, skills, and memory.

bash

kuzy --mcp-serve

$ kuzy onboarding

Interactive first-run setup. Detects available providers, helps you store an API key.

bash

kuzy onboarding

$ kuzy provider {status | set <id>}

Show which providers Kuzy can see, or pin one as active.

bash

kuzy provider status
kuzy provider set anthropic

$ kuzy secret {set | get | del} <KEY> [VALUE]

Store provider keys in the macOS Keychain (or 0o600 file fallback). Reads from env first, Keychain second, fallback file third.

bash

kuzy secret set OPENROUTER_API_KEY sk-or-v1-...
kuzy secret get OPENROUTER_API_KEY
kuzy secret del OPENAI_API_KEY

$ kuzy telemetry {on | off | status}

Toggle local-only telemetry (writes to ~/.henry/telemetry.jsonl). Never leaves your machine.

bash

kuzy telemetry status

$ kuzy update-check

Compare your version to the latest GitHub release tag. Cached for 24h at ~/.henry/update_check_cache.json.

bash

kuzy update-check

$ kuzy --version

Print the version from pyproject.toml.

bash

kuzy --version

◆ environment variables

HENRY_PYTHONPython interpreter the launcher should use. Default: python3 on PATH.

HENRY_UIOverride the UI: ink (default) | legacy (Textual) | cli (Rich).

OPENROUTER_API_KEYDefault BYOK provider key. Kuzy hosted users can leave this unset.

KUZY_API_KEYsk-kuzy-... token issued by the hosted gateway. Used in place of BYOK keys.

KUZY_API_URLHosted gateway origin. Default: https://api.kuzy.ai.

KUZY_OUTBOUND_MESSAGES_PER_MINRate limit for outbound messages (Slack, Telegram, WhatsApp). Default: 5.

HENRY_PROGRAM_NAMEInternal — set by the `kuzy` symlink so help text reads "kuzy" not "henry".

◆ scripting

One-shot via the bridge

The bridge mode reads newline-delimited JSON requests on stdin and writes events on stdout. Pipe a single user-message request in and tail events out.

bash

echo '{"type":"user_message","content":"review my staged diff"}' \
  | kuzy --bridge

Cron-style scheduling

Inside a session, ask the agent to schedule itself with the set_reminder tool. For OS-level cron, wrap the bridge:

bash

# crontab — Monday 09:00, drop a weekly summary in the active session log
0 9 * * MON  echo '{"type":"user_message","content":"post weekly digest"}' | kuzy --bridge >> ~/kuzy.log

Pipe stdin

bash

git diff main...HEAD | kuzy --cli "review this diff against our team standards"