@klok-integration/cli 0.6.245 → 0.7.248

package/assets/agents/skills/klok-cli/reference.md

@@ -0,0 +1,1096 @@
+# klok command reference
+
+Generated from the `klok` program of this klok-cli version by `npm run reference -w @klok/cli`; do not edit it by
+hand. Every command also takes `-h, --help`, and the global options below go before or after the command.
+
+Local proxy to the Klok Integration Agent. Interactive terminal UI when run in a terminal; headless JSON output when piped, in CI, or with --json.
+
+## Global options
+
+| Option | Description |
+|---|---|
+| `-V, --version` | output the version number |
+| `--json` | Headless mode: one JSON document on stdout, messages on stderr |
+| `--no-tui` | Disable the terminal UI (same as --json without pretty output) |
+| `--stream` | Headless mode: NDJSON task events on stdout, then the result document |
+| `--tenant <slug>` | Tenant to act in (overrides config and KLOK_TENANT) |
+| `--domain <slug>` | Default domain scope for tasks |
+| `--agent-url <url>` | Agent service URL (overrides config and KLOK_AGENT_URL) |
+
+```
+Exit codes:
+  0  ok
+  1  error
+  2  task needs input (see the question in the JSON document, answer with `klok agent answer`)
+  3  denied by policy (the JSON document lists the capability decisions)
+  4  not authenticated (run `klok login`)
+  5  managed files are outdated (klok agents update --check); a deployed service is stale (klok fleet status)
+
+Examples:
+  klok login
+  klok agent ask "Which legs consume InvoiceV1?"
+  klok agent ask "..." --json | jq .task.resultSummary
+  klok agent impact InvoiceV1 --change major --json
+  klok agent plan KLK001 --change-request change.md
+  klok agent serve
+  klok bead report fortnox-egress-1 --status done --message "Merged MR !12"
+  klok agents init                # KLOK-AGENTS.md, harness rows, platform and tenant skills, the session hook
+  klok agents update              # fetch the platform and tenant catalogs, write what moved, prune by marker
+  klok agents update --check      # exit 5 when a catalog is outdated or missing, write nothing
+  klok agents status              # per managed file and per catalog: current, outdated, missing, unreachable
+  klok agents init --global       # ~/.klok/agents/KLOK-AGENTS.md, every tenant of your token, the global hook
+  klok catalog publish-agents     # write this CLI's agent assets and version into the platform catalog
+  klok docs publish               # build this repository's znai tree and upload it to docs.klok.dev
+  klok docs publish --dry-run     # show the doc id, source root and portal, upload nothing
+  klok fleet status               # every deployed service: built from main? with the catalog's broker client?
+  klok fleet status --broker      # and every producer and consumer on the broker (needs your Vault login)
+  klok fleet rebuild --stale --dry-run   # which main pipelines a rebuild of the stale services would start
+  klok manifest update            # set this pipeline's image in its deploy manifest, commit and push
+  klok manifest update --dry-run  # clone and edit the manifest, print the diff, push nothing
+  klok pin update --repo <infra repo> --file <vars.yml> --version-key <key> --sha256-key <key> \
+    --sha256-of '{maven-central}.nar'   # open a merge request that pins this pipeline's release
+```
+
+## klok login
+
+```
+klok login [options]
+```
+
+Log in to Keycloak (device flow by default; --browser for the browser flow)
+
+| Option | Description |
+|---|---|
+| `--browser` | Use the browser authorization code flow instead of the device flow |
+| `--no-open` | Do not open the browser automatically |
+
+## klok logout
+
+```
+klok logout [options]
+```
+
+Remove stored credentials
+
+## klok whoami
+
+```
+klok whoami [options]
+```
+
+Show the logged-in user and tenant
+
+## klok config
+
+```
+klok config [options] [command]
+```
+
+Read and write ~/.config/klok/config.json
+
+### klok config list
+
+```
+klok config list [options]
+```
+
+Show effective configuration and where each value comes from; secrets show as ****
+
+### klok config get
+
+```
+klok config get [options] <key>
+```
+
+Print one effective configuration value; secrets show as **** unless --reveal
+
+| Argument | Description |
+|---|---|
+| `<key>` | required |
+
+| Option | Description |
+|---|---|
+| `--reveal` | Print the real value of a secret |
+
+### klok config set
+
+```
+klok config set [options] <key> [value]
+```
+
+Set a value. Keys: agentUrl, tenant, klokDevUrl, keycloakIssuer, keycloakClientId, protocol, domain, gitUrl, workspace, klokerBasePath, klokerUrl, klokerModel, summaryLanguage, klokApiKey. Leave out the value of a secret (klokApiKey) to type it at a hidden prompt or pipe it in, so it stays out of the shell history
+
+| Argument | Description |
+|---|---|
+| `<key>` | required |
+| `[value]` | optional |
+
+### klok config delete
+
+```
+klok config delete [options] <key>
+```
+
+Remove a value from the config file
+
+| Argument | Description |
+|---|---|
+| `<key>` | required |
+
+## klok agent
+
+```
+klok agent [options] [command]
+```
+
+Run tasks on the Klok Integration Agent
+
+### klok agent ask
+
+```
+klok agent ask [options] <question>
+```
+
+Ask a question about the integration landscape
+
+| Argument | Description |
+|---|---|
+| `<question>` | required |
+
+| Option | Description |
+|---|---|
+| `--focus <nodeId...>` | Focus node ids from the context graph |
+| `--session <id>` | Continue a conversation session |
+| `--no-wait` | Create the task and return immediately |
+
+### klok agent impact
+
+```
+klok agent impact [options] <target>
+```
+
+Impact analysis for a node id or datamodel name
+
+| Argument | Description |
+|---|---|
+| `<target>` | required |
+
+| Option | Description |
+|---|---|
+| `--change <kind>` | minor \| major \| remove |
+| `--description <text>` | What the change is |
+| `--no-wait` | Create the task and return immediately |
+
+### klok agent plan
+
+```
+klok agent plan [options] <solutionKey>
+```
+
+Plan a solution change from a change request file (or - for stdin)
+
+| Argument | Description |
+|---|---|
+| `<solutionKey>` | required |
+
+| Option | Description |
+|---|---|
+| `--change-request <file>` | Path to the change request text, or - for stdin |
+| `--answer <questionId=text...>` | Clarification answers |
+| `--no-wait` | Create the task and return immediately |
+
+### klok agent implement
+
+```
+klok agent implement [options] <beadId>
+```
+
+Implement a bead with a coding agent in the sandbox and deliver a merge request
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--repo-path <path>` | Repository the bead lives in (default: the origin of the current repository) |
+| `--agent <id>` | Coding agent: opencode \| claude-code \| codex (default: `opencode`) |
+| `--model <model>` | Model on the Klok LLM gateway |
+| `--max-minutes <n>` | Wall-clock budget for the agent and the build (default: `90`) |
+| `--max-build-attempts <n>` | How many times the agent may fix a failing build (default: `2`) |
+| `--no-wait` | Create the task and return immediately |
+
+### klok agent tasks
+
+```
+klok agent tasks [options]
+```
+
+List tasks in the tenant
+
+| Option | Description |
+|---|---|
+| `--status <status>` | submitted \| working \| input-required \| completed \| failed \| canceled |
+| `--type <taskType>` | landscape-question \| impact-analysis \| integration-plan \| erp-change-plan \| issue-creation \| bead-creation \| project-scaffold \| datamodel-proposal \| repo-index \| bead-implementation |
+| `--limit <n>` | Maximum number of tasks (default: `50`) |
+
+### klok agent open
+
+```
+klok agent open [options] <taskId>
+```
+
+Open the task in klok.dev
+
+| Argument | Description |
+|---|---|
+| `<taskId>` | required |
+
+### klok agent answer
+
+```
+klok agent answer [options] <taskId>
+```
+
+Answer an input-required question
+
+| Argument | Description |
+|---|---|
+| `<taskId>` | required |
+
+| Option | Description |
+|---|---|
+| `--question <questionId>` | Question id from the task |
+| `--text <answer>` | Answer text |
+| `--no-wait` | Do not wait for the task to continue |
+
+### klok agent cancel
+
+```
+klok agent cancel [options] <taskId>
+```
+
+Cancel a task
+
+| Argument | Description |
+|---|---|
+| `<taskId>` | required |
+
+### klok agent serve
+
+```
+klok agent serve [options]
+```
+
+Start the loopback MCP and A2A proxy for IDEs and other agents
+
+| Option | Description |
+|---|---|
+| `--port <port>` | Port on 127.0.0.1 (default: `3091`) |
+| `--host <host>` | Bind address (default: `127.0.0.1`) |
+
+## klok bead
+
+```
+klok bead [options] [command]
+```
+
+Work with .beads/*.json files in the current repository
+
+### klok bead list
+
+```
+klok bead list [options]
+```
+
+List beads in the current repository
+
+| Option | Description |
+|---|---|
+| `--status <status>` | open \| blocked \| in_progress \| needs_review \| done \| cancelled |
+
+### klok bead show
+
+```
+klok bead show [options] <beadId>
+```
+
+Print one bead
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+### klok bead report
+
+```
+klok bead report [options] <beadId>
+```
+
+Append progress to a bead and report it to klok.dev
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--status <status>` | open \| blocked \| in_progress \| needs_review \| done \| cancelled |
+| `--message <text>` | What happened |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+| `--local-only` | Update the bead file without reporting to klok.dev |
+
+## klok agents
+
+```
+klok agents [options] [command]
+```
+
+Install and keep current the Klok agent instructions (KLOK-AGENTS.md plus one managed row in every harness file), the platform skills and your tenant’s skills
+
+### klok agents init
+
+```
+klok agents init [options]
+```
+
+Write KLOK-AGENTS.md, knowledge/ and the skills into a repository, with --workspace into the workspace root, or with --global into the home folder, and put one managed row into AGENTS.md, CLAUDE.md, GEMINI.md and the other harness files. The platform assets come from the platform catalog on GitLab (the copy bundled with this CLI with --offline); the tenant skills come from the tenant catalog when a GitLab token is at hand, are installed next to the platform skills and kept out of git. Klok’s own files are replaced wholesale; every other file keeps its content and only has its single klok-agents row created or replaced. Retired skills are removed by their marker. A Claude Code SessionStart hook keeps the skills fresh.
+
+| Option | Description |
+|---|---|
+| `-g, --global` | Initialise the home folder (~/.klok/agents/KLOK-AGENTS.md, the harness files that point at it, and the skills of every tenant your token belongs to) |
+| `-w, --workspace [path]` | Initialise the workspace root (default: config workspace, ~/devklok) with the shared rules and pointer files, no skills |
+| `-d, --dir <path>` | Repository directory (default: current directory) |
+| `-t, --type <type>` | Project type: integration, datamodel, documentation, application, framework (default: detected) |
+| `--tools <list>` | Comma separated harnesses or "all": claude, codex, opencode, cursor, gemini, antigravity, cline, copilot (default: `all`) |
+| `--tenant <slug>` | Install this tenant’s skills (repeatable; default: the tenant of the origin remote, or every root group of the token with --global) |
+| `--no-tenant` | Platform skills only |
+| `--token <token>` | GitLab token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `--offline` | Use the assets bundled with this CLI and reach no catalog |
+| `--no-skills` | Do not write the skill files |
+| `--no-hooks` | Do not write the Claude Code SessionStart hook |
+| `--dry-run` | Show what would change without writing |
+
+### klok agents update
+
+```
+klok agents update [options]
+```
+
+Fetch the platform catalog and your tenant catalog(s), write the files that moved, prune retired skills by their marker and keep tenant skills out of git. Nothing is written when the catalogs did not move. --check reports and exits 5 when a catalog is outdated or missing; --quiet prints one line only when something changed, which is what the Claude Code hook runs.
+
+| Option | Description |
+|---|---|
+| `-g, --global` | Update the home folder instead of a repository |
+| `-d, --dir <path>` | Repository directory (default: current directory) |
+| `--tenant <slug>` | Update this tenant’s skills (repeatable; default: detected) |
+| `--no-tenant` | Platform assets only |
+| `--token <token>` | GitLab token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `--check` | Compare only: exit 5 when a catalog is outdated or missing, write nothing |
+| `--max-age <duration>` | Skip a catalog checked less than this long ago (30s, 10m, 2h, 1d) |
+| `-q, --quiet` | Print one line only when something changed; an unreachable catalog is not an error |
+| `--dry-run` | Show what would change without writing |
+| `--tools <list>` | Comma separated harnesses or "all" (default: as installed) |
+| `-t, --type <type>` | Project type (default: as installed, else detected) |
+| `--offline` | Use the assets bundled with this CLI and reach no catalog |
+
+### klok agents status
+
+```
+klok agents status [options]
+```
+
+Show, per managed file and per catalog, whether the instructions of a repository (with --global the home folder, with --workspace the workspace root) are current, outdated, missing or unreachable, and whether the session hook is installed
+
+| Option | Description |
+|---|---|
+| `-g, --global` | Check the home folder instead of a repository |
+| `-w, --workspace [path]` | Check the workspace root instead of a repository (default: config workspace) |
+| `-d, --dir <path>` | Repository directory (default: current directory) |
+| `-t, --type <type>` | Project type (default: detected) |
+| `--tools <list>` | Comma separated harnesses or "all" (default: `all`) |
+| `--tenant <slug>` | Check this tenant’s skills (repeatable; default: detected) |
+| `--no-tenant` | Platform only |
+| `--token <token>` | GitLab token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `--offline` | Compare with the assets bundled with this CLI and reach no catalog |
+
+### klok agents propose
+
+```
+klok agents propose [options]
+```
+
+Update the committed agent instructions of a repository from the platform catalog and offer the result as a merge request. Meant for a scheduled pipeline: when the files already match it does nothing, it never writes to the default branch, and it never commits tenant skills.
+
+| Option | Description |
+|---|---|
+| `-d, --dir <path>` | Repository directory (default: current directory) |
+| `-t, --type <type>` | Project type (default: detected) |
+| `--tools <list>` | Comma separated harnesses or "all" (default: `all`) |
+| `--no-skills` | Do not write the skill files |
+| `--offline` | Use the assets bundled with this CLI instead of the platform catalog |
+| `--branch <name>` | Branch to propose from (default: klok/agents-refresh) (default: `klok/agents-refresh`) |
+
+### klok agents list
+
+```
+klok agents list [options]
+```
+
+List the project types, harnesses and platform skills this CLI version installs, and the tenant skills installed here
+
+| Option | Description |
+|---|---|
+| `-g, --global` | List the tenant skills installed in the home folder |
+| `-d, --dir <path>` | Repository directory (default: current directory) |
+
+## klok catalog
+
+```
+klok catalog [options] [command]
+```
+
+The platform dependency catalog, which Gradle, klok-cli and klok.dev install from
+
+### klok catalog publish-agents
+
+```
+klok catalog publish-agents [options]
+```
+
+Write this CLI's agent assets into the catalog's agents/ and klok-agents.zip, with its version when they changed, then commit and push
+
+| Option | Description |
+|---|---|
+| `--repo <path-or-url>` | GitLab path or git URL of the catalog (default: KLOK_AGENTS_CATALOG_REPO, then klok/framework/klok-gradle-dependency-catalog) |
+| `--branch <name>` | Branch to push to (default: KLOK_AGENTS_CATALOG_BRANCH, then main) |
+| `-n, --dry-run` | Clone and write the assets, print what would change, commit and push nothing |
+
+```
+The files are the assets bundled in this CLI (assets/agents). When they differ from the catalog's, agents/VERSION
+becomes this CLI's version, so the catalog names the build that last changed its assets; when they are the same,
+nothing is committed, because every installed file carries that version in its marker. Only a released build
+(<x.y.z>-build.<yyMMddHHmmss>) is published, and a catalog that already has a newer build is left alone. When
+RELEASED_KLOK_CLI_VERSION is set (the release pipeline sets it), the command refuses to run from an older build,
+because the image was then not rebuilt; the same build or a later one is published, since pipelines on main queue
+and the image can already carry the CLI of a release made after this pipeline's.
+
+Credentials: in CI the job logs in to Vault with its identity token (VAULT_ID_TOKEN) and the role
+<tenant>-ci-protected (KLOK_VAULT_DEPLOY_KEY_ROLE overrides it), which only pipelines of a protected branch or tag
+can use, and reads the deploy key and the pinned host key from secret/<tenant>/CICD_KEY and
+secret/<tenant>/KNOWN_HOSTS. By hand,
+your ssh-agent (SSH_AUTH_SOCK) or GIT_SSH_COMMAND is used as it is.
+
+Examples:
+  klok catalog publish-agents               # in klok-integration-agent's main pipeline, after the release
+  klok catalog publish-agents --dry-run     # clone and write, show what would change, push nothing
+```
+
+### klok catalog release-dependents
+
+```
+klok catalog release-dependents [options]
+```
+
+After a library reached the platform catalog, start the default branch pipeline of every framework library whose newest release was built against an older version of it, so that it is released again against the catalog
+
+| Option | Description |
+|---|---|
+| `--library <artifact>` | The released library, by Maven artifact id (repeatable; default: the build/klok-release.properties files of this directory) |
+| `--catalog <path>` | GitLab path of the catalog (default: klok/framework/klok-gradle-dependency-catalog) |
+| `--catalog-file <file>` | Versions file in the catalog (default: klok-libs.versions.toml) |
+| `--catalog-ref <ref>` | Read the catalog at this branch or commit (default: main); an older commit shows what would have happened then |
+| `-n, --dry-run` | Say what would be started; start nothing |
+| `--git-url <url>` | GitLab base URL (default: in CI the job's server, else config gitUrl) |
+| `--token <token>` | GitLab access token (default: in CI the job token, else KLOK_GIT_APIKEY, then config klokApiKey) |
+
+```
+For each framework library (Maven group dev.klok.framework) in the catalog, the POM of the version the catalog names
+says which version of the released library it was built against. One that is older than the catalog's version is
+behind, and gets its default branch pipeline started when its repository has gradle/klok-libs.versions.toml (the build
+refreshes it from the catalog, so the new pipeline builds against the new version). Its release reaches the catalog,
+where the same job runs again: klok-common, then the broker client, then the Quarkus extension, one hop at a time.
+
+States per dependent:
+  current           its newest release already declares the catalog's version; nothing to do (this ends the chain)
+  started           its default branch pipeline was started
+  would start       the same, in a dry run
+  already running   a pipeline on its default branch, created after the version reached the catalog, will release it
+  waits             it also declares another library that is started now; that release starts it
+  pinned            it is behind but has no gradle/klok-libs.versions.toml: it pins versions itself; a WARNING, raise them by hand
+  not started       GitLab refused the start; the command exits 1
+  unknown           no POM of its catalog version in its package registry; a WARNING
+
+The project of a framework library is <tenant>/framework/<artifact>. Nothing is ever cancelled.
+
+In CI (the update_klok_catalog job of build-template-java.yml, after the catalog push) it uses the job token: the
+pipeline is started with POST /projects/:id/trigger/pipeline, which GitLab accepts when the dependent's job token
+allowlist holds the releasing project or its group, and runs as the user of the releasing pipeline. It starts
+pipelines only from a pipeline on the default branch and not when KLOK_CATALOG_UPDATE_DRY_RUN is true (the catalog
+update's dry run), and does nothing for a tenant other than the platform's.
+
+Examples:
+  klok catalog release-dependents --library klok-brokerclient-java --dry-run
+  klok catalog release-dependents --library klok-brokerclient-java --catalog-ref <catalog sha> --dry-run
+  klok catalog release-dependents                       # in CI: what this pipeline released
+```
+
+## klok ci
+
+```
+klok ci [options] [command]
+```
+
+The CI job klok-cli runs in, and where CI time goes
+
+### klok ci env
+
+```
+klok ci env [options]
+```
+
+Print what klok-cli detected about this CI job, and which variable each value came from
+
+### klok ci docs-only
+
+```
+klok ci docs-only [options]
+```
+
+Fail unless this change touches only documentation (klok-docs/, root Markdown files, .beads/): the guard of the pipeline path a `docs` commit takes, which skips the build
+
+| Option | Description |
+|---|---|
+| `--base <ref>` | Compare against this ref (default: the merge request target; on the default branch, the commit before the push) |
+
+```
+The Klok templates run it in a pipeline whose merge request title or commit is typed docs (Conventional Commits), where
+the build, the image, the release and the deployment are skipped: klok-docs/ci/docs-only.md.
+```
+
+### klok ci timings
+
+```
+klok ci timings [options]
+```
+
+Where CI time goes on GitLab: pipeline wall clock, waits per runner, and each job's phases (image, git, cache, artifacts, script) from its log. Saves a snapshot and compares it with a baseline.
+
+| Option | Description |
+|---|---|
+| `--since <date>` | Start of the window, ISO 8601 (default: 30 days before --until) |
+| `--until <date>` | End of the window, exclusive (default: now) |
+| `--project <glob>` | Only projects whose path matches, for example "klok/integration/*" or "jttl/**" (repeatable) (default: ``) |
+| `--out <file>` | Write the snapshot as JSON, to compare a later run with |
+| `--compare <file>` | Compare with a snapshot written earlier by --out |
+| `--no-logs` | Skip the job logs: no phase breakdown, but much faster |
+| `--git-url <url>` | GitLab base URL (default: config gitUrl) |
+| `--token <token>` | GitLab token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey); an administrator's sees every project |
+| `-j, --jobs <n>` | Parallel requests to GitLab (default: `8`) |
+
+```
+The metrics and how to read them: klok-docs/ci/timings.md. A snapshot has a version; --compare refuses one written
+with other metric definitions.
+
+Examples:
+  klok ci timings --since 2026-08-27 --until 2026-09-26 --out ci-baseline.json
+  klok ci timings --since 2026-10-20 --compare ci-baseline.json
+  klok ci timings --project "klok/integration/*" --no-logs
+```
+
+## klok datamodel
+
+```
+klok datamodel [options] [command]
+```
+
+The names and checks of a Klok datamodel (XSD first, one repository per model and major version)
+
+### klok datamodel names
+
+```
+klok datamodel names [options]
+```
+
+Print the repository, file, root element, type and namespace a model gets from its class and name
+
+| Option | Description |
+|---|---|
+| `--class <A|B|C|X>` | A public, B common (tenant wide), C domain, X system |
+| `--system <slug>` | External system of a class X model |
+| `--name <PascalCase>` | Model name without the version, e.g. SupplierInvoice |
+| `--major <n>` | Major version, 1 or higher |
+
+```
+The tenant is the global --tenant (or the configured one); a class C model takes its domain from the global
+--domain. The same rules name the repository klok.dev creates and the template's placeholders
+(klok/environment/project-template-datamodel). Example:
+
+  klok datamodel names --tenant acme --class C --domain finance --name SupplierInvoice --major 1
+```
+
+### klok datamodel validate
+
+```
+klok datamodel validate [options] [files...]
+```
+
+Check XSDs the way the datamodel pipeline does before avrotize: well formed, every prefix declared, every referenced type defined, every name a Java/Avro identifier; warn about the conventions
+
+| Argument | Description |
+|---|---|
+| `[files...]` | XSD files (default: every *.xsd in schema-definition-xsd/) |
+
+```
+Exit code 1 when a file is invalid; warnings never fail. The rules and their fixtures are shared with
+scripts/validate-xsd.py in build-ci-templates and with klok.dev (datamodel-fixtures.json).
+```
+
+## klok docs
+
+```
+klok docs [options] [command]
+```
+
+Read the platform documentation on docs.klok.dev, and publish this repository’s znai documentation there
+
+### klok docs read
+
+```
+klok docs read [options] <doc-id>
+```
+
+Print the llm.txt of a documentation project on docs.klok.dev, the one markdown file with its whole content, read with your GitLab token. Cached under ~/.cache/klok/docs with the ETag, so a second read is one conditional request; without network the cache is served with a warning. With --json the document carries the content and where it came from; otherwise the content goes to stdout and one status line to stderr.
+
+| Argument | Description |
+|---|---|
+| `<doc-id>` | required |
+
+| Option | Description |
+|---|---|
+| `--out <file>` | Write the content to this file instead of stdout |
+| `--refresh` | Fetch again even when the cache is current |
+| `--token <token>` | GitLab personal access token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+
+### klok docs list
+
+```
+klok docs list [options]
+```
+
+List the documentation projects on docs.klok.dev that your GitLab account may read, from the portal’s index: one line per project, its doc id (what `klok docs read` takes), title and description. With --json the document carries every field of the index.
+
+| Option | Description |
+|---|---|
+| `--token <token>` | GitLab personal access token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+
+### klok docs id
+
+```
+klok docs id [options] [path]
+```
+
+The doc id and documentation identity of a repository path (default: this repository, from CI_PROJECT_PATH or the git remote)
+
+| Argument | Description |
+|---|---|
+| `[path]` | optional |
+
+### klok docs lint
+
+```
+klok docs lint [options]
+```
+
+Check a znai documentation project: table of contents, links and metadata
+
+| Option | Description |
+|---|---|
+| `--source-root <dir>` | Directory holding toc and meta.json (default: docs, then the repository root) |
+
+### klok docs verify
+
+```
+klok docs verify [options]
+```
+
+Check that this repository’s klok-docs/ describes what it builds, before the merge request
+
+| Option | Description |
+|---|---|
+| `--payload <file>` | The documentation payload (default: build/klok-docs/project-documentation.json) |
+| `--base <ref>` | Compare against this ref (default: the merge request target, else origin/main) |
+| `--strict` | Fail on warnings too |
+
+### klok docs build
+
+```
+klok docs build [options]
+```
+
+Build this repository’s klok-docs/ with znai the way its documentation project will, upload nothing
+
+| Option | Description |
+|---|---|
+| `--repo-path <path>` | Repository path the doc id is derived from (default: CI_PROJECT_PATH or the git remote) |
+| `--znai <path>` | The znai executable (default: znai on PATH) |
+
+### klok docs send
+
+```
+klok docs send [options]
+```
+
+Publish this repository’s klok-docs/ to the documentation chain (projects not built with the Klok Gradle plugin)
+
+| Option | Description |
+|---|---|
+| `--repo-path <path>` | Repository path the identity is derived from (default: the CI project path or the git remote) |
+| `--any-branch` | Publish outside CI or from a branch other than the default one, deliberately |
+| `-n, --dry-run` | Build the payload and say what would be sent; publish nothing |
+
+### klok docs publish
+
+```
+klok docs publish [options]
+```
+
+Build the znai project and upload it under this project’s doc id
+
+| Option | Description |
+|---|---|
+| `--source-root <dir>` | Directory holding toc and meta.json (default: docs, then the repository root) |
+| `--doc-id <id>` | Publish under this doc id instead of the derived one |
+| `--repo-path <path>` | Repository path to derive from (default: CI_PROJECT_PATH or the git remote) |
+| `--znai <path>` | The znai executable (default: znai on PATH) |
+| `-n, --dry-run` | Resolve what would be published and build it with znai, upload nothing |
+| `--no-build` | With --dry-run: only resolve the plan, do not run znai |
+
+## klok fleet
+
+```
+klok fleet [options] [command]
+```
+
+Every deployed service: what it was built from, whether that is the latest, and rebuilding the ones that are not
+
+### klok fleet status
+
+```
+klok fleet status [options]
+```
+
+One row per deployed workload: deployed tag, main, the last main pipeline, the broker client its build used against the catalog, and a verdict; --broker adds every producer and consumer on the broker
+
+| Option | Description |
+|---|---|
+| `--manifests-repo <path>` | GitLab path of the deploy manifests repository (default: KLOK_MANIFEST_REPO, then klok/environment/ipaas/ipaas-service-deploy-manifests) |
+| `--git-url <url>` | GitLab base URL (default: config gitUrl) |
+| `--token <token>` | GitLab personal access token (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `-j, --jobs <n>` | Parallel requests to GitLab and the broker (default: `8`) |
+| `--broker` | Also read every producer and consumer on the broker (needs your Vault login) |
+| `--no-consumers` | Skip the search for broker client users that are not deployed |
+| `--admin-url <url>` | Pulsar admin URL (default: KLOK_PULSAR_ADMIN_URL, then https://broker1.ipaas.se:8443) |
+| `--token-url <url>` | Keycloak token endpoint of the broker superuser client (default: https://auth.ipaas.se/auth/realms/klok/protocol/openid-connect/token) |
+| `--vault-addr <url>` | Vault (default: VAULT_ADDR, then https://vault.ipaas.se:8200) |
+
+```
+Verdicts, most urgent first:
+  stale: old broker client running   (--broker only) the broker shows a connection of the service without Klok
+                                     metadata; overrules everything Git says
+  build failing                      the last pipeline on the default branch failed
+  stale: main ahead                  the default branch has commits the deployed image was not built from
+  stale: rebuilt, not rolled out (tag-only)
+                                     a later pipeline rebuilt the deployed commit under the same tag; the manifest did
+                                     not change, so the cluster still runs the deploying build
+  stale: catalog                     the deploying build used another broker client, Quarkus extension or klok-common
+                                     than the catalog has now (npm and Python: than the registry's latest)
+  unknown                            the deploying build, or its versions, could not be found
+  current                            none of the above
+
+The deploying build: the newest commit of the manifests repository that set the image (its message names the
+pipeline; an older commit is matched by its diff and the last pipeline of the commit before it). A digest-pinned
+image (<tag>@sha256:<digest>) is matched to the pipeline whose image job kept that digest in its image-digest
+artifact. Its versions: the gradle/klok-libs.versions.toml artifact of its build_java_job (or build_job); when it
+has expired, the jars on the classpath in that job's log, or the catalog commit the log names. npm and Python
+services: package-lock.json, uv.lock, poetry.lock or the requirements at the deployed commit.
+
+--broker reads the superuser client from Vault (secret/klok/environment/pulsar/klok-broker) with your own Vault
+token (VAULT_TOKEN or ~/.vault-token from `vault login`; in CI the job's login), trusts the Klok Root CA from
+Vault's pki/ca/pem, and only reads. Vault's own certificate is self-signed: set VAULT_CACERT (as for the vault CLI)
+or NODE_EXTRA_CA_CERTS. KLOK_PULSAR_TOKEN and KLOK_PULSAR_CA_FILE replace the Vault reads when you have them.
+
+Broker client versions: Java integrations do not declare the broker client; it comes with the Quarkus extension.
+The version shown is the resolved one: the classpath the build's documentation scan prints in the build log
+("resolved"), else computed from the build's catalog snapshot and the POMs of what the project declares, the
+highest of each library ("computed"). When the catalog's extension itself depends on an older broker client than
+the catalog names, a WARNING says so: rebuilding integrations cannot help until the extension is released.
+
+--broker also lists durable reply-subscriber-* subscriptions: broker clients before 0.3.7 made reply subscriptions
+durable (klok-brokerclient-java#10). One with consumers makes its service "stale: old broker client running"; ones
+without consumers are left behind, counted with their backlog, and never removed by this command.
+
+Exit codes: 0 everything is current; 5 a workload is stale or its build is failing, or (with --broker) a connection
+has no metadata or a durable reply subscription has consumers; 1 error. "unknown" alone does not fail. Use it as a
+gate after a rebuild.
+
+Examples:
+  klok fleet status                                  # every tenant in the manifests repository
+  klok fleet status --tenant klok --no-consumers     # one tenant, without the repository search
+  klok fleet status --broker                         # and who is connected to the broker
+  klok fleet status --json | jq '.status.rows[] | select(.verdict != "current") | .project'
+```
+
+### klok fleet rebuild
+
+```
+klok fleet rebuild [options]
+```
+
+Start the default branch pipeline of each selected project, wait for it and report how it ended; never cancels or retries
+
+| Option | Description |
+|---|---|
+| `--manifests-repo <path>` | GitLab path of the deploy manifests repository (default: KLOK_MANIFEST_REPO, then klok/environment/ipaas/ipaas-service-deploy-manifests) |
+| `--git-url <url>` | GitLab base URL (default: config gitUrl) |
+| `--token <token>` | GitLab personal access token (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `-j, --jobs <n>` | Parallel requests to GitLab and the broker (default: `8`) |
+| `--stale` | Every project whose workload `klok fleet status` calls stale (main ahead, rebuilt but not rolled out, an old catalog) |
+| `--project <path>` | A GitLab project path to rebuild; repeatable |
+| `-n, --dry-run` | Print what would be started, start nothing |
+| `--parallel <n>` | Pipelines to run at the same time (default: `1`) |
+| `--timeout <minutes>` | How long to wait for one pipeline before reporting it as still running (default: `60`) |
+
+```
+What it does: for each project, POST /projects/:id/pipeline on its default branch (a pipeline started through the
+API runs in full, also when the last commit was typed docs), wait until it ends, print the result and, when it
+failed, the failing job and the last lines of its log; then the next project. It never cancels, retries or deletes
+a pipeline: one that runs past --timeout is reported as still running and left alone. "build failing" projects are
+not part of --stale: fix the build first, then name them with --project. The token needs the api scope.
+
+Redeploying: after each successful pipeline the command reads the deploy job's result (`klok manifest update`)
+and says whether the manifest got a new image ("rolled out: <old> -> <new>") or kept its image ("unchanged"). A
+deploy job that pins the digest (`--digest-file`, the integration template) rolls out every rebuild; one that writes
+the tag alone rolls out nothing when the commit did not change.
+
+Exit codes: 0 every pipeline succeeded (or --dry-run); 1 any did not, or an error.
+
+Examples:
+  klok fleet rebuild --stale --dry-run                          # what would be started
+  klok fleet rebuild --stale                                    # one at a time, waiting for each
+  klok fleet rebuild --project klok/integration/klok-api-odl --project klok/integration/klok-api-ai --parallel 2
+  klok fleet status                                             # afterwards: is everything current?
+```
+
+## klok manifest
+
+```
+klok manifest [options] [command]
+```
+
+Deployment manifests in the GitOps repository that Argo CD applies
+
+### klok manifest update
+
+```
+klok manifest update [options]
+```
+
+Set the image of one container in one manifest file, then commit and push it
+
+| Option | Description |
+|---|---|
+| `--image <ref>` | Image to deploy, with its tag (default: KLOK_CONTAINER_IMAGE_SHA) |
+| `--digest <sha256:hex>` | Pin the image to this digest: <image>:<tag>@<digest> (default: KLOK_IMAGE_DIGEST) |
+| `--digest-file <path>` | Read the digest from this file, as kaniko --digest-file writes it; missing or empty is an error (default: KLOK_IMAGE_DIGEST_FILE) |
+| `--file <path>` | Manifest in the repository (default: KLOK_MANIFEST_FILE, MANIFEST_DEPLOYMENT_FILE, then <CI_PROJECT_PATH>/<CI_PROJECT_NAME>-crds.yaml) |
+| `--repo <path-or-url>` | GitLab path or git URL of the manifests repository (default: KLOK_MANIFEST_REPO, MANIFEST_REPO_URL, then klok/environment/ipaas/ipaas-service-deploy-manifests) |
+| `--container <name>` | Container to update (default: KLOK_MANIFEST_CONTAINER, else the only one in the file) |
+| `--workload <name>` | [<kind>/]<name> of the workload, when the container name repeats (default: KLOK_MANIFEST_WORKLOAD) |
+| `--branch <name>` | Branch to push to (default: KLOK_MANIFEST_BRANCH, then main) |
+| `-n, --dry-run` | Clone and edit, print the diff, commit and push nothing |
+
+```
+Digest: with --digest or --digest-file the manifest gets <image>:<tag>@sha256:<digest>. The tag stays for people;
+the runtime pulls by the digest. A rebuild under the same tag (a rerun on the same commit, say for a new dependency
+catalog) is then a new reference that Argo CD rolls out, while an image that came out byte for byte the same has
+the same digest and changes nothing. Without a digest the manifest says only the tag, and a new image under an old tag is
+never rolled out: nodes keep the copy they cached.
+
+Credentials: in CI the job logs in to Vault with its identity token (VAULT_ID_TOKEN) and the role
+<tenant>-ci-protected (KLOK_VAULT_DEPLOY_KEY_ROLE overrides it), which only pipelines of a protected branch or tag
+can use, and reads the deploy key and the pinned host key from secret/<tenant>/CICD_KEY and
+secret/<tenant>/KNOWN_HOSTS, where the tenant is KLOK_TENANT or the GitLab top level group. A tenant without that
+role falls back to VAULT_AUTH_ROLE with a warning. --dry-run clones with the key too. By hand, your ssh-agent (SSH_AUTH_SOCK) or GIT_SSH_COMMAND
+is used as it is. Commits are made as Klok CI unless GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL are set.
+
+Examples:
+  klok manifest update                                  # in an integration pipeline: everything from CI variables
+  klok manifest update --dry-run                        # clone, edit and show the diff; commit nothing
+  klok manifest update --digest-file image-digest       # pin to the digest the image job wrote
+  klok manifest update --image repo.klok.dev/jttl/application/biljett-shop/biljett-shop:62b24af3 \
+    --file jttl/application/biljett-shop.yaml
+  klok manifest update --file jttl/application/quickrace-com-cronjobs.yaml \
+    --workload quickrace-com-payouts --container curl --image curlimages/curl:8.12.1
+```
+
+## klok pin
+
+```
+klok pin [options] [command]
+```
+
+Pins of released artifacts in infrastructure repositories, changed through a merge request
+
+### klok pin update
+
+```
+klok pin update [options]
+```
+
+Set keys of a YAML file (a version, the sha256 of the released file) on a new branch and open a merge request
+
+| Option | Description |
+|---|---|
+| `--repo <path-or-url>` | GitLab path or git URL of the infrastructure repository (or KLOK_PIN_REPO) |
+| `--file <path>` | YAML file in that repository whose top-level keys hold the pin (or KLOK_PIN_FILE) |
+| `--set <key=value>` | Set a top-level key; repeatable; the value may use placeholders |
+| `--version-key <key>` | Set this key to the release version, the same as --set <key>={version} (or KLOK_PIN_VERSION_KEY) |
+| `--sha256-of <url-or-file>` | Download (or read) this file and put its sha256 in --sha256-key; placeholders allowed (or KLOK_PIN_SHA256_OF) |
+| `--sha256-key <key>` | The key that gets the sha256 (or KLOK_PIN_SHA256_KEY) |
+| `--release <file>` | Release file with group=, artifact=, version= (or KLOK_PIN_RELEASE; default build/klok-release.properties, read when a value uses a placeholder) |
+| `--name <name>` | What is pinned, for the branch and the title (or KLOK_PIN_NAME; default: the release artifact) |
+| `--scope <scope>` | Conventional Commits scope of the commit and the merge request title (or KLOK_PIN_SCOPE) |
+| `--docs-page <path>` | Page in the repository that says what to do after the merge; linked from the description (or KLOK_PIN_DOCS_PAGE) |
+| `--download-attempts <n>` | Download attempts before giving up (or KLOK_PIN_DOWNLOAD_ATTEMPTS; default 30) |
+| `--download-interval <seconds>` | Pause between download attempts (or KLOK_PIN_DOWNLOAD_INTERVAL; default 30) |
+| `-n, --dry-run` | Hash, clone and edit, print the diff and the merge request; push nothing |
+
+```
+Placeholders, filled in from the release file:
+  {group} {group-path} {artifact} {version}
+  {version-url}     the version URL-encoded (+ as %2B), for download URLs
+  {maven-central}   https://repo1.maven.org/maven2/{group-path}/{artifact}/{version-url}/{artifact}-{version-url}
+
+What it does: computes the values (the sha256 is of the downloaded file, retried while Maven Central's CDN catches
+up with the release), clones the repository's default branch, changes only the named keys' values in place
+(comments, order and quoting stay; a key the file does not have is an error), and pushes a new branch
+klok/pin/<artifact>-<version> whose push options make GitLab open the merge request. No API token is needed.
+When the default branch already has the values, or the branch already exists, it says so and exits 0.
+It refuses to push to the default branch and never force pushes; a person merges the merge request.
+
+Credentials: in CI the job logs in to Vault with its identity token (VAULT_ID_TOKEN) and the role
+<tenant>-ci-protected (KLOK_VAULT_DEPLOY_KEY_ROLE overrides it), which only pipelines of a protected branch or tag
+can use, and reads the tenant deploy key and the pinned host key from secret/<tenant>/CICD_KEY and
+secret/<tenant>/KNOWN_HOSTS. The key needs write access to the repository, and the merge request is opened as the
+GitLab user who added the key. What the key reaches and who can read it:
+https://docs.klok.dev/klok-environment-build-ci-templates/ci/authentication, "What the deploy key reaches, and
+why it is shared". By hand, your ssh-agent (SSH_AUTH_SOCK) or GIT_SSH_COMMAND is used.
+
+Examples:
+  # The entry filter's release pipeline, after release_and_publish_job:
+  klok pin update --repo klok/environment/klok-environment-setup \
+    --file ansible-master/playbooks/group_vars/all/pulsar_entry_filters.yml \
+    --version-key pulsar_entry_filters_version \
+    --sha256-key pulsar_entry_filters_sha256 --sha256-of '{maven-central}.nar' \
+    --scope pulsar --docs-page klok-docs/pulsar/entry-filters.md
+
+  # By hand, a dry run against a release file you have:
+  klok pin update --dry-run --release build/klok-release.properties --repo ... --file ... --version-key ...
+
+  # Without a release file:
+  klok pin update --repo ... --file vars.yml --name my-tool --set my_tool_version=1.2.3
+```
+
+## klok solutions
+
+```
+klok solutions [options] [command]
+```
+
+The integration solution registry (<tenant>/integration-solutions)
+
+### klok solutions validate
+
+```
+klok solutions validate [options]
+```
+
+Check every solutions/<SOLUTIONID>_<slug>/solution.meta.json against the descriptor contract
+
+| Option | Description |
+|---|---|
+| `--root <dir>` | Checkout of the registry (default: the current directory) |
+
+### klok solutions check
+
+```
+klok solutions check [options]
+```
+
+Compare the solution documents with the route classes on the default branch of every repository of the tenant in the workspace
+
+| Option | Description |
+|---|---|
+| `--root <dir>` | Checkout of the registry (default: the current directory) |
+| `--workspace <dir>` | Workspace root that `klok sync` mirrors into (default: the configured workspace) |
+| `--tenant-short <short>` | Route id prefix of the tenant (default: the one the registry's solution ids share) |
+
+## klok sync
+
+```
+klok sync [options] [command]
+```
+
+Mirror the GitLab repositories you can see into a local workspace
+
+### klok sync clone
+
+```
+klok sync clone [options]
+```
+
+Discover every repository you can see and clone the missing ones
+
+| Option | Description |
+|---|---|
+| `--git-url <url>` | GitLab base URL (default: config gitUrl) |
+| `-n, --dry-run` | Show what would happen and change nothing |
+| `-y, --yes` | Do not ask for confirmation |
+| `-w, --workspace <path>` | Workspace directory (default: config workspace) |
+| `--token <token>` | GitLab token (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `-j, --jobs <n>` | Parallel git operations (default: `6`) |
+| `--no-summary` | Skip the Kloker summaries |
+| `--summary-jobs <n>` | Parallel summary calls (default: `8`) |
+
+### klok sync pull
+
+```
+klok sync pull [options]
+```
+
+Fast-forward every repository in the workspace
+
+| Option | Description |
+|---|---|
+| `-w, --workspace <path>` | Workspace directory (default: config workspace) |
+| `--token <token>` | GitLab token (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `-j, --jobs <n>` | Parallel git operations (default: `6`) |
+| `--no-summary` | Skip the Kloker summaries |
+| `--summary-jobs <n>` | Parallel summary calls (default: `8`) |
+
+### klok sync status
+
+```
+klok sync status [options]
+```
+
+Show dirty trees, unpushed commits and branches behind their remote (as of the last fetch)
+
+| Option | Description |
+|---|---|
+| `-w, --workspace <path>` | Workspace directory (default: config workspace) |
+| `-j, --jobs <n>` | Parallel git operations (default: `12`) |
+| `-a, --all` | List every repository, not only the ones needing attention |
+| `--fetch` | Fetch every repository first, so "behind" is current |