CLI

Add-on verbs

The kraft admin addon verbs: add collections, install, update, remove and validate add-ons.

kraft admin addon manages add-ons and the collections they come from. The server, machine and forge verbs are on their own pages. Every verb here accepts --json; the exceptions are in Output format.

Verbs at a glance

VerbWhat it does
admin addon collection addAdds a collection; installs nothing. Added in 2.1
admin addon collection listLists the collections and what each publishes. Added in 2.1
admin addon collection updateFetches the newest catalogue. Added in 2.1
admin addon collection auto-updateSets a collection's auto-update. Added in 2.1
admin addon collection removeForgets a collection. Added in 2.1
admin addon installInstalls an add-on and its missing ancestors, after a review. Added in 2.1
admin addon updateUpdates installed add-ons, one review per tree. Added in 2.1
admin addon auto-updateSets one add-on's auto-update. Added in 2.1
admin addon enableLoads an installed add-on. Added in 2.1
admin addon disableKeeps an add-on installed but not loaded. Added in 2.1
admin addon uninstallRemoves an installed add-on. Added in 2.1
admin addon listLists the installed add-ons. Added in 2.1
admin addon validateChecks a collection or add-on directory; installs nothing. Added in 2.1

Install and update add-ons

Added in 2.1

admin addon collection add

kraft admin addon collection add [flags] SOURCE

Adds a collection from owner/repo (GitHub), a git URL or a directory. Installs nothing.

FlagTypeDefaultMeaning
--refbranch, tag or committhe default branchWhat the collection follows.
--auto-updateswitchoffEvery add-on installed from it updates itself.
--replaceswitchoffMoves one already added from another source. The next update reviews it. Added in 2.5

Move a collection to another source

Added in 2.5

kraft admin addon collection add SOURCE --replace moves a collection already added under the same name to another repository or directory: a fork, a mirror or a local checkout. It writes the new source to addons.yaml, and changes neither the lock nor the store.

The installed add-ons keep what they locked until kraft admin addon update shows the move, as collection URL changed: <old> -> <new>, and you accept it. From one directory to another, the update shows only what changed in the add-ons' files.

The move takes the new source whole: the old --ref is dropped, auto_update is kept from one git source to another, and a directory never auto-updates. Without --replace, adding a taken name from another source is refused. To follow another branch of the same repository, collection add SOURCE --ref REF is enough.

admin addon collection list

kraft admin addon collection list [flags]

Each collection, its source and the add-ons it published when last fetched. No network. It takes no flags.

admin addon collection update

kraft admin addon collection update [flags] [NAME]

Fetches the newest catalogue of NAME, or with no name of every collection from git. Installed add-ons don't change. It takes no flags.

admin addon collection auto-update

kraft admin addon collection auto-update [flags] NAME on|off

Sets whether every add-on installed from the collection updates itself. It takes no flags.

admin addon collection remove

kraft admin addon collection remove [flags] NAME

Forgets a collection. It takes no flags.

RefusalCause
RefusedOne of its add-ons is installed.

admin addon install

kraft admin addon install [flags] ADDON@COLLECTION

Installs an add-on, and any of its ancestors that isn't installed, after one review.

FlagTypeDefaultMeaning
--asnamespacethe add-on's ownInstalls the add-on under another namespace.
--auto-updateswitchoffThe add-on updates itself.
--re-installswitchoffTakes the newest commit of an installed one, even at an unchanged version.
-y, --yesswitchoffAccepts the review without asking.

Add a collection and install from it

kraft admin addon collection add SOURCE records a collection in addons.yaml under the name its collection.json declares. owner/repo is written as its full GitHub URL. kraft admin addon install ADDON@COLLECTION then fetches the add-on, checks it against this instance, and prints a review: what can change how far a run reaches first, then the rest. Nothing is installed until you accept it. -y accepts without asking; with no terminal and no -y the install is declined.

Any ancestor the add-on builds on that isn't installed is installed with it, in the same review; a disabled one is refused with the kraft admin addon enable to run.

--as ALIAS installs the add-on under another namespace. --re-install takes the commit the collection's ref names now, even when the add-on's version hasn't changed.

admin addon update

kraft admin addon update [flags] [ADDON@COLLECTION ...]

Updates the named add-ons, with their installed relatives' waiting updates, or all of them, after one review per tree of related add-ons.

FlagTypeDefaultMeaning
-y, --yesswitchoffAccepts every review. Exclusive with --check.
--checkswitchoffChanges nothing; the exit code says what it found.

Update add-ons

