Add-on verbs
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
| Verb | What it does |
|---|---|
admin addon collection add | Adds a collection; installs nothing. Added in 2.1 |
admin addon collection list | Lists the collections and what each publishes. Added in 2.1 |
admin addon collection update | Fetches the newest catalogue. Added in 2.1 |
admin addon collection auto-update | Sets a collection's auto-update. Added in 2.1 |
admin addon collection remove | Forgets a collection. Added in 2.1 |
admin addon install | Installs an add-on and its missing ancestors, after a review. Added in 2.1 |
admin addon update | Updates installed add-ons, one review per tree. Added in 2.1 |
admin addon auto-update | Sets one add-on's auto-update. Added in 2.1 |
admin addon enable | Loads an installed add-on. Added in 2.1 |
admin addon disable | Keeps an add-on installed but not loaded. Added in 2.1 |
admin addon uninstall | Removes an installed add-on. Added in 2.1 |
admin addon list | Lists the installed add-ons. Added in 2.1 |
admin addon validate | Checks 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--ref | branch, tag or commit | the default branch | What the collection follows. |
--auto-update | switch | off | Every add-on installed from it updates itself. |
--replace | switch | off | Moves 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.
| Refusal | Cause |
|---|---|
| Refused | One 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--as | namespace | the add-on's own | Installs the add-on under another namespace. |
--auto-update | switch | off | The add-on updates itself. |
--re-install | switch | off | Takes the newest commit of an installed one, even at an unchanged version. |
-y, --yes | switch | off | Accepts 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
-y, --yes | switch | off | Accepts every review. Exclusive with --check. |
--check | switch | off | Changes 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 code | Meaning |
|---|---|
0 | Every add-on is current. |
1 | An update is waiting or held by a range. |
2 | An update would be refused, a relative's that breaks a chain included. |
3 | It 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.
| Refusal | Cause |
|---|---|
| Refused | Its 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.
| Refusal | Cause |
|---|---|
| Refused, listing each reference | Your 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.
| Refusal | Cause |
|---|---|
error: kraft-default@kraft comes with Kraft; upgrading Kraft updates it | install, update, auto-update, enable, disable or uninstall names it. |
error: the collection name 'kraft' is Kraft's own | collection 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--with | directory, repeatable | none | A collection or add-on directory to find a child add-on's parent in. |
--json | switch | off | Prints 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:
- in
PATH, when it is a collection that publishes the parent - in each
--with DIR, a collection directory or a single add-on directory; repeat--withfor more than one. A--withdirectory that holds neither manifest is a problem - on this instance, as installed
- 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.
Related
- Share chains with add-ons: publish a collection and install an add-on from it.
- Add-ons and collections: the manifests,
addons.yaml, the lock, and when an add-on loads or updates.