kumo-cli

name	kumo-cli
description	Drive Kumo from coding agents and automation through the `kumo` command-line interface. Use when starting, stopping, inspecting, configuring, or troubleshooting Kumo, Mihomo runtime state, profiles, proxies, system proxy, TUN, service mode, or Kumo agent skill installation.

Kumo CLI

Quick Start

Run kumo doctor --json first when diagnosing state. Use --json whenever parsing output. Use the installed kumo command, which should resolve to /usr/local/bin/kumo and then to Kumo.app/Contents/Helpers/kumo. swift run kumo is only for source-tree development checks.

When to Use

• Control Kumo lifecycle, mode, profiles, proxies, system proxy, TUN, or service mode.
• Inspect current runtime state before changing configuration.
• Install, update, or inspect Kumo's bundled agent skills.

Output Contract

• JSON responses use { "ok": true|false, "data": ..., "error": ... } and always include all three keys.
• Exit code 0 means success.
• Exit code 1 means failure; read error when ok is false.
• Prefer stable command names and JSON fields over parsing human-readable output.
• --json stdout is always plain JSON with no ANSI color, progress, or logs.
• Diagnostics and log output go to stderr in text mode.

Discoverability

• kumo --help or kumo -h shows common commands.
• kumo -l shows long command usage.
• kumo <command> -h and kumo help <term> show focused help.
• kumo completion zsh|bash|fish emits shell completion scripts.

Command Workflow

1. Start with kumo doctor --json for a broad snapshot.
2. Use focused read commands such as kumo status --json, kumo proxies --json, or kumo service status --json.
3. Use --dry-run before commands that can change macOS settings or installed skills.
4. After a write command, re-run the narrow status command to verify the result.

Skill Installation Commands

• kumo skills status --json
• kumo skills status --agent cursor --json
• kumo skills install --agent codex --dry-run --json
• kumo skills install --agent all --scope global --json
• kumo skills uninstall --agent cursor --scope global --dry-run --json

Supported agents are cursor, claude, codex, gemini, agents, and all where documented. codex and gemini do not support project scope.

Logging Commands

• kumo logs path
• kumo logs cli --limit 5
• kumo logs clean --dry-run --json

Use --loglevel <silent|error|warn|notice|http|info|verbose|silly> to adjust diagnostic verbosity. Prefer --silent --json for automation that only needs machine-readable results.

Safety Rules

• Do not edit generated runtime YAML unless the user explicitly asks for raw file changes.
• Prefer kumo or the Kumo app over direct writes to Kumo state files.
• Do not pass --force to skill installation unless the user intends to replace an existing skill directory.
• When working inside the Kumo repository, use docs/interfaces/cli-agent-control.md for the detailed CLI contract.