Calling the Kition agent from CLI

Installation

The CLI shares a binary with the desktop app — install the desktop and kition is already on your PATH. For server-only setups, install the standalone CLI package:

# macOS / Linux via the install script
curl -fsSL https://get.kition.ai/cli | sh

# Or with Homebrew
brew install kition-ai/tap/kition

# Verify
kition --version
kition doctor   # checks vault, providers, MCP servers

Basic commands

# Run a one-shot prompt against the default vault
kition run --prompt "summarize this week's notes"

# Pick a vault explicitly
kition --vault ~/Work run --prompt "draft standup from today's commits"

# Pin a model
kition run --model claude-opus-4-7 --prompt "review staged diff"

# Pipe stdin in
git diff --staged | kition run --prompt "write a commit message for this diff"

# Resume a previous session by id
kition run --resume sess_8h2k --prompt "now publish the post"

# List recent sessions
kition sessions list --limit 10

Output formats

Default output is human-readable markdown. Scripts usually want --json for a structured stream — every message, tool call, token usage line, and final text.

--stream emits NDJSON (one event per line), perfect when you want progress signals from long-running tasks.

kition run --json --prompt "list TODOs in src/" \
  | jq -r '.events[] | select(.type=="tool_result") | .content'

kition run --stream --prompt "..." # NDJSON, one event per line
kition run --output-file out.md --prompt "..." # write final text to file

# Capture only the cost summary
kition run --json --prompt "..." | jq '.usage'

Exit codes

• 0 — success
• 1 — model / network error (retry-safe)
• 2 — hook denied (compliance gate, retrying is pointless)
• 3 — tool call failed
• 4 — config error (vault / provider / permission)
• 5 — context window exhausted (split the task or pick a longer-context model)
• 130 — user interrupt (SIGINT)

Using it in CI

GitHub Actions, GitLab CI, any runner — the trick is injecting the API key via secrets and checking out the vault. Minimal PR-review workflow below.

name: agent-review
on: pull_request
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kition-ai/setup-kition@v1
        with: { version: latest }
      - run: |
          git fetch origin ${{ github.base_ref }}
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/diff
          kition run \
            --vault ./.kition \
            --prompt "Review this diff. Flag bugs only." \
            --input-file /tmp/diff \
            --output-file /tmp/review.md
        env:
          KITION_API_KEY: ${{ secrets.KITION_API_KEY }}
      - uses: actions/upload-artifact@v4
        with: { name: review, path: /tmp/review.md }

Common gotchas

• The vault path must be writable — remember to cd in after actions/checkout
• Hooks fire in CI too — use --no-hooks to skip (dev-only escape hatch)
• Long prompts: switch to --input-file or stdin to dodge shell escaping
• In cron, set KITION_NONINTERACTIVE=1 so ask-mode tools fail fast instead of blocking
• Never commit API keys to the vault — keep them in CI secrets or the OS keychain
• After CI, kition sessions prune --older-than 7d keeps history from snowballing