kraft admin addon update reviews every installed add-on that has an update: its version changed (its files, for a directory collection), or you changed its alias, ref or collection URL by hand. Add-ons that build on each other share one review.

An add-on that fails a check is reported and the others go on. A change that would break one of your own chains, a default_chain in repos.yaml or an intake.yaml schedule is refused and names the reference.

update exits 0 only when everything asked for was applied or current, and 1 when an update was refused, declined, held or failed, a held relative's included.

--check prints the reviews and changes nothing. Its exit code tells a scheduled job what it found:

--check exit codeMeaning
0Every add-on is current.
1An update is waiting or held by a range.
2An update would be refused, a relative's that breaks a chain included.
3It couldn't check.

An add-on set to auto-update is checked after each server start and once a day while the server runs. kraft admin addon list marks it auto-update (collection) or auto-update (addon); its last outcome is on the add-on updates row of kraft admin doctor and in GET /api/health. See Auto-update.

admin addon auto-update

kraft admin addon auto-update [flags] ADDON@COLLECTION on|off

Sets one add-on's auto-update. It takes no flags.

RefusalCause
RefusedIts collection already auto-updates.

admin addon enable

kraft admin addon enable ADDON@COLLECTION

Loads an installed add-on. It takes no flags and no --json.

admin addon disable

kraft admin addon disable ADDON@COLLECTION

Keeps an add-on installed and not loaded. It takes no flags and no --json. Remove an add-on says when it is refused.

admin addon uninstall

kraft admin addon uninstall [flags] ADDON@COLLECTION

Removes an add-on. It takes no flags.

RefusalCause
Refused, listing each referenceYour own config still references its namespace.

Remove an add-on

kraft admin addon uninstall and disable are refused while your library, a chain, repos.yaml, intake.yaml, policy.yaml or harnesses.yaml still names the add-on's namespace. The refusal lists each reference.

A worker can't run the verbs that change add-ons.

admin addon list

kraft admin addon list [flags]

Every installed add-on (not the built-in kraft-default, which ships with Kraft): namespace, version and commit, with its auto-update setting, why it isn't loaded, and a pending alias, ref or collection URL change. It takes no flags.

The built-in kraft-default

Added in 2.6

The built-in kraft-default@kraft ships with Kraft and takes its version from Kraft's. A bare update or update --check skips it. See Add-on problems.

RefusalCause
error: kraft-default@kraft comes with Kraft; upgrading Kraft updates itinstall, update, auto-update, enable, disable or uninstall names it.
error: the collection name 'kraft' is Kraft's owncollection add names a collection kraft.

Check an add-on

Added in 2.1

admin addon validate

kraft admin addon validate [flags] PATH

Checks a collection or a single add-on directory and installs nothing. Exits 1 on any problem.

FlagTypeDefaultMeaning
--withdirectory, repeatablenoneA collection or add-on directory to find a child add-on's parent in.
--jsonswitchoffPrints the report as an object with addons, problems, warnings and skipped.

Validate a collection or an add-on

PATH is a directory holding .kraft/collection.json, or one holding .kraft/addon.json.

It checks each add-on's files against the size and content limits, both manifests, the Kraft version the add-on requires, and that every chain the add-on ships resolves.

When the config directory holds a library.yaml, it also checks the add-on as an install into that instance: its requires.harnesses and requires.profiles, its namespace, and your own chains. With none, it prints a skipped: line naming those checks.

It prints one line per add-on with its version and digest, then each problem with its file, then warnings: a manifest key Kraft doesn't read, and a file that looks like part of the add-on layout and isn't.

It exits 0 when every add-on passes and 1 otherwise, so a collection's CI can run it on every push; Run validate in CI shows a job.

Validate a child add-on

Added in 2.3

An add-on that builds on another (requires.addons) is checked together with its parent and every ancestor above it. Validate looks for each one, in order:

  1. in PATH, when it is a collection that publishes the parent
  2. in each --with DIR, a collection directory or a single add-on directory; repeat --with for more than one. A --with directory that holds neither manifest is a problem
  3. on this instance, as installed
  4. on this instance, as the current version of a collection added in addons.yaml, which validate fetches into a temporary directory, so the instance isn't changed
kraft admin addon validate ./payments-addons --with ./company-addons

When none of them has the parent, validate still checks the child's own files, then exits 1 with its parent <id> could not be found in PATH, --with or this instance; pass its collection with --with, alongside any other problem it finds. A tree that is a cycle, or deeper than 8 add-ons, is reported the same way. In --json, each entry of addons carries parent, the parent's ID or null.

Copyright © 2026