Appearance
The kadmo commands
Every command of the kadmo CLI, as kadmo --help prints it for version 0.1.0. Install it first: Install the runtime.
| Command | What it does |
|---|---|
kadmo service | Install, check, restart and remove the runtime's login service |
kadmo serve | Run the runtime in this terminal, to try it once (bare kadmo does the same) |
kadmo mcp | The relay over stdio, for an MCP client: it connects to the running runtime |
kadmo status | Ask the running runtime for its status and the browser's |
kadmo doctor | Say what stands between your MCP clients and the browser, each line with its fix |
kadmo list | List the workflows the runtime has |
kadmo run <workflow> | Start a workflow on the running service |
kadmo install [source] | Install a pack, refresh the agent ops, or list what is installed |
kadmo uninstall <domain> | Remove an installed pack |
kadmo search [query] | Search your registries and the public catalogue |
kadmo registry | Add, list, update and remove pack registries |
kadmo init <domain> | Scaffold a new pack |
kadmo validate [path] | Check a pack's structure |
kadmo login --token <token> | Store a personal API token from the Kadmo app |
kadmo publish [source] | Publish a pack to the Kadmo app, or into a local registry |
kadmo plugin | List, install and remove plugins |
Every command takes -h, --help. kadmo -V (or --version) prints the version, and kadmo help <command> prints a command's help.
Run the runtime
The runtime runs once per user, as a login service that kadmo service install sets up (Install the runtime). Every MCP client's kadmo mcp relays to it.
kadmo service
bash
kadmo service install [--replace]
kadmo service status [--json]
kadmo service restart
kadmo service uninstall| Subcommand | What it does |
|---|---|
install | Installs the runtime (kadmo serve) as a login service for the current user only, without administrator or root rights, starts it now and waits until it answers. Run it again after an update: it rewrites the service and restarts the runtime. It refuses when it runs from an npx cache (install the package globally first). When a runtime you started by hand already runs, it names its pid and stops; --replace stops that runtime first. |
status | The service's state (installed, running, its pid, its file and its logs), whether the runtime that answers was started by the service or by hand, and, on a computer that is an agent, the last dependency report. Exit 0 when the service runs the runtime, 1 otherwise. --json prints the same as JSON. |
restart | Restarts the runtime through the service, for example after you edit ~/.kadmo/.env |
uninstall | Stops the runtime and removes the service and its files. ~/.kadmo (packs, settings, logs) stays. |
Which service each system gets, where its file and its logs are, and the command that starts it: Install the runtime. On a Kadmo agent VM, whose runtime is the system unit kadmo.service, status reports that unit read-only, and install, restart and uninstall refuse: the agent's Self Update job changes it.
kadmo serve
bash
kadmo serve [-p <port>] [--host <host>]Runs the runtime in this terminal: the dashboard, the REST API, the extension's WebSocket on /ws, the HTTP MCP endpoint on /mcp, and the socket (a named pipe on Windows) that every kadmo mcp relays through. It runs until you stop it. kadmo with no command, or with only options, runs kadmo serve. The login service runs this same command for you; start it by hand only to try the runtime once.
| Option | Default | Meaning |
|---|---|---|
-p, --port <port> | 9876 | The port to listen on. The Kadmo extension always connects to 9876, so another port runs without a browser. |
--host <host> | 127.0.0.1 (or KADMO_HOST) | The bind address. Any other address requires KADMO_AGENT_TOKEN, or the runtime refuses to start. |
--headless | Printed by the help, but it changes nothing in this release: the dashboard is always served. |
One runtime runs per user. A second one, for example kadmo serve while the login service runs, prints Another Kadmo runtime already runs for this user: pid … with the first one's version and start time, and exits 1. When another program holds port 9876, the runtime still starts: it serves its relays, names the program in every status, and tries the port again every 10 seconds.
At start the runtime fetches the agent ops once when none are installed and an agent token is set (on an agent's machine).
kadmo mcp
bash
kadmo mcpThe relay for an MCP client, over stdio: stdin and stdout carry the protocol's JSON-RPC messages, and diagnostics go to stderr. An MCP client starts it; you do not run it by hand. It starts nothing and binds no port: it connects to the running runtime over its socket and relays every request there, where the tools, the packs and the browser are. Registration recipes for each client are on The MCP server.
| Case | What the relay does |
|---|---|
| No runtime runs | It answers every tool call with the fix, which names kadmo service install when no login service is installed and the command that starts the service when one is. It tries again every 3 seconds; once the runtime answers, it tells the client to list the tools and resources again, so the client needs no restart. |
| The runtime restarts | The call in flight answers that the runtime is unreachable; the relay reconnects and the client lists again. |
| The relay and the runtime are different versions | It relays, writes one line to stderr, and the runtime's status reports the mismatch. |
| The client ends | It exits when its stdin closes. |
kadmo status
bash
kadmo statusAsks http://localhost:9876/health and prints whether the runtime runs (its pid, since when, whether it listens on the extension's port, and whether the login service or a person started it), whether the browser is connected, how many sessions it serves and which one has the tab, any browser problem, and the runtime's version. It always asks port 9876, and it exits 0 whether or not a runtime answers, so read its output rather than its exit code; when none answers, it names the command that starts one.
text
Server Status
Server: Running
Runtime: pid 2210, since 2026-10-17T10:15:02Z, listening on 127.0.0.1:9876, started by the login service (launchd)
Browser: Connected
Sessions: 1; the tab: my-project · Claude Code
Version: <version>kadmo doctor
bash
kadmo doctor [-p <port>] [--json]Says what stands between your MCP clients and the browser, one line per finding, each marked ✓ (fine), ! (a warning) or ✗ (a failure) and naming its fix:
| Line | What it checks |
|---|---|
runtime | Whether a runtime answers on the socket: its pid, version and start time, whether the login service or a person started it, and whether its version differs from this command's |
service | The login service: installed or not, running, its pid. It agrees with kadmo service status |
token | That the run token ~/.kadmo/run/token exists and only you can read it (never its value) |
port | Who holds port 9876: the runtime, another program (named, with its pid), or nobody |
extension | Each extension that connected, with its tab, and any extension the runtime refused |
sessions, lease | The relays and jobs the runtime serves, and which of them holds the browser's tab |
report | On a computer of yours that is an agent, when the runtime last reported itself to the Kadmo app, or why that failed (A computer of yours as an agent) |
-p names another port for the port line. --json prints the report as JSON. The command exits 1 when a line fails.
Workflows
kadmo list
bash
kadmo list [--json]Lists the workflows the runtime has, read from disk: ~/.kadmo/actions/, ~/.kadmo/workflows/ and every installed pack (one copy per workflow id among the packs, by layer). An id in ~/.kadmo/actions/ or ~/.kadmo/workflows/ that a pack also has is listed twice; the file of your own is the one that runs. It prints each workflow's id, title and parameter names. --json prints an array of id, title and params instead. It needs no running service.
kadmo run
bash
kadmo run <workflow> [--param key=value ...] [-p <port>]Starts a workflow on the running runtime. The runtime must be running (the login service, or kadmo serve); otherwise the command prints The Kadmo runtime is not running., names the command that starts it, and exits 1.
| Option | Default | Meaning |
|---|---|---|
--param <params...> | Parameters, each as key=value; repeat the values after one --param or give --param again | |
-p, --port <port> | 9876 | The port of the running runtime |
The command does not wait for the run: it prints Status: started and the run id, and exits 0. The run's steps and result are in the dashboard's run logs, or in the get_run_log MCP tool. A workflow with browser steps needs the extension connected; without it, this release prints Status: undefined, still exits 0, and starts nothing.
bash
kadmo run read_heading --param url=https://example.comPacks
kadmo install
bash
kadmo install <source> [--force]
kadmo install agents [--force]
kadmo install --listInstalls a skill pack. <source> is tried in this order:
| Source | Example | Installed at layer |
|---|---|---|
A git URL (contains ://, starts with git@ or ends in .git) | kadmo install https://github.com/org/packs.git | account, or override when the pack's skill-pack.json says so |
A local directory (starts with ., / or ~, or exists) | kadmo install ./my-pack | account, or override when the pack's skill-pack.json says so |
| A pack in one of your registries, by its exact domain, else its exact name | kadmo install app.example.com | account, or override when the pack's skill-pack.json says so |
A pack in the public catalogue at catalogue_url, by domain | kadmo install app.example.com | library |
A git repository is searched one level deep: every top-level directory with a skill-pack.json is installed. A repository whose root is itself the pack installs nothing (No skill packs found in the repository.); clone it and install the directory instead. When nothing matches, the command prints Pack not found: <source> and exits 1.
| Option | Meaning |
|---|---|
--force | Reinstall a pack already installed at the same layer, or install another version of it. A pack a higher layer holds is kept even with --force. |
--list | List the installed packs: each one's domain, layer, name, version, title and install date, and the ops version beside an ops pack |
Each install prints what it did: Installed, Updated, already installed (same version) or kept with the reason. Which copy wins is explained on The Kadmo runtime.
kadmo install agents is for an agent's machine. It asks the Kadmo app for the agent ops with the agent's token (KADMO_AGENT_TOKEN, else AGENT_TOKEN, else either one from ~/.agent-env), sending the stored ETag so an unchanged set answers at once. --force asks without the ETag. It exits 0 when the ops are current or refreshed, and 1 on a failure, for example no agent token on your own computer. The domain agents comes only from the app: a registry, git repository, directory or catalogue pack with that domain is refused.
kadmo uninstall
bash
kadmo uninstall <domain>Removes the installed pack of that domain from ~/.kadmo/skills/ and from the install record.
kadmo search
bash
kadmo search [query]Lists the packs your registries hold and the packs the public catalogue offers, matching the query against each pack's name, domain, title and description; without a query it lists all of them. A pack in a registry hides a catalogue pack of the same domain. Install one with kadmo install <domain>.
kadmo registry
A registry is a collection of packs: a directory on your computer or a git repository, with an index.json at its root. Adding one installs every pack it holds at the account layer; updating it reinstalls them.
bash
kadmo registry add <url> [--name <name>] [--type local|git]
kadmo registry list
kadmo registry update [name]
kadmo registry remove <name>| Subcommand | What it does |
|---|---|
add <url> | Adds a registry and installs its packs. A git URL is cloned (shallow) to ~/.kadmo/registries/<name>/; git must be installed. --name sets the registry's name (default: derived from the URL), --type forces local or git (default: detected). |
list | Shows each registry with its type, URL, whether it is enabled, and its pack count |
update [name] | Runs git pull in a git registry (a local one is read again) and reinstalls its packs with --force; without a name, every registry |
remove <name> | Removes the registry, uninstalls the packs installed from it, and deletes its clone |
Registries are stored in ~/.kadmo/settings.json.
Make a pack
How a pack is structured is on Creating packs. These commands scaffold, check and publish one.
kadmo init
bash
kadmo init <domain>Creates a directory named after the domain with skill-pack.json, a _skill.md template and _roles/qa.md. It refuses when the directory exists.
kadmo validate
bash
kadmo validate [path]Checks the pack in path (default: the current directory): skill-pack.json must exist with name, version and a valid domain, _skill.md must exist, and every YAML file must parse (errors, exit 1); a missing _roles/ directory is a warning.
kadmo login
bash
kadmo login --token <token>Stores a personal API token from the Kadmo app for kadmo publish. --token is required. The token is checked against the app at app_url first and then written, with the app's address, to ~/.kadmo/auth.json (readable only by you).
kadmo publish
bash
kadmo publish [source] [--registry <dir>] [--dry-run]Without --registry, publishes a pack to the Kadmo app at app_url. source is a pack directory, the domain of an installed pack, or a pack in one of your registries. The pack is validated first; publishing needs kadmo login for the same app, and the app answers 403 when your account does not own the domain.
With --registry <dir>, publishes into a local registry instead: it copies the pack into <dir>/<domain>/, regenerates the registry's index.json, and commits when <dir> is a git repository. With --registry and no source, it validates every pack in the registry and regenerates index.json.
| Option | Meaning |
|---|---|
--registry <dir> | Publish into this local registry directory instead of the app |
--dry-run | Validate and print what would be published, without writing anything |
Plugins
kadmo plugin
bash
kadmo plugin list
kadmo plugin install <source>
kadmo plugin remove <name>| Subcommand | What it does |
|---|---|
list | Lists the installed plugins with their version, description and tools |
install <source> | Installs a plugin from a local directory into ~/.kadmo/plugins/<name>/ |
remove <name> | Removes an installed plugin |
Plugins add MCP tools; restart the runtime (kadmo service restart) to load a change. Each client's kadmo mcp reconnects and lists the tools again. See Plugins and Creating a plugin.