Forge verbs
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
| Verb | What it does |
|---|---|
admin forge add | Names a forge account. Added in 2.5 |
admin forge edit | Changes an account; only the flags given change. Added in 2.5 |
admin forge list | The accounts. Added in 2.5 |
admin forge remove | Forgets an account. Added in 2.5 |
admin forge test | Checks 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--forge | github or gitlab | none given: required | The host's forge. |
--web-url | https:// URL | none given: required | The forge's web address. |
--api-url | URL | the forge's usual one | Must share the web address's origin (host and port). |
--default-for-host | switch | off | Makes the account the one repos on that host use unless they name another. |
--client | cli or api | cli, or api with a token flag | cli: gh and glab keep their own sign-in. api: Kraft reads a token. |
--ca-file | path | what git trusts for that address (http.sslCAInfo), then the system's CAs | The CA that signs a self-hosted forge's certificate, for the API client only. TLS verification is never turned off. |
--token-from | git-credential, env:NAME, file:PATH or command:CMD | none | Where the token is read from. Implies --client api. |
--token-stdin | switch | off | Reads 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. |
--kind | pat, oauth or unknown | unknown | Says 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.
| Refusal | Cause |
|---|---|
| Refused | A second account with --default-for-host for one host. |
| Refused | --client cli with --token-from or --token-stdin. |
403 | The 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--api-url | URL | unchanged | Must share the web address's origin. |
--client | cli or api | unchanged | --client cli drops the account's token and ca_file. |
--ca-file | path | unchanged | As for add. |
--token-from, --token-stdin | as for add | unchanged | As 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. |
--kind | pat, oauth or unknown | unchanged | Says 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).
| Refusal | Cause |
|---|---|
| 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.
| Refusal | Cause |
|---|---|
| Refused | A 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.