Server verbs
Bare kraft is the same as kraft admin start. This page covers the server itself; Add-on verbs, Machine verbs and Forge verbs cover the rest of kraft admin. Every verb here accepts --json; the exceptions are in Output format.
Verbs at a glance
| Verb | What it does |
|---|---|
admin start | Runs the server; bare kraft does the same. |
admin stop | Stops the running server. |
admin restart | Stops the server, then starts it the same way. |
admin health | The server's state; exits 1 when degraded. |
admin doctor | Checks the whole install, one line per check. |
admin update | Installs the newest release. |
admin reload | Rereads the library, policy.yaml, intake.yaml, workers.yaml and forges.yaml. |
admin reindex | Rescans documents into the search index. |
admin install-service | Registers Kraft as an OS service; admin uninstall-service removes it. |
admin templates lint | Lints the library's chains. |
admin templates show | Shows one chain. |
admin templates library | Lists the library's components. |
admin harnesses | The harness profiles and the tasks that select each. |
admin init | Registers Kraft's MCP server and skills with an agent. |
admin mcp | Serves the MCP tools over stdio. |
admin permission-hook | A Cursor or Codex worker's pre-tool hook; not run by hand. |
Run the server
admin start
kraft admin start [flags]
Runs the server in the foreground; the same as bare kraft. It takes no --json.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--host | bind address | KRAFT_HOST, else access.yaml | Overrides KRAFT_HOST, which overrides access.yaml. |
--port | integer | KRAFT_PORT, else access.yaml | Overrides KRAFT_PORT, which overrides access.yaml. |
--detach, -d | switch | off | Forks the server into its own session and returns once it is up. |
| Refusal | Cause |
|---|---|
| Refused to start | The address isn't loopback and no password is set. |
| Refused to start | A server is already running against the same run directory. |
The foreground server stops on Ctrl-C, which, like kraft admin stop, leaves the local steps of worktree items running. Use kraft admin stop for one you started elsewhere.
The flags aren't saved: other commands still dial the host and port in KRAFT_HOST and KRAFT_PORT, or in access.yaml. When --host or --port differs from that value, start prints the KRAFT_HOST=H or KRAFT_PORT=N line they need. A wildcard --host such as 0.0.0.0 needs none.
With --detach, if the server exits instead, start prints the error (such as RuntimeError: database schema vN is newer than code vM), the end of that start's output, and the path of server.log.
admin stop
kraft admin stop [flags]
Stops the running server. It takes no --json.
kraft admin stop sends SIGTERM to the process in run/kraft.pid, once it has checked that the process is this Kraft server. The local steps of worktree items keep running in the local worker, and the next start picks them up. stop says how many keep running, and that until Kraft is back nothing answers their permission prompts or enforces their caps.
A step of an item that runs in place stops with the server, and that item stops with a reattach: failure when Kraft starts again; it doesn't resume by itself. See A restart leaves local steps running.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--now | switch | off | Stops every step, the local steps of worktree items included. Each of those items stops with a reattach: failure when Kraft starts again. Added in 2.4 |
- A pidfile naming any other process is stale:
stopremoves it, says so and signals nothing. - It lists the items it stops, without asking. A server that doesn't list them within 2 seconds is stopped anyway.
- A repo's setup command that is running is ended too, with everything it started, so it never runs beside the next server's own run of it. A server that is killed (SIGKILL) can't end it.
admin restart
kraft admin restart [flags]
Restarts the server. It takes no --json.
kraft admin restart stops the server, then starts it again the way it was running: through the service manager if one is installed, back into the background if it was detached.
Like stop, restart leaves the local steps of worktree items running; the new server picks them up. It ends the step of an item that runs in place: pause those items first, and retry any item it stopped. It lists those items and, in a terminal, asks before going on; with none, it asks nothing. -y skips the question.
| Flag | Type | Default | Meaning |
|---|---|---|---|
-y, --yes | switch | off | Doesn't ask about running in-place steps. |
--when-free | switch | off | Asks for one restart at the next free moment instead, whatever restart_when_free says. See Update when Kraft is free. Added in 2.3 |
| When | Then |
|---|---|
| The server runs attached to a terminal | It is stopped, with a note that only that terminal can bring it back, and restart exits 1, since no server is running after it. |
| You answer no | It exits 1 and says nothing was restarted. |
| No server is running | It starts nothing: it says so and exits 1. Start one with kraft admin start. |
| The installed Kraft is a new major version and an item is active | It exits 1 before stopping anything, naming --when-free and stop --now. Added in 2.4 |
Update and reload
admin update
kraft admin update [flags]
Installs the newest release. It takes no --json.
kraft admin update installs the newest release with uv, keeping the vector extra and the Python it runs on, or runs brew upgrade if you installed with Homebrew. On a pipx or pip install, or a source checkout, it installs nothing and prints the command that updates that install.
It warns when another install of kraft sits ahead of this one on PATH, since MCP servers and hooks run the first one.
Before it installs a release of another major version, it lists each loaded Kraft add-on whose requires.kraft that release doesn't meet, and asks Install it anyway? [y/N]. Those add-ons stop loading until each publishes a version for the new major. Answering no, or running with no terminal, installs nothing and exits 1.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--force | switch | off | Installs even when current. |
--restart | switch | off | Also restarts a running server, as restart does. It lists the in-place items and asks before installing anything; answering no exits 1. Across a major version it marks the release for when Kraft is free instead. |
--now | switch | off | Installs and restarts at once, ending every running step, including those an update to a new major version would wait for. Implies --restart. Added in 2.4 |
--channel | one of stable, rc, beta, alpha | the channel of the installed release | Takes releases from that channel. See Channels. |
-y, --yes | switch | off | Answers yes to Install it? for the kraft-default change, accepts the template migration without asking, skips --restart's question, and installs a major release that leaves add-ons out. |
--when-free | optional release tag | off; with no tag, the newest release on the channel | Marks the newest release on the channel, or TAG, to install and restart once nothing is running. See Update when Kraft is free. Added in 2.3 |
--cancel-when-free | switch | off | Drops a release marked with --when-free or on the About page. Added in 2.3 |
A Kraft home from 0.x holds a registry.yaml and no library.yaml: the server starts degraded and refuses new work until you run kraft admin update. See A 0.x home for what the update changes.
What an update changes in kraft-default
Added in 2.6
Before it installs, kraft admin update prints what the new release changes in the built-in kraft-default add-on, or kraft-default: unchanged. When there is a change, a break in one of your overrides or a note, it asks Install it? [y/N] at a terminal; no installs nothing and exits 1. With no terminal it declines the same way.
An unattended update, --when-free or --restart across a major version, doesn't ask. It holds when an override of yours would break or the comparison can't be made, installs nothing and records why: the kraft-default row of kraft admin doctor says to run kraft admin update, read the change and accept it.
Update when Kraft is free
Added in 2.3
kraft admin update --when-free and kraft admin restart --when-free ask the running server to do it once nothing is going on: no agent session is running, and no item is active, waiting, queued or rate_limited. They answer at once; the server installs and restarts later, inside any allowed hours. A mark survives a restart.
- Without a tag,
update --when-freemarks the newest release on the channel,--channelchoosing it. With a tag, it marks that release, a new major version included. It marks nothing when the install is already current. - Both need a running server to hold the request. With none, they say so, exit 1 and name the command that works without one:
kraft admin updateinstalls now.--cancel-when-freeneeds one too. - Allowed hours apply to a mark and to
restart --when-free: they ask for "when free", not "now".kraft admin updateandkraft admin restartwithout the flag stay immediate. - A dev install, and an install not made with uv, can't be marked: the server refuses and says why.
update --restartacross a major version marks the newest release the same way instead of restarting, and says so.update --nowinstalls and restarts at once.
Update Kraft when it is free says what the server does when it gets there and what a failed update puts back.
Channels
--channel takes one of four values:
--channel | Takes |
|---|---|
stable | Final releases only. It is how an rc or beta install goes back to finals. |
rc | Release candidates and finals. |
beta | Betas, release candidates and finals. |
alpha | Anything. |
Without --channel, the install follows the channel of the release it is:
| Install | Follows |
|---|---|
| A release candidate | rc |
| A beta | beta |
| An alpha | alpha |
| A final release | stable, which never takes a pre-release |
Homebrew installs only track stable.
admin reload
kraft admin reload [flags]
Rereads the library, the chains, policy.yaml, intake.yaml, workers.yaml and forges.yaml from disk, with no restart. It also clears the forge token cache, as a Settings save does. It takes no flags.
kraft admin reload rereads the library, the chains, policy.yaml, intake.yaml, workers.yaml and forges.yaml. A policy.yaml, intake.yaml, workers.yaml or forges.yaml that doesn't load is refused and the running one is kept. Reload names it and exits 1, as it does for a chain that doesn't resolve.
It also rereads addons.yaml and addons.lock, and restores in the background any add-on store the lock names and this machine lacks. An add-on file that doesn't read is refused, and the server keeps the add-ons it has. See What loads.
Check the server
admin health
kraft admin health [flags]
Prints the server's state and exits 1 when it is degraded, with the reasons on stdout. It takes no flags.
What health prints
kraft admin health prints the server's state as key value lines, and exits 1 unless status is ok. The line after version and the lines after embeddings appear only when they apply:
installednames the installed version withrestart pending, after an update the server hasn't restarted for. It isn't degraded.invalid template,invalid policyandinvalid intakename each file that doesn't load, with the reason.storageshows worktree usage againststorage.worktrees.limit, and appears only when a limit is set.heldmakes the statusdegraded, so the command exits 1. Withauto_cleanupset, the line also says how many finished items ended too recently to clean up.forge tokennames aclient: apiaccount whose token is refused, lacks rights, has no value or fails TLS, or expires within 7 days. It makes the statusdegraded.index error,reattachedandorphaned sessionsreport the search index and the agent sessions found at startup.
status ok
version 2.0.0
bind 127.0.0.1
documents 214
repos scanned 3
last scan 4m ago
embeddings available
--json prints the GET /api/health answer.
admin doctor
kraft admin doctor [flags]
Runs every check in one pass. Exits 1 if any fails. It takes no flags.
What doctor checks
kraft admin doctor runs every check in one pass, one line per check, and exits 1 if any fails. --json prints the rows. kraft admin health checks only the server.
Each line starts with ok, warn, FAIL or skip, then the check's name and what it found. With storage.worktrees.limit set, a storage row says how much the worktrees use of the limit: ok under the quota, warn over it, and over the limit a failing health row. A row about one repository carries its name, such as setup my-repo. The last line counts them.
ok server http://127.0.0.1:8765
ok health ok
...
ok restart the server (pid 4242) runs the installed version (2.0.0)
ok config /Users/you/.kraft/config
ok access.yaml parses
...
ok spa bundle /usr/lib/kraft/_bundled/web
...
ok repo app /Users/you/code/app
ok forge app github · gh
ok worktrees /Users/you/.kraft/run/worktrees
ok review bots no review bot silent across 3 items
all 26 checks passed
The excerpt cuts the rows marked .... The count is for a running server, the shipped chains with claude on PATH, and one connected repo, app, with its commands declared. It grows with each connected repo and each harness profile the chains select. With no repo connected, a repos none connected row stands in for the repo rows.
Doctor failures lists every row with its fix.
Inspect templates and harnesses
admin templates lint
kraft admin templates lint [flags]
Checks every chain in the library and exits 1 on any error.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--dir | path | none: it asks the server | Checks that directory in-process, with no server and no $KRAFT_HOME. |
kraft admin templates lint checks every chain in the library, including that harnesses.yaml can launch each agent task (a task's profile: naming an agent profile with no model for its harness's provider is an error). It exits 1 on any error, printing each as file:line:column: message.
admin templates show
kraft admin templates show [flags] ID
One chain as written.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--resolved | switch | off | Expands its library components, as a work item would get it. |
kraft admin templates show ID asks the running server. A chain file you just added shows only after admin reload, and --resolved expands the version the server last loaded.
For a chain that extends another, --resolved heads the YAML with comment lines: # extends <parent>, then each node as inherited, added or overridden (with its override paths), then each parent node it removes. Without --resolved, the chain prints as written.
A chain that comes from an add-on is headed # <id> (<addon> <version>), with or without --resolved, and a child add-on's chain ends the parenthesis with ; <mark>: inherited from <parent>, overridden here or added here. A root add-on's --resolved output starts with that header, then # extends.
# team-payments:default (team-payments@acme 1.0.0; overridden here)
# extends plat:default
# verification: inherited
# pci_review: added; pci_review added here
# scan: inherited; security_scan overridden here
A node line ends with <component> overridden here or <component> added here when it is built from a component the child overrides or adds. The parent is named as this instance serves it, here plat.
admin templates library
kraft admin templates library [flags] [ID]
Every library component, its kind and the chains using it. With an ID, one component. It takes no flags.
kraft admin templates library ID takes a component ID such as tasks.implementer, or a unique bare name. A bare name two sections share is refused with each full ID. It prints the component's definition, its users and its lint issues. Without an ID, the ID column of a child add-on's component ends its parenthesis with ; inherited from company, ; overridden here or ; added here, and a single component's id row does the same.
admin harnesses
kraft admin harnesses [flags] [ID]
Every harness profile in harnesses.yaml, its provider, and the library tasks and chains selecting it (a chain's own harness: on a task included), then the agent profiles. With an ID, one harness profile in detail. It takes no flags.
Service, index and agents
admin install-service
kraft admin install-service
Registers Kraft as an OS service (a launchd agent on macOS, a systemd user unit on Linux) that restarts if it exits. Stop a running server first. It takes no flags and no --json. See Run Kraft as a service.
admin uninstall-service
kraft admin uninstall-service
Removes the OS service that install-service registered. It takes no flags and no --json.
admin reindex
kraft admin reindex [flags]
Rescans documents into the search index.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--repo | path | every repo | Limits it to one repo. |
admin init
kraft admin init [flags]
Registers the MCP server and skills with an agent. See Use Kraft from your agent.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--repo | switch | off | Installs into this repo, not your user config. |
admin mcp
kraft admin mcp
Serves the MCP tools over stdio. It takes no flags and no --json.
admin permission-hook
kraft admin permission-hook [flags] HARNESS
What a Cursor or Codex worker's pre-tool hook runs, with HARNESS codex or cursor. You don't run it by hand. It takes no --json. See Permission gate.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--fail-closed | switch | off, or KRAFT_PERMISSION_FAIL_CLOSED=1 | Denies rather than giving no opinion when Kraft can't answer. |
Related
- Doctor failures: the fix for each row
admin doctorcan print. - Run Kraft as a service:
install-service, and keeping the server up across restarts. - Restart Kraft without ending running steps: what
stopandrestartdo to a running step, and how to keep one running. - Upgrade Kraft: when to run
admin update, and how to pin a version.