◆ concepts · cli

CLI reference.

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

$ kuzy run "<task>"

Run a one-shot task. Streams tool calls to stdout, exits with the agent's status code.

bash

kuzy run "find any flaky tests in the last week and open a fix PR"

$ kuzy schedule "<cron>" "<task>"

bash

kuzy schedule "every Monday 09:00" "post weekly digest in #standup"

$ kuzy spawn @<sub-agent>

Fork a sub-agent with its own sandbox, conversation, and context window.

bash

kuzy spawn @code-explorer --sandbox docker --tools terminal,filesystem

$ kuzy status

In-flight tasks, sub-agents, credit balance, sandbox occupancy.

bash

$ kuzy status
running:    1 task · 4 / 14 tools active
sub-agents: 0 idle · 0 spawning
credits:    87 cr remaining

$ kuzy logs [--tail] [--task <id>]

Live stream every tool call. Filter by task id.

bash

kuzy logs --tail

$ kuzy memory <action>

inspect / search / forget / export the per-workspace memory.

bash

kuzy memory search "credit ledger"
kuzy memory export > workspace-memory.json

$ kuzy skill <action>

list / install / share / remove auto-generated and custom skills.

bash

kuzy skill list
kuzy skill share refactor-credit-flow > flow.skill.yaml

$ kuzy auth <action>

bash

kuzy auth login                 # hosted Kuzy
kuzy auth set-key openai sk-...  # BYOK
kuzy auth whoami

$ kuzy mcp <action>

list / add / test / remove MCP servers.

bash

kuzy mcp test stripe

$ kuzy update

Force an update check.

bash

kuzy update --channel stable

◆ environment variables

KUZY_HOMEOverride the data directory. Default: ~/.kuzy

KUZY_API_BASECustom hosted gateway URL. Default: https://api.kapakgpt.com

KUZY_PROVIDERForce a specific provider (openai, anthropic, hosted, local).

KUZY_SANDBOXDefault sandbox: docker, nsjail, firecracker, none.

KUZY_LOG_LEVELtrace, debug, info, warn, error.

KUZY_NO_TELEMETRYSet to 1 to disable anonymous performance metrics.

KUZY_THEMEdark | light (CLI uses dark by default).

◆ scripting

CI integration

.github/workflows/agent.yml

- name: Auto-fix flaky tests
  run: |
    git clone https://github.com/bulbulogludemir/kuzy.git .kuzy-agent
    cd .kuzy-agent
    python3 -m pip install -e .
    ./kuzy secret set OPENAI_API_KEY ${{ secrets.OPENAI_KEY }}
    ./kuzy --cli "find flaky tests, fix them, open a PR" --json \
      | tee agent-output.json

Cron

bash

# crontab
0 9 * * MON kuzy run "post weekly digest in #standup"

Pipe stdin

bash

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