Kumo CLI
Apps & Automationkumo-cliKumo CLI is an Agent Skill for apps & automation published in the ProjectKumo/KumoApp repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ProjectKumo/KumoApp/blob/HEAD/Sources/KumoCoreKit/Resources/KumoAgentSkills/skills/kumo-cli/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kumo-cli, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
0means success. - Exit code
1means failure; readerrorwhenokis false. - Prefer stable command names and JSON fields over parsing human-readable output.
--jsonstdout is always plain JSON with no ANSI color, progress, or logs.- Diagnostics and log output go to stderr in text mode.
Discoverability
kumo --helporkumo -hshows common commands.kumo -lshows long command usage.kumo <command> -handkumo help <term>show focused help.kumo completion zsh|bash|fishemits shell completion scripts.
Command Workflow
- Start with
kumo doctor --jsonfor a broad snapshot. - Use focused read commands such as
kumo status --json,kumo proxies --json, orkumo service status --json. - Use
--dry-runbefore commands that can change macOS settings or installed skills. - After a write command, re-run the narrow status command to verify the result.
Skill Installation Commands
kumo skills status --jsonkumo skills status --agent cursor --jsonkumo skills install --agent codex --dry-run --jsonkumo skills install --agent all --scope global --jsonkumo 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 pathkumo logs cli --limit 5kumo 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
kumoor the Kumo app over direct writes to Kumo state files. - Do not pass
--forceto skill installation unless the user intends to replace an existing skill directory. - When working inside the Kumo repository, use
docs/interfaces/cli-agent-control.mdfor the detailed CLI contract.