Commands#

Usage

Usage:
  weles onboarding [status|next|import|verify|reset] [--subject <stable-id>]
  weles onboarding import <trajectory-export.json> --host <managed-worker-hostname> [--subject <stable-id>]
  weles onboarding verify --receipt <receipt.json> --keys <receipt-keys.json> [--subject <stable-id>]
  weles import <trajectory-export.json> --host <managed-worker-hostname>
  weles open <url> [--headless] [--browser chromium|firefox] [--wait-for-text <text>] [--text] [--screenshot <file>] [--timeout <ms>]
  weles screenshot <url> <file> [--headless] [--browser chromium|firefox] [--wait-for-text <text>] [--timeout <ms>]
  weles mcp
  weles release surface
  weles release enforce-version --decision <file> --baseline <file> --declaration <file> --manifest <file>
  weles release validate-manifest --manifest <file> --source-revision <sha> --candidate-tag <tag>
  weles figma export-design-assets
  weles doctor
  weles version

Command surface (weles 0.6.5)
Command	Purpose
`weles onboarding [status\|next\|import\|verify\|reset] [--subject <stable-id>]`	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>]`	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>]`	Verify a real terminal service receipt against trusted receipt keys, offline.
`weles import <trajectory-export.json> --host <managed-worker-hostname>`	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>] [--timeout <ms>]`	Navigate in the fingerprinted browser and print one JSON result line.
`weles screenshot <url> <file> [--headless] [--browser chromium\|firefox] [--wait-for-text <text>] [--timeout <ms>]`	Navigate and save a full-page screenshot; same flags as open.
`weles mcp`	Start the Weles MCP server (dist/mcp.js).
`weles release surface`	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>`	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>`	Judge a candidate deployment manifest against the revision the release is for and the tag cut for it.
`weles figma export-design-assets`	Export the organization's Figma design files and publish them to the design-assets repository.
`weles doctor`	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.

Subscription authentication#

Brama resolves provider and subscription_id with POST /reauth/resolve, then submits the returned account_revision to POST /reauth. Weles uses the matching Skarbiec login on its Stado-selected host and persists the OAuth grant to that same subscription. A successful browser login alone is not repair: Brama must refresh the stored credential successfully.

Google may offer Enter your password instead of showing a password field. Weles selects that visible method before Try another way. It does not treat a hidden Too many failed attempts template as a refusal, and it does not repeatedly submit the selected challenge.

A visible Google refusal returns BROWSER_NOT_SECURE or provider_challenge_refused. If the chosen password field never appears, google_password_challenge_unavailable records the observed host, path and visible text. These failures retain the actual stage and are not automatically retried against unchanged identity and software.

Get a code to sign in is an unfinished Google verification step, even without a 2-Step Verification heading. Weles recognizes the challenge URL and visible page, and waits for a submitted code to leave that challenge before continuing. google_2fa_material_missing means the selected Skarbiec login has no authenticator seed or supplied one-time code; no alternative that sends a notification or SMS is selected. google_sign_in_state_unavailable means navigation prevented an observed state, not that authentication succeeded. Stado credentials seed-freshness reports stored seed availability separately from successful login evidence.

Read GET /diagnostics/<run_id> and its run-result.json entry for the recorded result, source_revision and retained DOM, network and video files. Session closure stops its measurement timers; a recorded failure must not be converted into a later worker timeout.

Navigation commands (open, screenshot)#

stdout carries exactly one JSON line — ok, url, title, status, plus screenshot and/or text when requested; narration goes to stderr. weles screenshot takes the destination file as its positional argument and otherwise behaves like weles open.

Arguments | Default | Description
Argument	Default	Description
`--headless`	off	Run the browser headlessly.
`--browser <name>`	chromium	Browser engine passed to AsyncNewBrowser (chromium or firefox).
`--os <name>`	macos	Persona OS passed to AsyncNewBrowser.
`--locale <locale>`	(unset)	Locale passed to AsyncNewBrowser.
`--chromium-path <path>`	CHROMIUM_PATH or managed build	Custom Chromium binary path.
`--user-data-dir <dir>`	(temporary)	Browser profile directory; reuse it to keep a session across runs.
`--proxy <url>`	(direct)	Proxy server URL for the browsing context.
`--text`	off	Print document body text after navigation (open).
`--screenshot <file>`	(none)	Save a full-page screenshot after navigation (open).
`--timeout <ms>`	(engine default)	Navigation timeout in milliseconds.

Onboarding#

Arguments | Default | Description
Argument	Default	Description
`status \| next \| import \| verify \| reset`	Journey action: read the current screen, advance or skip optional import, adopt an existing export, cryptographically verify a real receipt, or reset progress.
`--subject <stable-id>`	(host default)	Stable operator/device scope for durable onboarding progress.
`--state-dir <dir>`	(platform default)	Override the durable onboarding state directory.
`--receipt <file>`	(required for verify)	Real terminal Weles service receipt JSON to verify.
`--keys <file>`	(required for verify)	JSON map of trusted receipt key IDs to PEM public keys; must be a non-empty object.

Existing-data import#

weles import is reusable outside onboarding. weles onboarding import calls the same operation from the optional existing-data step and records that step only after accepted destination state is returned. Any refused item makes the CLI exit nonzero while preserving the complete JSON result on stdout.

Arguments | Default | Description
Argument	Default	Description
`<trajectory-export.json>`	(required)	Exact JSON response from the Weles trajectories list endpoint, or one bare trajectory detail response; at most 2 MiB.
`--host <hostname>`	(required)	Exact managed Weles worker OS hostname stored with every newly imported draft.
`WELES_API_BASE`	(required)	HTTPS destination deployment; plaintext HTTP is accepted only for loopback.
`WISENT_ORGANIZATION_ID`	(required)	Destination organization UUID, which must match every source tenant_id.
`WELES_TOKEN`	(required)	Organization-scoped bearer carrying trajectories:write.

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.