Command line

Install the kumo CLI, run it from any directory, hand it off to scripts and agents.

The kumo command-line tool exposes the same KumoCoreKit facade the GUI uses, as a small ArgumentParser binary. Anything the GUI can do, the CLI can do, and vice versa, so the two can be used interchangeably.

Install the CLI

Two ways to put kumo on PATH.

From the app (recommended)

The first-launch onboarding sheet offers to install the CLI. If that step was skipped, run it again from Settings → General → Install Command Line Tool.

Behind the scenes Kumo creates a symlink at:

/usr/local/bin/kumo  →  /Applications/Kumo.app/Contents/Helpers/kumo

This requires administrator authorization because /usr/local/bin is owned by root. One osascript prompt appears; after that, no further elevation is needed.

Manual install

sudo ln -sf "/Applications/Kumo.app/Contents/Helpers/kumo" /usr/local/bin/kumo

To remove the CLI later:

sudo rm /usr/local/bin/kumo

Kumo only deletes its own symlink. It will not touch a kumo installed via Homebrew or by hand if the path does not match.

Verify the install

kumo --version
kumo status --json

The first command prints the version. The second talks to the running GUI (or starts a controller if needed) and returns the current state as JSON.

File locations

Path	What it is
`/usr/local/bin/kumo`	The symlink.
`/Applications/Kumo.app/Contents/Helpers/kumo`	The real CLI binary inside the app.
`~/Library/Application Support/Kumo/`	Profiles, state, logs, overrides.
`~/Library/Application Support/Kumo/logs/cli/`	Per-invocation CLI debug logs.

See File locations for the full map.

Tab completion

Print and source a completion script for your shell:

kumo completion zsh   > ~/.zsh/completions/_kumo   # zsh
kumo completion bash  > ~/.bash_completion.d/kumo  # bash
kumo completion fish  > ~/.config/fish/completions/kumo.fish  # fish

Then make sure the directory is on the shell's completion path.

Quick start

Try these from any directory:

kumo status --json                              # current state
kumo start                                      # start the core
kumo mode global                                # switch outbound mode
kumo proxies --json | jq '.data[0].name'        # pull the first group
kumo doctor --json                              # one-shot health report

Commands that change system state accept --dry-run to preview the action without executing it. Commands that produce output accept --json to switch from human text to the stable JSON envelope.

What's next

CLI reference — every command, grouped by purpose.
Automation — wire the CLI into Shortcuts, Spotlight, or shell hooks.
Agent skills — give a coding agent safe, structured access to the CLI.

On this page