kronika onboarding
Present or move the first-use journey from the command line: the same screens, progress and first-success fact the graphical importer walks, read from Kronika's own packaged journey and kept under Kronika's own state.
Invocation
kronika onboarding [--advance | --skip | --reset | --status] [--json]
With no action the current screen is shown and an attempt is started when none exists. Name only one action: combining or repeating action flags is refused before journey state is read or changed, regardless of their order.
Inputs and options
| Option | Effect |
|---|---|
--advance | Moves to the next screen along the journey's own transitions. |
--skip | Leaves the journey without completing it; the workspace stays usable. |
--reset | Discards the recorded attempt and replays the journey from its entry screen. |
--status | Reports an existing attempt without starting one; with none, the entry screen as not started. |
--json | Prints the view below as JSON instead of the text a person reads. |
No Brama configuration is read. When KRONIKA_STADO_INTEGRATION_TOKEN and the control-plane origin are set, progress is also mirrored to the control plane; without them local progress is authoritative and nothing is refused.
Output and state
Stdout is the current screen: status (not_started, in_progress, completed or skipped), screenId, screenKind, step of stepCount, title, body, actions, the screen's command and expected result when it declares them, completedScreenIds and firstSuccessFact. Completion is recorded only when the fact is observed — kronika init adopting or recognising a workspace — never by viewing a screen. Progress is written under Kronika's state directory; a persisted attempt is resumed only when it belongs to this journey version and this installation, otherwise a fresh attempt starts.
Exact refusals
onboarding accepts one action; --<first> conflicts with --<second>— combining or repeating action flags is a usage refusal; no journey operation is performed.- An existing state that cannot be read or parsed refuses with its path and actual cause. Unsupported schema or malformed required
installation_id,pending_events,evidenceormetarefuses by field instead of replacing retained data or creating another installation identity. Only an absent file starts fresh; the CLI and graphical journey share this store. onboarding bundle envelope is invalid,onboarding bundle identity is invalid,onboarding bundle integrity is invalid,onboarding screen graph is invalid,onboarding screen is invalid,onboarding entry screen is missing,onboarding fallback is missing,onboarding transition is invalid— a journey bundle that does not validate; the packaged canonical journey is used in its place where one is available.onboarding progress points at an unknown screen— a recorded attempt names a screen the journey no longer has.onboarding control plane is unavailable,onboarding control plane URL is invalid,onboarding control plane rejected the request— the mirror to the control plane, reported when it was configured and did not answer; local progress stays authoritative.
Operational refusals are written to stderr as kronika: <message> and exit 1. Conflicting actions and unsupported options exit 2 with usage; unsupported options name the command and flag as onboarding does not accept <flag>.
Real CLI refusal qualification: node tests/cli/refusals.mjs, with KRONIKA_TEST_CLI_BIN, KRONIKA_TEST_SOURCE_REVISION, KRONIKA_TEST_SUCCESS_EXIT, KRONIKA_TEST_USAGE_EXIT and KRONIKA_TEST_OPERATIONAL_EXIT declared for the installed binary. Usage refusals must create no state. The journey then starts real local onboarding, damages only its owned state, requires parse/field refusals without rewriting bytes, restores the original and checks identity-preserving recovery. Optional control-plane configuration is absent. Revision, binary digest, commands, outputs and exit statuses remain under .build/cli-refusals/<run>/report.json.