CLI

Server verbs

The kraft admin verbs that run this machine's server: start, stop, restart, update and reload it, check its health and inspect its templates and harnesses.

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

VerbWhat it does
admin startRuns the server; bare kraft does the same.
admin stopStops the running server.
admin restartStops the server, then starts it the same way.
admin healthThe server's state; exits 1 when degraded.
admin doctorChecks the whole install, one line per check.
admin updateInstalls the newest release.
admin reloadRereads the library, policy.yaml, intake.yaml, workers.yaml and forges.yaml.
admin reindexRescans documents into the search index.
admin install-serviceRegisters Kraft as an OS service; admin uninstall-service removes it.
admin templates lintLints the library's chains.
admin templates showShows one chain.
admin templates libraryLists the library's components.
admin harnessesThe harness profiles and the tasks that select each.
admin initRegisters Kraft's MCP server and skills with an agent.
admin mcpServes the MCP tools over stdio.
admin permission-hookA 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.

FlagTypeDefaultMeaning
--hostbind addressKRAFT_HOST, else access.yamlOverrides KRAFT_HOST, which overrides access.yaml.
--portintegerKRAFT_PORT, else access.yamlOverrides KRAFT_PORT, which overrides access.yaml.
--detach, -dswitchoffForks the server into its own session and returns once it is up.
RefusalCause
Refused to startThe address isn't loopback and no password is set.
Refused to startA 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.

FlagTypeDefaultMeaning
--nowswitchoffStops 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: stop removes 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.

FlagTypeDefaultMeaning
-y, --yesswitchoffDoesn't ask about running in-place steps.
--when-freeswitchoffAsks for one restart at the next free moment instead, whatever restart_when_free says. See Update when Kraft is free. Added in 2.3
WhenThen
The server runs attached to a terminalIt 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 noIt exits 1 and says nothing was restarted.
No server is runningIt 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 activeIt 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.

FlagTypeDefaultMeaning
--forceswitchoffInstalls even when current.
--restartswitchoffAlso 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.
--nowswitchoffInstalls 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
--channelone of stable, rc, beta, alphathe channel of the installed releaseTakes releases from that channel. See Channels.
-y, --yesswitchoffAnswers 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-freeoptional release tagoff; with no tag, the newest release on the channelMarks 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-freeswitchoffDrops 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-free marks the newest release on the channel, --channel choosing 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 update installs now. --cancel-when-free needs one too.
  • Allowed hours apply to a mark and to restart --when-free: they ask for "when free", not "now". kraft admin update and kraft admin restart without 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 --restart across a major version marks the newest release the same way instead of restarting, and says so. update --now installs 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:

--channelTakes
stableFinal releases only. It is how an rc or beta install goes back to finals.
rcRelease candidates and finals.
betaBetas, release candidates and finals.
alphaAnything.

Without --channel, the install follows the channel of the release it is:

InstallFollows
A release candidaterc
A betabeta
An alphaalpha
A final releasestable, 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:

  • installed names the installed version with restart pending, after an update the server hasn't restarted for. It isn't degraded.
  • invalid template, invalid policy and invalid intake name each file that doesn't load, with the reason.
  • storage shows worktree usage against storage.worktrees.limit, and appears only when a limit is set. held makes the status degraded, so the command exits 1. With auto_cleanup set, the line also says how many finished items ended too recently to clean up.
  • forge token names a client: api account whose token is refused, lacks rights, has no value or fails TLS, or expires within 7 days. It makes the status degraded.
  • index error, reattached and orphaned sessions report 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.

FlagTypeDefaultMeaning
--dirpathnone: it asks the serverChecks 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.

FlagTypeDefaultMeaning
--resolvedswitchoffExpands 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.

FlagTypeDefaultMeaning
--repopathevery repoLimits 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.

FlagTypeDefaultMeaning
--reposwitchoffInstalls 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.

FlagTypeDefaultMeaning
--fail-closedswitchoff, or KRAFT_PERMISSION_FAIL_CLOSED=1Denies rather than giving no opinion when Kraft can't answer.
Copyright © 2026