Qualifying deployment manifest validation#

Run node --test tests/release/manifest.mjs in the Weles checkout with an accepted deployment manifest, not an invented release. Supply WELES_BIN as an absolute executable path, WELES_TEST_SOURCE_REVISION as the checkout revision, WELES_TEST_BINARY_SHA256 as the independently recorded executable digest, WELES_TEST_DEPLOYMENT_MANIFEST as the manifest path, WELES_TEST_DEPLOYMENT_SOURCE_REVISION as its accepted source, and WELES_TEST_CANDIDATE_TAG as its candidate tag.

The journey calls the real release validate-manifest CLI, checks its returned deployment identity and manifest digest, then checks named refusals for an escaping entrypoint, obsolete URL fields, a legacy platform name and a non-release URI. It retains the original manifest, negative inputs, commands, stdout, stderr and exit statuses under build/real-tests/release-manifest without modifying the accepted input. This qualifies CLI admission only; signed artifact retrieval, browser installation and browser execution require their own real flows.

Maintaining the CLI reference#

In the documentation checkout, run npm run docs:cli to refresh the command pages and reference from the real Weles executable. WELES_BIN selects the executable to inspect; npm run docs:cli -- --check compares the existing pages without rewriting them. The usage lines and option descriptions come from the same observed help document, while command purposes remain hand-written.

The generator reads the canonical documentation and requires its Usage and command-surface section before writing per-command pages. A missing section refuses with generate-cli-reference: cli page has no Usage and command-surface section; restore that section in src/content/docs/reference/cli.json and run the command again. That refusal leaves the generated command pages unchanged; it does not promise atomic publication if a later filesystem write fails.

Commands#

Usage

Usage:
  weles onboarding [status|next|import|verify|reset] [--subject <stable-id>] [--json]
  weles onboarding import <trajectory-export.json> --host <managed-worker-hostname> [--subject <stable-id>] [--json]
  weles onboarding verify --receipt <receipt.json> --keys <receipt-keys.json> [--subject <stable-id>] [--json]
  weles import <trajectory-export.json> --host <managed-worker-hostname> [--json]
  weles open <url> [--headless] [--browser chromium|firefox] [--wait-for-text <text>] [--text] [--screenshot <file>] [--json]
  weles screenshot <url> <file> [--headless] [--browser chromium|firefox] [--wait-for-text <text>] [--json]
  weles mcp
  weles release surface [--root <directory>]
  weles release enforce-version --decision <file> --baseline <file> --declaration <file> --manifest <file> [--json]
  weles release validate-manifest --manifest <file> --source-revision <sha> --candidate-tag <tag> [--json]
  weles release adopt-baseline --released <version> --published-surface <file> --reason <text> [--correcting <version>] [--json]
  weles design export-assets --provider figma --request <export-request.json>
  weles design parse-document --provider figma <document.json[.gz]> <summary.json> <nodes.json> [<vocabulary.json>]
  weles runs list [--json]
  weles runs show <run-id> [--json]
  weles runs answer <run-id> --ready|--approved|--not-received [--detail <text>] [--json]
  weles runs cancel <run-id> --detail <text> [--json]
  weles account-security --provider google --login-role <skarbiec-role> [--json]
  weles account-security --run <run-id> [--json]
  weles app-password --provider google --login-role <skarbiec-role> --organization <skrzynka-organization> [--json]
  weles app-password --provider google --login-item <skarbiec-item> --organization <skrzynka-organization> [--json]
  weles app-password --run <run-id> [--json]
  weles developer-certificate --provider apple --subject <dn> [--account-role <role>] --confirm "AUTHORIZE ONE APPLE DEVELOPER ID" --execution-host <host> --private-key-out <abs> --expires-in-minutes <n> [--execution-agent <agent>] [--json]
  weles developer-certificate --run <run-id> --certificate-out <abs> [--private-key <abs> --store-host <host>] [--json]
  weles login --provider apple [--account-role <role>] --confirm "AUTHORIZE ONE APPLE LOGIN" --execution-host <host> --expires-in-minutes <n> [--execution-agent <agent>] [--json]
  weles login --run <run-id> [--json]
  weles worker <status|version|start|stop|restart> [--json]
  weles keeper start --session <id> [--url <url>] [--headless]
  weles records adopt [--json]
  weles doctor [--json]
  weles version

