CLI

Forge verbs

The kraft admin forge verbs: name, edit, list, remove and test forge accounts.

kraft admin forge manages the accounts in forges.yaml. The server, add-on and machine 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 forge addNames a forge account. Added in 2.5
admin forge editChanges an account; only the flags given change. Added in 2.5
admin forge listThe accounts. Added in 2.5
admin forge removeForgets an account. Added in 2.5
admin forge testChecks an account's sign-in or token. Added in 2.5

Forge accounts

Added in 2.5

An account in forges.yaml records which forge a host runs and its web address, so kraft repo connect doesn't ask about a self-hosted host whose name doesn't say. A client: cli account holds no token: gh and glab keep their own sign-in. A client: api account reads one from a source; see forges.yaml. A repo names an account with forge_account.

Every verb asks the server, which owns the file, except a command source, which the CLI writes on disk as admin forge add says.

admin forge add

Added in 2.5

kraft admin forge add [flags] NAME

Names a forge account: the host's forge and web address, and for --client api where its token comes from. NAME is lowercase letters, digits, ., - and _, starting with a letter or digit, so a web host such as code.corp.example works.

FlagTypeDefaultMeaning
--forgegithub or gitlabnone given: requiredThe host's forge.
--web-urlhttps:// URLnone given: requiredThe forge's web address.
--api-urlURLthe forge's usual oneMust share the web address's origin (host and port).
--default-for-hostswitchoffMakes the account the one repos on that host use unless they name another.
--clientcli or apicli, or api with a token flagcli: gh and glab keep their own sign-in. api: Kraft reads a token.
--ca-filepathwhat git trusts for that address (http.sslCAInfo), then the system's CAsThe CA that signs a self-hosted forge's certificate, for the API client only. TLS verification is never turned off.
--token-fromgit-credential, env:NAME, file:PATH or command:CMDnoneWhere the token is read from. Implies --client api.
--token-stdinswitchoffReads the token from standard input, never from an argument, and the server writes it to a private file. Implies --client api. Exclusive with --token-from.
--kindpat, oauth or unknownunknownSays what the token is.

A command source runs code as the server's user, so the server's API refuses it. The CLI writes it into forges.yaml on the server's machine and reloads; elsewhere, or inside a worker, it refuses. A reload that refuses the file, or after which the server doesn't list the account, puts the old text back and exits 1.

RefusalCause
RefusedA second account with --default-for-host for one host.
Refused--client cli with --token-from or --token-stdin.
403The API refuses a write naming an env variable or file another account reads, or another account's pasted file; edit forges.yaml by hand to share one.

admin forge edit

Added in 2.5

kraft admin forge edit [flags] NAME

Changes the flags given on an account: its API address, ca_file, client or token source. edit changes only the flags given.

FlagTypeDefaultMeaning
--api-urlURLunchangedMust share the web address's origin.
--clientcli or apiunchanged--client cli drops the account's token and ca_file.
--ca-filepathunchangedAs for add.
--token-from, --token-stdinas for addunchangedAs for add. A pasted token's file is deleted once the account stops reading it. If the paste fails, edit puts the changed fields back.
--kindpat, oauth or unknownunchangedSays what the new token is.

The same goes for changing an account that already reads a command source: edit with --token-from env:…, file:…, --token-stdin or --client cli writes forges.yaml on the server's machine too, because the API (and so Settings) refuses to replace a command. A --token-stdin token is written to a private file under $KRAFT_HOME/secrets/, as the API does. Nothing is changed when the token is refused (too short, or holding whitespace).

RefusalCause
Refused--kind with no token flag.

admin forge list

Added in 2.5

kraft admin forge list [flags]

Each account: forge, web address and whether it is the host's default. It takes no flags.

admin forge remove

Added in 2.5

kraft admin forge remove [flags] NAME

Forgets an account. It takes no flags. A default account no repo names is removed anyway, and items pinned to it stop at their next forge node.

RefusalCause
RefusedA repo names the account.

admin forge test

Added in 2.5

kraft admin forge test [flags] NAME

Checks a client: cli account's gh or glab sign-in, or a client: api account's token: who it signs in as, its scopes, expiry and the repos it sees. test exits 1 when it fails. It takes no flags.

On a client: cli account, test runs gh auth status or glab auth status in the server for the account's host, without its port. On a client: api account it probes the token and never runs the CLI.

Copyright © 2026