CLI commands

kdo ships as a single binary named kdo. Every command works from the workspace root (the directory containing kdo.toml). Run kdo --help for the short form, or use the sections below.

Discovery

kdo init

Initialize a workspace. Scaffolds a template on an empty directory, or adopts an existing repo.

kdo init

Side effects: creates kdo.toml, .kdoignore, .kdo/ cache, updates .gitignore. Safe to re-run. It won’t overwrite an existing kdo.toml.

kdo new <name>

Scaffold a new project interactively. Prompts for language, type (lib/bin), and framework.

kdo new my-service
# ? Language: [rust] / typescript / python / anchor / go
# ? Type:     [library] / binary
# ? Framework: [none] / react / next  (TypeScript only)

Creates the project dir with a manifest, source stub, tests stub, and regenerates .kdo/context/.

kdo list

List every project in the workspace.

kdo list
kdo list --format json    # programmatic consumption

kdo graph

Show the dependency graph.

kdo graph                         # indented text
kdo graph --format json           # for tooling
kdo graph --format dot | dot -Tsvg > graph.svg

kdo doctor

Validate workspace health. Parses every manifest, checks for circular deps, verifies .kdo/ is populated, warns about stale context files.

kdo doctor

Exit code is non-zero if any errors are found (warnings don’t fail).

Context

kdo context <project> [--budget N]

Generate a token-budgeted context bundle for one project.

kdo context vault-program --budget 2048
kdo context vault-sdk --format json

Output includes: one-line summary, public API signatures (extracted via tree-sitter), dependency list. Truncates with a visible marker when the budget is exceeded.

kdo source <symbol> [--filter project]

Look up where a symbol is defined. Grep-based, respects .gitignore / .kdoignore.

kdo source initialize_vault
kdo source VaultClient --filter vault-sdk

Works across Rust (fn, struct, enum, trait), TS/JS (function, class, const, interface, type), Python (def, class), Go (func, type).

kdo similar <project> [--limit N]

Find structurally similar projects. Ranks by Jaccard similarity of dependency sets plus a same-language bonus.

kdo similar vault-program
kdo similar vault-sdk --limit 3 --format json

Execution

kdo run <task> [--filter P] [--parallel] [--dry-run] [-- args]

Run a named task. Aliases resolve first. depends_on expands into a linear plan, then executes.

kdo run build                      # topological order, all projects
kdo run test --filter vault-sdk    # one project
kdo run ci --parallel              # independent stages concurrent
kdo run build --dry-run            # print the plan, don't execute
kdo run build -- --release         # pass-through args after --
kdo run b                          # if [aliases] has b = "build"

Flags:

See kdo.toml schema for how task resolution works.

kdo exec <command> [--filter P] [--parallel]

Run an arbitrary shell command in each project directory.

kdo exec "ls src"
kdo exec "wc -l **/*.rs" --filter vault-program
kdo exec "git status" --parallel

kdo affected [--base ref]

List projects affected by changes since a git ref. Uses the dependency graph. Changing a leaf marks every dependent as affected.

kdo affected                    # since main
kdo affected --base HEAD~5
kdo affected --base origin/main --format json

Pair with kdo run test --filter "$(kdo affected --format json | jq -r '.[].name' | head -1)" for CI.

MCP

kdo serve [--transport stdio] [--agent <profile>]

Run the MCP server. Exposes seven tools and a resources/list endpoint.

kdo serve --transport stdio --agent claude
kdo serve --transport stdio --agent openclaw
kdo serve --transport stdio --agent generic   # default

Agent profiles tune:

Loop-detection behavior: N identical (tool, args) calls in a row (per window) return a structured "loop detected" error to the agent. OpenClaw’s window is 3; Claude and generic are 5.

For first-time registration, prefer kdo setup below.

kdo setup <agent> [--global] [--dry-run]

One-command wiring for Claude Code and OpenClaw. Idempotent, atomic writes, honest dry-run.

kdo setup claude --global            # register globally + update ~/.claude/CLAUDE.md
kdo setup claude                     # workspace-local: .claude + ./CLAUDE.md + .kdo/memory
kdo setup openclaw --global          # skill + MCP server at user level
kdo setup openclaw                   # workspace: SKILL.md + AGENTS.md + ~/.openclaw/openclaw.json
kdo setup claude --dry-run           # print every path + content that would change

Claude: shells out to claude mcp add --scope <user|local>, merges a kdo block in CLAUDE.md between <!-- kdo:start --> / <!-- kdo:end --> sentinels (surrounding user content preserved), creates .kdo/memory/MEMORY.md + .kdo/agents/claude/.

OpenClaw: writes SKILL.md (AgentSkills-spec YAML frontmatter), merges {command, args} at JSON Pointer /mcpServers/kdo into ~/.openclaw/openclaw.json (plain JSON, siblings preserved), seeds AGENTS.md + shared memory.

kdo bench [--task <name>] [--iterations N] [--from-log <path>]

Reproducible token-consumption benchmark.

Proxy mode (default): for each task in .kdo/bench/tasks.toml, measures the bytes an fs-walking agent would read against the bytes kdo actually returns from kdo_list_projects + kdo_get_context. Same scope, real files, no mocking.

kdo bench                            # run every task
kdo bench --iterations 3             # median of 3 samples per task
kdo bench --task fix-withdraw        # only tasks whose name contains that substring

Results persist to .kdo/bench/results/<timestamp>.json.

Log mode: parse a real Claude Code session JSONL and sum observed token usage.

kdo bench --from-log ~/.claude/projects/<slug>/<session-id>.jsonl

Prints input_tokens + output_tokens + cache_read_input_tokens across turns. Pair two log runs (with + without kdo) for an empirical delta.

Meta

kdo completions <shell>

Generate shell completions.

kdo completions zsh > ~/.zsh/completions/_kdo
kdo completions bash > /etc/bash_completion.d/kdo
kdo completions fish > ~/.config/fish/completions/kdo.fish
kdo completions powershell > kdo.ps1

kdo upgrade [--version X] [--dry-run]

Self-update. Downloads the latest release binary from GitHub and replaces the running binary atomically (backup-then-rename, auto-rollback on failure).

kdo upgrade                    # latest release
kdo upgrade --version 0.1.0-alpha.4
kdo upgrade --dry-run          # show what would happen

Only supported platforms get prebuilt binaries (x86_64/aarch64 linux, x86_64/aarch64 darwin). For unsupported platforms, use cargo install kdo --version X.

Environment

kdo reads:

• RUST_LOG: standard tracing filter. RUST_LOG=debug kdo init is the first thing to try when discovery misbehaves.
• NO_COLOR: set to disable ANSI colors in output.

Exit codes

Global flags

Not currently standardized. --help works on every subcommand; --version on the root binary. More global flags (like --color, --cwd) are tracked in the roadmap.