Command surface (weles 0.7.56)
Command	Purpose
`weles onboarding [status\|next\|import\|verify\|reset] [--subject <stable-id>] [--json]`	First-use journey through the authorization boundary, optional existing-data adoption, and receipt-backed completion.
`weles onboarding import <trajectory-export.json> --host <managed-worker-hostname> [--subject <stable-id>] [--json]`	Adopt an existing Weles API trajectory export from inside the onboarding journey.
`weles onboarding verify --receipt <receipt.json> --keys <receipt-keys.json> [--subject <stable-id>] [--json]`	Verify a real terminal service receipt against trusted receipt keys, offline.
`weles import <trajectory-export.json> --host <managed-worker-hostname> [--json]`	Validate and durably adopt an existing Weles API trajectory export as host-bound drafts.
`weles open <url> [--headless] [--browser chromium\|firefox] [--wait-for-text <text>] [--text] [--screenshot <file>] [--json]`	Navigate in the fingerprinted browser and print one JSON result line.
`weles screenshot <url> <file> [--headless] [--browser chromium\|firefox] [--wait-for-text <text>] [--json]`	Navigate and save a full-page screenshot; same flags as open.
`weles mcp`	Start the Weles MCP server (dist/mcp.js).
`weles release surface [--root <directory>]`	Report everything this build publishes — library exports, CLI commands, MCP tools, worker HTTP routes, API schemas — read from the source through the TypeScript program.
`weles release enforce-version --decision <file> --baseline <file> --declaration <file> --manifest <file> [--json]`	Judge AutoVersion's decision, the released baseline, the repository's version declaration and the package manifest against each other, and refuse every disagreement.
`weles release validate-manifest --manifest <file> --source-revision <sha> --candidate-tag <tag> [--json]`	Judge a candidate deployment manifest against the accepted source revision and candidate tag. Artifact entries use platform, uri, sha256 and entrypoint: uri names a stado://releases/<product>/<version>/<platform>/<archive> coordinate; supported platforms are darwin-arm64, darwin-amd64 and linux-amd64. Missing or obsolete fields, unsupported platforms, invalid release coordinates and entrypoints outside the archive are refused by field name. Validation does not fetch an archive, verify its signed publication, install a browser or prove browser readiness.
`weles release adopt-baseline --released <version> --published-surface <file> --reason <text> [--correcting <version>] [--json]`	Record what a release published: write the released surface and the version declaration from the surface document that release carried, so the version gate judges later revisions against a real release instead of a hand-kept claim. Refuses a baseline that moves backwards unless the caller names the version being overridden, and refuses a surface document that names nothing.
`weles design export-assets --provider figma --request <export-request.json>`	Export every Figma file in the explicit --request inventory, without organization-name filtering. The request names an existing clean checkout, one Git remote and branch, and the exact Skarbiec scope, item, field and workload identity. No repository is cloned or removed and no private account, SSH key, team or checkout is built in. The managed figma directory receives documents, nodes, assets and vocabulary; publication succeeds only after the remote branch reads back the new commit. The manual Actions form requires both runner_label and request_file and runs this same command. See the CLI reference's Design export section for the request format, prerequisites and retained failure state.
`weles design parse-document --provider figma <document.json[.gz]> <summary.json> <nodes.json> [<vocabulary.json>]`	Parse one exported design document into its summary, its node table and its vocabulary without contacting the design tool, with the same parser the export uses; fewer than the three required paths is refused with the full usage line.
`weles runs list [--json]`	List every run the managed worker has a live child for, with how long ago each last wrote anything and, for a run that waits for a person, the instruction, whether the person was paged and whether its process still waits.
`weles runs show <run-id> [--json]`	Print a running run's last output lines, its account and stage for a sign-in and the request it waits on with every page, answer and note, or the record of a finished run.
`weles runs answer <run-id> --ready\|--approved\|--not-received [--detail <text>] [--json]`	Tell a run that waits for a person what the person did: --ready lets a Google phone approval send Google's prompt now (none is sent before), --not-received makes it press Google's Resend it for a prompt that never arrived or expired (or end with google_prompt_not_received when Google offers none), --approved makes it record what Google still shows. A run that waits on nobody is refused with the stage it stands at, a finished run with when.
`weles runs cancel <run-id> --detail <text> [--json]`	End a run the managed worker is running: its process group is killed and the run is recorded as cancelled with --detail; a cancelled sign-in no longer holds the account. A finished run is refused with when.
`weles account-security --provider google --login-role <skarbiec-role> [--json]`	Submit a read-only Google 2FA observation from an exact Skarbiec account, or read a persisted run. No local browser, fresh sign-in or account changes; a missing observation remains unknown.
`weles app-password --provider google --login-role <skarbiec-role> --organization <skrzynka-organization> [--json]`	Sign in to an exact Skarbiec Google account, create a Google app password and hand it to Skrzynka under the organization --organization names, which is required; with --run, read that persisted run.
`weles developer-certificate --provider apple --subject <dn> [--account-role <role>] --confirm "AUTHORIZE ONE APPLE DEVELOPER ID" --execution-host <host> --private-key-out <abs> --expires-in-minutes <n> [--execution-agent <agent>] [--json]`	Issue one developer certificate at the certificate authority --provider names (apple is the one Weles implements) for a private key generated on this machine under the distinguished name --subject gives, which is required; with --run, read the issued certificate back and, with --private-key and --store-host together, store the signing identity in the named host's vault instead of leaving it in files.
`weles login --provider apple [--account-role <role>] --confirm "AUTHORIZE ONE APPLE LOGIN" --execution-host <host> --expires-in-minutes <n> [--execution-agent <agent>] [--json]`	Sign one Skarbiec account in at the identity provider --provider names (apple is the one Weles implements, none is assumed) on a Stado host, under a one-time authorization the operator confirms in words; with --run, read that run and its receipt back.
`weles worker <status\|version\|start\|stop\|restart> [--json]`	Read or manage the Weles executor through its authenticated worker API. WELES_WORKER_API_BASE with WELES_WORKER_TOKEN names it explicitly; otherwise Stado resolves weles-admission for consumer operator and the bearer is the token of the item playing the role echo-weles-api.
`weles keeper start --session <id> [--url <url>] [--headless]`	Hold one browser session open and answer JSON commands on ~/.weles/keeper/<id>/socket until its page closes, so several trajectories drive one signed-in page in turn; a session whose socket already exists is refused by name.
`weles records adopt [--json]`	Tag every Weles record in this vault with weles:record:<kind> from its own context, so records written before the tags existed are found by the same lookup as new ones.
`weles doctor [--json]`	Print installation diagnostics and subscriptionAuthentication from the live Skarbiec inventory: resolved account identities, login methods, account revisions and exact resolution failures. Weles has no separate account catalogue. Brama uses authenticated POST /reauth/resolve with provider and subscription_id for the same read-only resolution, then POST /reauth with account_revision to perform OAuth and persist the credential to the same Skarbiec item. source_revision identifies the Weles release. Neither provider CLIs nor copied local sessions are used.
`weles version`	Print the version string.

Exit status#

0 when the command did what it promises. 2 when the invocation itself is wrong, before anything runs: an unknown command, a missing argument such as `open requires <url>` or `runs answer requires <run-id>`, a missing or contradictory flag such as `runs answer requires exactly one of --approved or --not-received` or `login needs --provider naming the identity provider to sign in to; Weles signs in to apple`, or an option a command does not take (`login takes either …; got …`, `worker requires …; only --json is accepted`). 1 for every other failure, including `weles import` when any row was refused and a run whose result is not ok. The message on standard error starts with `weles:` and names what was wrong.

Environment variables#

Variables reported by weles doctor
Variable	Effect
`CHROMIUM_PATH`	Path to a custom Chromium binary, overriding the managed build.
`WELES_USE_STOCK_CHROMIUM`	Set to opt out of the managed Chromium build.
`WELES_API_BASE, WELES_TOKEN, WISENT_ORGANIZATION_ID`	Deployment endpoint, organization-scoped token, and organization UUID used by the client library and by weles import. They are never required by open or screenshot.