This page is generated from the help of the two CLIs: flint (your Flints) and nuu (the identity of this machine, the NUU account, the org, and the network). Do not edit it by hand. To make it again, run node scripts/gen-cli-reference.mjs --out <this file> in the repo flint. --check <this file> fails when a command or a flag of the help is missing here.
Each command also prints its help: flint <command> --help, nuu <command> --help.
The Obsidian rows that other commands print, and the Obsidian commands that 0.7.0 removed, are in Obsidian in Other Commands.
Create a Flint: a folder with a Mesh, shards, a Git repository, and an Obsidian vault
Argument
Description
name
The name of the Flint
Option
Description
-p, --path <dir>
The parent folder (default: this folder)
--preset <name>
The first shards (default: blank). See the presets below
--org <slug|none>
The org (default: the default org of this machine, or none)
--org-id <uuid>
The id of that org, when this machine does not know it
--visibility <level>
private | org | public (default: org with an org, else private)
--no-obsidian
Skip Obsidian for this run only (flint config set obsidian off turns it off on this machine)
--open
Open the Flint in Obsidian now (default: only in a terminal and without --json)
--no-open
Do not launch Obsidian now; the payload is installed
--no-git
No Git repository
--from <url>
Clone a Flint from Git (its files give the name and the org)
--resume <path>
Complete a creation that stopped
--type <type>
guide or member (see the types below)
--about <address>
Type guide: the entity that the Guide is about
--regarding <org>
Type member: the org slug or id
--verbose
Show every step, the shard install lines, and the kernel changes
--json
One JSON result on stdout. The progress goes to stderr
A Flint name uses the letters A to Z, the digits 0 to 9, spaces, and the characters - ' , . ! & + ; @. It has at most 100 characters. It does not end with a space or a dot.Presets: blank flint, orbh (default) Ask the agent what the Flint is for garden flint, orbh, notepad quarry flint, orbh, notepad lab flint, orbh, notepad, plan observatory flint, orbh, reports factory flint, orbh, projects, increments, reports default flint, orbh, and 7 shards for projects, plans, and reportsTypes (most Flints need no type): --type guide --about <address> A Guide about an entity --type member --regarding <org> Your Member Flint of an org flint setup always makes the Computer Flint. flint create does not make it.Examples: flint create "My Notes" flint create "Team Notes" --org none flint create "Server Notes" --no-obsidian flint create --from git@github.com:owner/notes.git
A Flint name or reference, such as "NUU Flint" or "(Guide) NUU Cognition". The word computer is the Computer Flint of this machine. With a second argument: a type
name
The name, when the first argument is a type: flint open guide "NUU Cognition"
Option
Description
--no-launch
Resolve and print the target without opening Obsidian
A Flint name or reference, such as "NUU Flint" or "(Guide) NUU Cognition". The word computer is the Computer Flint of this machine. With a second argument: a type
name
The name, when the first argument is a type: flint cd guide "NUU Cognition"
Set the org of this Flint. The id comes from --id, the enrollment of this machine, or a Flint of this machine with that org. none removes the org: a Flint with no org is local (@/)
Argument
Description
org
The org slug, the org id, or none
Option
Description
--id <uuid>
The id of the org. The admin of the org gives it. Not needed when this machine knows the org
Make the lock match the specs: resolve each spec, record the registry answers, install what is missing. With a source: install one or more shards (a package spec @org/name[@range][#place], a bare name, the name of a shard source, a path, or owner/repo). With --core: install each missing core shard
Argument
Description
sources
Package specs (e.g. @nuucognition/notepad@^1.1, notepad), the names of shard sources, paths, or owner/repo
Option
Description
-f, --force
Overwrite existing shard files
--all-dev
Build the shard of every shard source
--core
Install each core shard (Flint, Orbh) that this Flint does not have; leave the present ones alone
--no-deps
Install the shard alone: do not install its missing dependencies first
--with-deps
Install the missing dependencies first (the default)
--from-git <owner/repo[#ref]>
Install from a Git location (a tag, a branch, or a commit after #); the registry names the package and its state
--from-path <dir>
Install from a folder on this machine (a path record)
--alias <alias>
The local name of the shard in this Flint (the key in flint.toml); the slug of the package by default. Needed for a second shard with the same slug.
--reference
Install by reference (use = "reference"): no copy under Shards/; the loader reads the source folder on this machine. Not for a GitHub source.
-p, --path <dir>
Path to flint
--dry-run
With no source: show the plan and the registry answers, and write nothing
--json
Output one JSON object with retained files (with no source: the operation report)
Move the lock inside the range of each spec: the pnpm update of Flint. Updates every installed shard, or one shard by its alias, shorthand, or id; a build of a source is skipped
Argument
Description
ref
The shard to update: the package name, the alias, the shorthand, or the id. Default: every installed shard
Option
Description
-p, --path <dir>
Path to flint
--reinstall
Force re-download and reinstall all installed shards regardless of version
Release a version: build from a clean export of HEAD, tag v<version>, push, register with the NUU Shard Registry, and lock the shard as published when the registry lists the version
Argument
Description
name
The package name, the alias, the shorthand, or the id of the source
version
Version to release (default: read from shard.yaml)
Option
Description
--org <slug>
Register under this org: a slug that this machine knows. Default: the org of the Flint. A Flint with no org does not publish, also with --org
--no-register
Tag and push only; do not register with the NUU Shard Registry
--json
One JSON value: { ok, alias, version, tag, sha, hash, repo, registered, registry, slug, state } or { ok: false, code, reason, next }
Release a version of a module source: run its build step, check that the build output is committed, tag v<version>, push, register the module with the NUU Shard Registry, and lock it as published when the registry lists the version
Argument
Description
name
The module name, or the source folder name
version
Version to release (default: read from module.yaml)
Option
Description
--org <slug>
Register under this org: a slug that this machine knows. Default: the org of the Flint. A Flint with no org does not publish, also with --org
--no-register
Tag and push only; do not register with the NUU Shard Registry
--json
One JSON value: { ok, alias, version, tag, sha, hash, repo, registered, registry, slug, state } or { ok: false, code, reason, next }
Set a value in the Flint CLI config file (~/.nuucognition/flint-dev/config.toml)
Argument
Description
key
Config key (dot notation, e.g. orbit.devOrigins): a dotted key is a nested table. obsidian takes on or off; obsidian-trust takes auto or ask; update-check takes on or off
Map a GitHub owner to an org: one [orgs.<slug>] table in the NUU config (~/.nuucognition/config.toml). flint migrate run reads it for the Git records that the registry does not know
Argument
Description
slug
The org slug, for example nuu-cognition
github-owner
The GitHub user or organization whose repositories hold the shards of the org
Harness runtime or runtime/name (agy, claude, codex, cursor, droid, grok, kimi, muse, opencode). Omit it to use the default target list; the first argument is then the prompt
prompt
Prompt for the agent (or pass --prompt-file)
Option
Description
--prompt-file <path>
Read the prompt from a UTF-8 file instead of the argument. Keeps a typed launch command short when the prompt is long.
--continues <sessionId>
Link as continuation of another session
--max-turns <n>
Maximum number of agent turns
--budget <usd>
Maximum budget in USD (where supported by the harness)
--model <model>
Model override
--account <name>
Harness account name, or 'none' to bypass the runtime default
--allow-switch
Let the account autoswitch move an explicit --account to a good fallback account when it is limited
--allow-manual-only
Let --account name a manual-only account (auth manual-only)
--title <title>
Pre-set session title (skips agent self-registration)
--description <description>
Pre-set session description
--application <name>
Tag the session with the launching application (also read from ORBH_APPLICATION); tagged sessions are hidden from list, active, and the cockpit by default
--fleet <handle>
Make the new session a member of this open fleet (stamp via launch, one roster event)
--declare-fleet <handle>
Declare a new fleet with the new session as its root (needs --charter-file)
--charter-file <path>
The charter of the fleet that --declare-fleet declares: the goal, the boundary, and the done condition
--fleet-name <name>
The display name of the fleet that --declare-fleet declares (default: the handle in Title Case)
--force
Bypass the live-run guard (may create concurrent runtimes)
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Run one unattended inference turn and print its returned string
Argument
Description
targetOrPrompt
Harness runtime or runtime/name (agy, claude, codex, cursor, droid, grok, kimi, muse, opencode); with --continue, the complete prompt
prompt
Complete prompt for a fresh ping
Option
Description
-c, --continue <predecessorId>
Continue a returned ping in a new spool
--account <name>
Harness account name, or 'none' to bypass the runtime default
--application <name>
Tag the session with the launching application (also read from ORBH_APPLICATION); tagged sessions are hidden from list, active, and the cockpit by default
--json
Print {"sessionId","result"} so the returned ping can be chained with --continue
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Launch an interactive agent TUI with Orbh session tracking; --continue follows a completed compaction to its successor
Argument
Description
target
Harness runtime or runtime/name (agy, claude, codex, cursor, droid, grok, kimi, muse, opencode). Omit it to use the default target list; the first argument is then the prompt
prompt
Optional initial prompt (or pass --prompt-file)
Option
Description
--dev-channels
Load development MCP channels (e.g. orbh)
--prompt-file <path>
Read the prompt from a UTF-8 file instead of the argument. Keeps a typed launch command short when the prompt is long.
-c, --continue <sessionId>
Continue a previous Orbh session (completed compaction predecessors resolve to the successor)
--continues <sessionId>
Link as continuation of another session (new session)
--session-id <uuid>
Pre-allocate the new session id (full UUID). Lets an external launcher know the id before the session registers.
--model <model>
Model override
--account <name>
Harness account name, or 'none' to bypass the runtime default
--no-detach
Run in legacy foreground handoff mode instead of attaching to a detachable daemon
--detached
Start the detachable daemon and return at once: print the session id and the attach command, attach nothing (detached launch)
--plain
Use the explicit raw transport mode instead of the App Layer
--detachable
Run as a detachable daemon (deprecated; detachable is the TTY default — use --no-detach to opt out)
--close-after <seconds>
Bounded run: close the runtime + TTY after N seconds (testing/acceptance)
--force
Bypass the live-run guard when continuing (may create concurrent runtimes)
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Launch a request turn and wait for its correlated result, or post a deferred question to an existing session
Argument
Description
target
Runtime/name target, session ID, or prompt (with --runtime, or with no target: the default target list applies)
text
Prompt text or deferred question
Option
Description
--runtime <runtime>
Harness runtime or runtime/name target (alternative to positional runtime)
--stream
Stream the live transcript while waiting
--stream-attempt <json>
Reserved stream binding (used by step start)
-c, --continue <sessionId>
Resume a previous session and wait for the result of the turn this command initiates
--continues <sessionId>
Link as continuation of another session (new session)
--max-turns <n>
Maximum number of agent turns
--budget <usd>
Maximum budget in USD (where supported by the harness)
--model <model>
Model override
--account <name>
Harness account name, or 'none' to bypass the runtime default
--allow-switch
Let the account autoswitch move an explicit --account to a good fallback account when it is limited
--allow-manual-only
Let --account name a manual-only account (auth manual-only)
--title <title>
Pre-set session title
--description <description>
Pre-set session description
--application <name>
Tag the session with the launching application (also read from ORBH_APPLICATION); tagged sessions are hidden from list, active, and the cockpit by default
--timeout <seconds>
Maximum time to wait before detaching
--output-schema <schema>
JSON Schema (a file path, or inline JSON) that each return of the new session must match; a matching return is stored as result.structured
--json
Print the result as JSON: the structured value when the return matched an output schema, else the text as a JSON string (implies -q)
-q, --quiet
Suppress spinner and status output, print only the raw result (for agent use)
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Attach to a detachable interactive session, following completed compaction predecessors to their successor; browse detached sessions when no id is given. Modern clients cut over automatically during compaction; failed or legacy cutover prints flint orbh attach <successor> for manual recovery. Detach with Ctrl-\ or orbh detach <id>.
Argument
Description
id
Session ID (full or partial)
Option
Description
--print
Print the detached-session table instead of opening the picker (no id only)
--json
Print the detached-session listing as JSON (no id only)
--plain
Use the explicit raw transport mode instead of the App Layer
--steal
Deprecated no-op: attach always takes over automatically; the displaced client is notified
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Detach the active client of a detachable interactive session from another terminal — the agent keeps running. Self-targets via ORBH_SESSION_ID inside a harness.
Argument
Description
id
Session ID (full or partial). Optional when ORBH_SESSION_ID is set.
Option
Description
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Agent-facing session lifecycle commands. Compaction moved to flint orbh compact start / handoff / finish (agent-authored handoff, in-process only). When ORBH_SESSION_ID is set, <id> may be omitted for self-targeting actions (register, return, set, get, ask).
Argument
Description
id
Session ID (full or partial), or the action verb when ORBH_SESSION_ID is set
action
Action: register, return, set, get, ask, note — or use "await" for event subscription
value
Arguments for the selected action
Option
Description
--timeout <seconds>
Timeout in seconds (default: "3600")
-f, --filter <key=value>
Filter payloads by field value (for await); repeat to add more (default: [])
--list
List available event types (for await)
--host <host>
Server host override (for await)
--port <port>
Server port override (for await)
--orb-store-dir <path>
Override the Orb store directory (.orb) used to locate the server (for await)
--config <path>
Path to orbh.toml (for await)
--finish
Return this turn and finish the session (default)
--await
Return this turn and leave the session awaiting follow-up
--until-group <group>
With return --await: resume when every job in this group is terminal
--barrier-timeout <seconds>
With return --await --until-group: fail still-running group jobs after this many seconds
--wake-at <when>
With return --await: wake on a schedule. ISO 8601 datetime (2026-07-26T14:02) or +duration (+45m, +2h, +1h30m, +1d)
--wide
Render full-width list output without narrow stacking
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Compaction has moved to its own in-process lifecycle: flint orbh compact start Print the handoff contract + the path to write it to; hold the pager, show [Compacting...]. flint orbh compact handoff TURN-ENDING: validate the handoff, end this context, and relaunch the same session; use --into runtime/profile to change runtime or profile. flint orbh compact finish In the fresh context, confirm the handoff was read and clear the compaction marker. flint orbh compact abort Release the pager hold if you decide not to compact.
Close this session — record closed retention, terminate the harness, then close the bound Obsidian terminal tab. Pass --no-leaf to leave the tab open at a shell prompt. Self-targets via ORBH_SESSION_ID when run from inside an Orbh harness.
Argument
Description
id
Session ID (full or partial). Optional when ORBH_SESSION_ID is set.
Option
Description
--no-leaf
Leave the bound Obsidian terminal tab open — the pane returns to a shell prompt
--obsidian
Deprecated: closing the bound tab is now the default. Accepted so existing callers keep working
--force
Close even when descendant sessions still run; they keep running without a parent
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Await further activity for this session (the legacy park spelling) — record awaiting retention, pin it to flint orbh c, ensure the Orbh orchestrator wake sweep, terminate the current harness turn, then close the bound Obsidian terminal tab. Pass --no-leaf to leave the tab open at a shell prompt. With --until-group, await the all-terminal job-group barrier. Self-targets via ORBH_SESSION_ID when run from inside an Orbh harness.
Argument
Description
id
Session ID (full or partial). Optional when ORBH_SESSION_ID is set.
Option
Description
--until-group <group>
Await until every job in this group reaches a terminal state (done OR failed), then resume with the results
--barrier-timeout <seconds>
With --until-group: force-resolve the barrier after this many seconds (still-running group jobs are marked failed) so the session can never be stranded
--force
Allow parking a confirmed-live run when no interactive manager can terminate it, or another session whose descendant sessions still run
--no-leaf
Leave the bound Obsidian terminal tab open — the pane returns to a shell prompt
--obsidian
Deprecated: closing the bound tab is now the default. Accepted so existing callers keep working
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Discard this session — tombstone its entry (event-sourced; hidden from flint orbh list), terminate the harness, then close the bound Obsidian terminal tab. Pass --no-leaf to leave the tab open at a shell prompt. No confirmation. Self-targets via ORBH_SESSION_ID when run from inside an Orbh harness.
Argument
Description
id
Session ID (full or partial). Optional when ORBH_SESSION_ID is set.
Option
Description
--no-leaf
Leave the bound Obsidian terminal tab open — the pane returns to a shell prompt
--obsidian
Deprecated: closing the bound tab is now the default. Accepted so existing callers keep working
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Open the Sessions cockpit in a TTY; use --print for the static table or --json for machine-readable output
Option
Description
-a, --all
Include sessions hidden from the default work queue: discarded sessions and application-tagged sessions, which print under a Special section (--print/--json only; the cockpit toggles them with x)
--application <name>
Only sessions tagged with this application (implies --all for them)
-s, --stats
Print token/turn stats (prefers persisted run context; otherwise reads transcripts)
-S, --status <status>
Filter by session workState (e.g. working, finished)
-r, --runtime <runtime>
Filter by runtime (e.g. claude, codex)
-q, --search <text>
Search the id prefix, title, description, and prompt (case-insensitive)
--json
Print machine-readable JSON (the default when invoked from inside an Orbh session)
--print
Print the static session table instead of opening the cockpit
--wide
Print the static table full-width without narrow stacking
--subagents
Flatten subagent sessions into top-level rows instead of rendering dispatch trees
--all-scopes
List sessions machine-wide — every registered Flint store plus ~/.orb — grouped by scope (static table output)
--detached
Only detached-interactive sessions
--fleet <handle>
Only the members of the declared fleet <handle>: the root, the sessions that carry its stamp, and its explicit members
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Pre-flight probe: print which Orb store the next command will resolve to, and why. Read-only, takes no session id, creates nothing. With --expect it exits non-zero on a mismatch, so a brief can require it before any mutating verb.
Option
Description
--expect <dir>
Assert the resolved store root equals this path; exit 1 if it does not
--json
Machine-readable output
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Schedules use minute-resolution, 5-field cron expressions.The per-machine orchestrator checks schedules every 60 seconds and fires headless sessions; no server is required.
Import a saved session bundle as a full Orbh session on this machine (same session id)
Argument
Description
bundleDir
Path to a bundle directory (contains bundle.json with an orb/ spool bundle)
Option
Description
--cwd <dir>
Working directory the restored native files are keyed to (default: the bundle's recorded cwd when it exists here, else the context root)
--account <name>
THIS-machine account the imported session runs under (default: same-name match against the session's pinned account)
--force
Replace an existing spool with the same id, and overwrite differing native files; refuses a session with a running run or a live manager (end the run first)
--servers-confirmed <note>
Below writer epoch 2, confirm with a note that no process outside the registries (Flint servers, Orbh servers, collectors) of an older build runs; a --force import over an existing spool needs it
--check
Write nothing: print the session id, whether it exists here, and every native file the import would write with its current existence
--json
With --check: print the check as JSON
--no-record-paths
Record no path of this machine (the bundle directory, the store root) in the transfer record of the imported session (a network transfer)
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Move THIS session onto another profile of the SAME runtime, keeping its conversation. The run is closed at a turn boundary and the same native context resumes under the new model/effort. An interactive pane swaps its child in place; a headless session immediately relaunches a same-spool continuation. Cross-runtime is not possible here — use compact handoff --into for that.
Argument
Description
target
Destination profile registry key (<runtime>/<profile>, same runtime as this session)
Move a session to another account of the same runtime (default: THIS session; pass --session for another): its conversation files are MOVED to the new account home and the durable account is flipped. An interactive pane resumes the same context there; a headless session has a live turn KILLED at a run boundary (that turn is lost, the conversation is not) and comes up on the new account at its next wake. Nothing but the session travels — memory, config, and credentials stay with the old account. With --release-claim (no account): clear a migration claim that a failed release or a stuck migration left, after a check that no migration can still change files; the files are settled first.
Argument
Description
account
Destination account name (same runtime as the session); not used with --release-claim
Option
Description
--session <id>
Session to migrate (full or partial ID); defaults to ORBH_SESSION_ID, the session that runs this command
--force
Migrate even when the destination account has no usable credentials
--release-claim
Clear a stuck migration claim of the session; refuses while its migration can still run
The account autoswitch: an ordered fallback list of accounts for each runtime. A new headless launch whose account is in the list and limited (a usage-limit marker, or a fresh usage snapshot window at or above the switch percent) uses the first good account of the list, and prints one notice. Only with the separate opt-in settings --auto-migrate on (default off), the orchestrator also moves a headless session whose turn stopped on a provider limit to a good account of the list, between turns; that move uses the migration primitive of auth migrate, which still has open races. With no list, Orbh never switches. Orbh never chooses an account outside the list, and never switches an interactive launch or session.
Run the harness CLI under an isolated account home — general arg passthrough to the runtime executable
Argument
Description
runtime
Harness runtime
name
Account name (must already exist)
args
Arguments forwarded to the harness executable (e.g. login --device-auth)
Option
Description
--dry-run
Print env and command without running the harness
Sets the runtime account-home env var (CODEX_HOME, CLAUDE_CONFIG_DIR, …) to thenamed Orbh account directory, then execs the harness binary with the remainingargs unchanged. Use this for login variants, status, logout, or any other CLIsubcommand that should touch only that account's credentials and state.The account must already exist (create with `auth add <runtime> <name> [--no-login]`).Examples: flint orbh auth account codex nathan-gmail login flint orbh auth account codex nathan-gmail login --device-auth flint orbh auth account codex nathan-gmail login status flint orbh auth account claude nuu /logout flint orbh auth account codex nathan-gmail --dry-run login --device-auth
Hide an account whose subscription lapsed: the account views hide it and a new launch refuses it. Its home, credentials, and sessions stay; resume still works
Mark an account that only a person uses (a work account), or clear the mark. Orbh then sends it no usage request unless a command names it, keeps it out of every fallback list and default, never moves a session to it, and a launch names it only with --account <name> --allow-manual-only
Re-authenticate accounts whose access token has expired by launching one throwaway session under each
Argument
Description
runtime
Optional harness runtime
name
Optional account name
Option
Description
--json
Emit the refresh outcomes as JSON
--dry-run
List the accounts that would be refreshed without launching anything
A `needs-reauth` account is almost never actually logged out — its stored accesstoken has simply expired, and the harness CLI refreshes it from the refresh tokenthe moment a session launches under that account. This command automates exactlythat: one minimal ping per stale account, then a re-check.Success is the post-ping usage result, not the ping exit status. The refresh landsat launch, before any inference, so a ping that fails to return its result hasstill done the job.Examples: flint orbh auth refresh flint orbh auth refresh claude flint orbh auth refresh claude nuucognition flint orbh auth refresh --dry-run
Run ccusage against Orbh account homes; add a runtime vanilla home only when that runtime has no named account
Argument
Description
args
Arguments passed to ccusage (default: daily)
Option
Description
--dry-run
Print the env and command without running ccusage
Aggregates registered account homes under ~/.nuucognition/orbh/accounts(or ORBH_ACCOUNTS_DIR) into ccusage multi-directory env vars(comma-separated, no spaces). A runtime with no named account alsocontributes its vanilla CLI home: CLAUDE_CONFIG_DIR ← claude accounts, or ~/.claude (+ ~/.config/claude) if none CODEX_HOME ← codex accounts, or ~/.codex if none GROK_HOME ← grok accounts, or ~/.grok if none … ← any other harness accountHomeEnvVar + resolveDefaultHomeVanilla homes are omitted for any runtime that already has a named account.Launch with --account none still uses the vanilla home; list and usage do notshow it once named accounts exist.Claude reports use temporary copies to support nullable iteration models.The original transcripts stay unchanged. Temporary copies are removed after the report.ccusage has no Muse support, so Orbh reads the Muse session logs itself($XDG_DATA_HOME/muse, else ~/.local/share/muse). After the ccusage table ofdaily, weekly, monthly, or session (and each --sections report), Orbh prints aMuse table for the same periods; --since, --until, --timezone, --last, and --idapply to it. With --json, the Muse rows go under the top-level key"orbhAgents", and the ccusage keys stay unchanged. The Muse cost isunknown (— or null). blocks, statusline, and one-agent reports get no Muse rows."auth ccusage muse [daily|weekly|monthly|session]" prints the Muse report alone.Examples: flint orbh auth ccusage flint orbh auth ccusage monthly flint orbh auth ccusage daily --json flint orbh auth ccusage muse weekly flint orbh auth ccusage --dry-run
Repair Orbh Data Layer conformance violations (C1-C14)
Option
Description
--dry-run
Show what would be repaired without writing
--include-synced
Allow rewrites in synced/flint-tier spaces
--allow-adapter-strip
Delete adapter data heal cannot re-fold instead of refusing those spools
--servers-confirmed <note>
Below writer epoch 2, confirm with a note that no process outside the registries (Flint servers, Orbh servers, collectors) of an older build runs; a heal that rewrites a log needs it
--json
Print a machine-readable heal report
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Destroy this flint's derived Orb transcript events and rebuild them from the native agent transcripts. Alias: reset.
Option
Description
--json
Print a machine-readable rebuild report
--dry-run
Preview only: print what would be wiped/rebuilt and change nothing
--yes
Actually perform the destructive wipe + rebuild (required; otherwise previews)
--force
Alias of --yes
--cwd <dir>
Override the working directory used to resolve the target flint
--runtime <name>
Only rebuild sessions of this runtime
--session <id>
Only rebuild this session
--servers-confirmed <note>
Below writer epoch 2, confirm with a note that no process outside the registries (Flint servers, Orbh servers, collectors) of an older build runs; the rebuild needs it
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
Run a shell command — or a subagent dispatch with --agent — as a background job (inherits the terminal env)
Argument
Description
command
Shell command to run in the background (with --agent: the subagent prompt)
Option
Description
--group <g>
Job group name — the join key for park --until-group
--agent <target>
Dispatch a subagent instead: <target> is a runtime/profile (e.g. codex/55xh) and the positional argument is its prompt
--account <name>
Harness account for --agent, or 'none' to bypass the runtime default
--title <title>
With --agent: pre-set the title of the child session
--description <description>
With --agent: pre-set the description of the child session
--application <name>
With --agent: Tag the session with the launching application (also read from ORBH_APPLICATION); tagged sessions are hidden from list, active, and the cockpit by default
--output-schema <schema>
With --agent: JSON Schema (a file path, or inline JSON) that each return of the child must match; job result --json prints the structured value
--timeout <seconds>
Mark the job failed (timeout) and SIGTERM its process group after this many seconds
--session <id>
Target session ID (full or partial); defaults to ORBH_SESSION_ID
Block until a job reaches a terminal state, then print its full output. Exit 0 when done, 1 when failed. Reaps dead-wrapper/timed-out jobs while polling, so a wait can never hang on a job that will never report.
Argument
Description
id
Job id (full or unique prefix)
Option
Description
--poll <ms>
Polling interval in milliseconds (default 1000)
--session <id>
Target session ID (full or partial); defaults to ORBH_SESSION_ID
Declare and manage fleets: a named group of sessions that acts under one name and one charter
Option
Description
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
A fleet is one spool in the flint Orb space of the Flint. Its handle is unique for all time.A child of a member inherits the fleet at launch. A peer or a station joins with fleet join.fleet close does not stop a session.
Create and manage durable orb agents (orba) — named entities backed by a long-lived session
Option
Description
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
An orb agent owns a scope of responsibility and persists across sessions.Its identity lives in its markdown mind — `<home>/(Orb Agent) <name>.md`, whosefrontmatter carries agent/home/target/account/scope/description. Edit an agent byediting that file; a moved mind folder self-heals on the next read. The only twowrites with verbs are the launch facts, because each does more than the edit:`agent profile` validates the target against the profile registry, and`agent migrate` also moves a live interactive body into the new account.Its backing headless session is a replaceable body: `agent wake` launches oneon first use and relaunches it if the previous body ended.Address a live agent with `flint orbh message send agent:<name> "<text>"`.
Show or set the runtime/profile an orb agent's body launches under. Setting it writes target: in the agent's mind and, when the body can take it, switches that live body onto the new profile too — keeping its conversation. Cross-runtime targets only ever reach the next body.
Argument
Description
name
Agent name or id
target
Target to set (<runtime> or <runtime>/<profile>); omit to show the current one
Option
Description
--mind-only
Write the declaration and leave the live body on its current profile
Move an orb agent to another harness account of the same runtime. Writes account: in the agent's mind, and when its body is a live interactive pane, moves that running conversation into the new account too.
Argument
Description
name
Agent name or id
account
Destination account name (same runtime as the agent)
Option
Description
--force
Migrate even when the destination account has no usable credentials
--mind-only
Write the declaration and leave the live body on its current account
Spawn and follow workers — runtime objects bound to one unit of work each
Option
Description
-p, --path <dir>
Path to flint (default: auto-detect)
--orb-root <dir>
Scope this command to an Orb store directory (overrides ORBH_ORB_ROOT_DIR and cwd)
--at <scope>
Scope this command by name: 'flint:<name>' (registered Flint) or 'machine' (~/.orb). The human spelling of --orb-root.
--create-store
Permit an explicitly scoped store that does not exist yet to be created
A worker is a headless session bound to exactly one unit and to a conversationalsurface. Its parent agent spawns it with a self-contained brief; it narrates onits own update stream, parks while it waits, converses with the human in its ownthread, and returns exactly once — the delivery result that resolves the parent'scollection. `worker spawn` does not block: the result arrives through the normalchild-result wake.The native surface (this session spool) is always present and is never a binding.External surfaces — a Discord thread, and later anything else — are boundprojections with inbound routing; nothing is lost when one of them dies.
Attach a deterministic step register to this session: ordered steps, forced evidence check-ins, verb-side enforcement. Self-targets via ORBH_SESSION_ID.
Attach a new procedure to a session (refused while one is already active)
Option
Description
--title <title>
Human title for the procedure
--from <file>
Extract ordered steps from a markdown/text file (numbered items, else top-level bullets, else ## headings; fenced code blocks are ignored; a "(skippable)" annotation on a step line marks it skippable and is stripped from the title)
--steps <list>
Semicolon-separated step titles; a trailing "?" marks a step skippable
--enforced
Refuse session return --finish while required steps are outstanding
--session <id>
Target session ID (full or partial); defaults to ORBH_SESSION_ID (a dispatcher may start a procedure for a session it launched)
Arm a clause on a session's NEXT return (an already-returned run does not count)
Argument
Description
session-id
Subject session id (full or partial)
Option
Description
--then <prompt>
Prompt to launch when the clause fires; may contain {{...}} tokens resolved at fire time, including {{result:subject}} for the triggering subject's own result
--on <edge>
Edge to take: finished | failed | any (default: "finished")
--target <runtime/profile>
Agent target for the launched child (default: 'default', the first available target of the default target list at launch)
--wf <id>
Append to this workflow instance instead of creating a fresh one
--label <label>
Child label, referenced by {{result:<label>}}; defaults to the clause id ('subject' is reserved)
--title <title>
Title for the launched child session
--session <id>
Owning session id for a freshly created instance; defaults to ORBH_SESSION_ID
Arm a clause on a procedure step or on the procedure finishing (arming ahead of the procedure existing is legal)
Argument
Description
procedure-id
Subject procedure id
Option
Description
--then <prompt>
Prompt to launch when the clause fires; may contain {{...}} tokens resolved at fire time, including {{result:subject}} for the triggering subject's own result
--step <n>
Fire on this step settling; omit to fire when the procedure finishes
--on <edge>
Edge to take: finished | failed | any (default: "finished")
--target <runtime/profile>
Agent target for the launched child (default: 'default', the first available target of the default target list at launch)
--wf <id>
Append to this workflow instance instead of creating a fresh one
--label <label>
Child label, referenced by {{result:<label>}}; defaults to the clause id ('subject' is reserved)
--title <title>
Title for the launched child session
--session <id>
Owning session id for a freshly created instance; defaults to ORBH_SESSION_ID
Arm a STATIC workflow from a shipped definition (by name) or a definition file (by path). Every trigger subject is resolved and anchored now; action prompts stay templates until they fire.
Argument
Description
name-or-path
Definition name under <orbRoot>/workflows/definitions, or a path to a definition JSON
Option
Description
--args <k=v>
Definition argument override; repeat to add more (default: [])
Manually drive the firing chokepoint. The harness chokepoints (session return, orbh end, procedure step/skip/finish/abandon) already call fireWorkflowEvent in-process; this verb is that same entry point, driven by hand for testing and manual recovery.
Agent-authored compaction, in three verbs. compact start prints the handoff contract and the path to write it to, holds the pager, and marks the session [Compacting...]; you then write the handoff with your own tools. compact handoff is TURN-ENDING: it validates what you wrote, ends this context, and relaunches the SAME session from it; --into <runtime/profile> [--account <name>] selects the runtime, profile, and optional account for that fresh run. Interactive panes keep their manager and swap only the harness child. compact finish is run by the RELAUNCHED context once it has read the handoff and every FILES path — it clears [Compacting...] and releases the hold. compact abort backs out before handoff.
TURN-ENDING: validate the handoff, end this context, and relaunch the same session from it. Optionally select a different runtime/profile/account for the fresh run.
Option
Description
--into <runtime/profile>
Relaunch the fresh run under this profile registry key (cross-runtime allowed)
--account <name>
Use this account for the relaunched run (requires --into)
OrbCode views: a view of a product with the proof of Orbtest. list, view, check, diff, history, and parts write nothing; review, apply, discard, restore, set, and remove write.
Show one view (or one candidate with --candidate) joined with the stories and the proof of Orbtest and with Git: each node with its proof state, its criteria, its cases, its related cases, and its findings. Writes nothing.
Argument
Description
view
The UUID or the name of the view (not with --candidate)
Option
Description
--candidate <id>
Show a candidate as a view, with its proof
--checkout <dir>
Read the code and the Git history of this worktree of the codebase in place of its primary checkout; the Orbtest definitions and runs come from its product root when it has them, else from the primary checkout
Print the findings of the views (format, code-ref-missing, story-missing, review-due, anchor-unknown, never-reviewed, no-contract, part-missing, no-part). Exits 1 when a finding has the level error. Writes nothing.
Argument
Description
view
The UUID or the name of one view (default: every view)
Option
Description
--paths <path...>
Only the views with a node whose code-refs match one of these paths: an absolute path matches the code-refs of the codebase of its Git repository (also @<Codebase name>/<path>); a relative path is a path of the codebase of the project
--candidate <id>
Check one candidate file as a view
--checkout <dir>
Read the code and the Git history of this worktree of the codebase in place of its primary checkout; the Orbtest definitions and runs come from its product root when it has them, else from the primary checkout
Write the review anchor of the nodes of a view: the commit and the hashes of the claim and of the references of each node. With no --node, each node with a node block.
Argument
Description
view
The UUID or the name of the view
Option
Description
--node <id...>
Only these nodes
--commit <sha>
The commit of the anchor (default: the HEAD of the codebase)
Replace a view with a candidate only when the view did not change after the candidate was made (the base_hash of the candidate). Then remove the candidate. A conflict writes nothing and exits 1. An apply by an agent sets the curation proposed; an apply by a person keeps the curation of the view.
Argument
Description
view
The UUID or the name of the view (the view_id of the candidate for a new view)
Option
Description
--candidate <id>
The candidate id
--by <agent|person>
Who applies: agent sets the curation proposed; person keeps the curation of the view (default: "agent")
Remove a draft view and its candidates. A kept view is refused: set --lifetime draft first. The view goes to History/ first (flint orbcode restore brings it back).
List the static parts of each OrbCode project (the artifacts of Map/) with the processes that pass through each part (views of the shape flow or streams, nodes that name the part) and the count of the code-refs that name no file. Writes nothing.
Add one contact. Keep the other contacts of the node.
Argument
Description
program
The name or id of the program.
node
The node id.
Option
Description
--json
Print one JSON value.
--document <id>
The map, or the id of a view. (default: "map")
--kind <kind>
reference, file, command, http, mesh, orbtest, agent, human, or note.
--id <id>
A mapping contact id. The default uses claim words, prompt words, or command words, then the kind. Duplicates get a number. Wikilinks use a computed id.
--claim <text>
The statement that the contact checks.
--run <command>
The shell command of a command contact.
--cwd <dir>
The working folder of the command.
--url <url>
The URL of an HTTP contact.
--path <path>
The file path of a file contact.
--ref <note>
The Mesh note name. Reference and note contacts store a wikilink and no other fields.
--prompt <text>
The question for an agent or person.
--fresh-for <duration>
How long an observation stays fresh, for example 7d.
--direction <direction>
observe or act. The default is observe.
--query <json>
The Mesh query as a JSON object.
--expect <json>
The expected result as a JSON object.
--story <id>
An Orbtest story id. Repeat for more stories.
--criterion <address>
An Orbtest criterion address. Repeat for more criteria.
A Git source (an owned member) or "registry:<name>" (a reference member)
Option
Description
--json
Print the report as one JSON value
add writes the declaration to tinderbox.toml, refreshes .gitignore, andrecords the member in tinderbox.json when its id is known. It makes.tinderbox/ and the roster row of the box when they are absent. The nextflint tinderbox sync clones an owned member or references a roster member.
Remove a member and keep its folder, unless --move-out moves it
Argument
Description
name
The member name in tinderbox.toml
Option
Description
--move-out <dir>
Move the member folder out of the box into <dir>
--json
Print the report as one JSON value
The member leaves tinderbox.toml and tinderbox.json. The references that thebox wired are stripped. The folder and its roster row stay, except with--move-out: the folder then moves into <dir>, and the roster row follows it.
Move every member folder out of the box into <dir>
--force
Dissolve also when a member has uncommitted or unpushed work
--dry-run
Show the plan and change nothing
--yes
Dissolve with no confirmation prompt
--json
Print the report as one JSON value
Dissolve backs up and removes tinderbox.toml and tinderbox.json, removes theroster row, and strips the wiring. The member folders, .git, and .tinderbox/(with the backups) stay.
Make the box match its intent on this machine, then run the local sync (flint sync) in each selected member
Option
Description
--dry-run
Show the plan of the box and of each selected member and change nothing
--no-git
Not needed: tinderbox sync does no Git transport (retired)
--no-update
Not needed: tinderbox sync does not move a lock (retired)
--json
Print the operation report of the box and of each member as one JSON value
--only <names...>
Sync only these members (the repos are not synced)
--skip <names...>
Do not sync these members (the repos are not synced)
Clones a missing owned member, references a roster member, wires theconnections and the repos, and records the box in tinderbox.json. It makesno Obsidian vault registry entry: a vault enters the registry when Obsidianopens it. Then runs `flint sync` in each selected member. It never asksthe registry, never moves a lock, and never touches origin. Undeclared foldersstay where they are.
In each member, take the remote as truth: keep local work that merges, discard what does not
--force-local
In each member, take the local side as truth: overlapping changes resolve in favour of local commits
--no-sync
Transport only: do not run the local sync of the box or of the members
--only <names...>
Sync only these members (the box repo still syncs)
--json
Print the operation report as one JSON value
The box goes first: checkpoint, fetch, integrate. Then the local sync of thebox. Then the members, 4 at a time, each with the flow of `flint git sync`.Then the second checkpoint of the box, and the push. A reference member isskipped: its own Flint moves its history. A conflict holds the rebase; run`flint tinderbox git resolve <member>`. A merge, a cherry-pick, or a revertthat holds a member or the box blocks it (exit 2): finish it with Git first.
Set up this machine in seven steps: your Name and the machine, the Git author, the tools, the agent default, your Computer Flint, the Guide, and the open of your Computer Flint with your first agent session. Setup needs internet access: with no network it stops before the first step
Option
Description
--name <name>
Your Name (the author of your notes)
--machine-name <name>
The branch prefix of this machine (default: from the hostname)
--machine-proper-name <name>
The machine display name (the name people read, such as "Ada Laptop"). It renames the Computer Flint too
--git-email <email>
The email of the Git author, with no question. Setup writes it only when Git has no email
--no-open
Do not open the Computer Flint in Obsidian (the onboarding session then runs in this terminal)
--guide
Clone the Guide of NUU Cognition with no question
--no-guide
Do not clone the Guide (later: flint setup guide)
--font
Install the terminal font JetBrainsMono Nerd Font with no question
--no-font
Do not install the terminal font (later: flint setup font)
-y, --yes
Ask no question. Every open input takes its default, setup installs the terminal font, and setup clones the Guide
--json
Output one JSON result envelope on stdout. Ask no question. The text for a person goes to stderr
Check this machine and the current Flint, and give one next command for each problem. Starts no agent
Option
Description
-p, --path <dir>
Check the Flint at this path (default: the Flint of the working folder)
--json
Print the checks as one JSON value
The checks: your identity and the NUU home, Git, Node.js, Obsidian, theterminal of Obsidian (its PATH finds node and flint, its font, and python3),the agent (the default target list of Orbh), the launcher record, theBlacksmith daemon (a read: it starts no daemon), the Computer Flint, the Flintregistry, the Flint version (it names a newer release and never fails for it),and the Orbh profiles.Inside a Flint: its lock, the layout of flint.toml, its sync plan, its modules,its Git state, and its Obsidian payload.A check that needs judgement names flint fix; then the doctor writes one failurerecord for it. It writes nothing else. Exit 0 when each check passes, else 1.
Start an agent that repairs the last failure of a Flint command (a repair session)
Argument
Description
record
The failure record to repair: a number of flint fix --list (1 is the newest), a record id, or a record file
Option
Description
--list
List the failure records of this machine
--json
With --list: print one JSON value
When flint sync, flint create, flint git sync, flint shard install, flint setup,or flint tinderbox sync fails, Flint writes a failure record and prints"Or: flint fix". flint fix starts an interactive Orbh session on the defaulttarget in your Computer Flint. The session reads the record and follows therepair skill of the Flint shard. flint doctor checks this machine and starts no agent.To report the failure to NUU Cognition: flint feedback --bug --with-failure.
Print the report and the link as one JSON value; opens nothing without --yes
flint feedback builds a report: your text, the kind, the Flint version, the OSand the arch, and the Node.js version. It shows the report and asks before itopens anything. Then your browser opens a new issue ofNUU-Cognition/flint-public with the report filled in, and you submit it.--email opens an email to hello@nuucognition.com in your mail app.Flint sends nothing itself.Flint removes some secrets, but not all. Read the report.Remove each secret before you send it.Each line of your text that has a secret key, a secret flag, or anAuthorization or Cookie header loses the rest of the line. Private key blocks,the user information of URLs, known tokens, and home folder paths go too.--with-failure adds only the facts of the newest failure record (flint fix--list): the command words, the exit code, the error code, the Flint version,and the time. It adds no arguments, no output, no reason, and no paths.A local copy of each report goes to the NUU home (flint/feedback/).With no terminal, the command prints the report and the link only.Examples: flint feedback --bug "flint sync stops on a fresh clone" --with-failure flint feedback --idea "A flint sync --watch mode" flint feedback --question "How do I share a shard with my org?" --no-openTo repair a failure on this machine, run flint fix.
Git operations for the Flint: init, sync, merge, resolve, publish, or passthrough to git
Argument
Description
args
Raw git arguments (passthrough); bare flint git shows the Flint git status
Anything that is not a listed subcommand passes through to git, run at the Flint root.Examples: flint git status flint git sync -m "polish docs" flint git publish git@github.com:owner/repo.git
Exchange history with origin: checkpoint, fetch, integrate, run the local sync, push
Option
Description
-m, --message <msg>
Custom commit message
--replay
After a remote history rewrite, replay local-only commits onto the new history
--force-remote
Take the remote as truth: keep local work that merges, discard what does not
--force-local
Take the local side as truth: overlapping changes resolve in favour of local commits
--no-sync
Transport only: do not run the local sync
--continue
Continue a sync halted on a conflict (a bare re-run also continues)
--abort
Abort a halted sync: stop the in-progress rebase and restore the branch
--json
Print the operation report as JSON (with --abort: one JSON value)
Checkpoints all changes, fetches and diagnoses divergence, rebases orfast-forwards, runs the local sync (`flint sync`), checkpoints the writes ofthe local sync, and pushes. The push runs also when the local sync fails;the writes of a failed local sync stay uncommitted, and the push sends theintegrated history as it is: when origin moved during that sync, the push isrejected, and the next `flint git sync` sends it. `--no-sync` is transportonly. If the remote history was rewritten (force-push), sync realignsautomatically when no local-only commits exist, or halts and asks for--replay to carry local commits over.--force-remote makes the fetched remote branch the source of truth. Localcommits that replay cleanly are kept; overlapping changes are resolved infavour of the remote, and anything that still won't merge is discarded.A backup ref preserves committed parent history before integration.Commit or stash changes in nested repositories before you use this flag.--force-local is the mirror image: overlapping changes resolve in favour ofyour local commits. Remote history is never rewritten — remote commits stayin the base; only conflicting content takes the local side.A conflict halts before the local sync. Edit the files (or use`flint git resolve`), then re-run `flint git sync` (or `--continue`): itfinishes the integrate, runs the local sync, and pushes. `--abort` restoresthe pre-sync branch and runs no sync. `--continue` does not take --replay,--force-remote, or --force-local.A git merge, cherry-pick, or revert that is in progress stops the syncwith exit 2, and nothing changes. Finish it or abort it with git first.
Integrate with origin and run the local sync, with no push: checkpoint, fetch, integrate, run the local sync
Option
Description
-m, --message <msg>
Custom commit message
--replay
After a remote history rewrite, replay local-only commits onto the new history
--force-remote
Overlapping changes resolve in favour of the remote
--force-local
Overlapping changes resolve in favour of local commits
--no-sync
Transport only: do not run the local sync
--json
Print the operation report as JSON
`flint git sync` with no push: it checkpoints, fetches, integrates, runs thelocal sync, and checkpoints the writes of the local sync. Use it to convergewith the remote, inspect the result, then publish with `flint git sync`. Aconflict halts exactly like sync; resolve and re-run, or `flint git sync --abort`.
During a conflict halt, resolve files by taking one side whole
Argument
Description
paths
Files to resolve (default: every conflicted file)
Option
Description
--local
Take your local version of the paths
--remote
Take the remote version of the paths
Only valid while a sync is halted on a conflict (mid-rebase). Takes thenamed side of each file whole — no marker editing, and it works for binaryfiles. A path is relative to the working directory. When every conflict isresolved, run `flint git sync` to continue.
flint foundation inspect <PID|registration-UUID> [--tree]
Show one process: identity, record, owner, launch parent, observed parent, memory, and log path. A UUID selects its record, also a stale one. A PID selects the current process.
Option
Description
--tree
Also show the descendants and the RSS sum of the tree.
--json
Print one JSON object (schema foundation-cli/0.1).
--home <NUU-home>
Read this NUU home. Default: $NUU_HOME, else ~/.nuucognition.
Read the event log of a NUU process: its events, filtered by service, event, level, and time. A log is <NUU home>/foundation/logs/<registration UUID>/events.jsonl. events.1.jsonl holds the lines before the last rotation. A process writes a log when it registers with events: true. A log stays after its process exits. Without a UUID, logs reads the newest log that matches --service and --role, of a live or an exited process. The prefix sync selects the events sync and sync.command.applied. It does not select syncx. prune --apply removes the logs of exited processes that are old or above the byte budget.
Option
Description
--list
List the logs, newest first, with their state and size.
--service <service>
Read the newest log of this service. With --list: only the logs of this service.
--role <role>
Read the newest log of this role. With --list: only the logs of this role.
--event <prefix>
Only the events whose name starts with these whole words. Repeat it for more prefixes.
--level <level>
Only the events of this level or higher: debug, info, warn, or error.
--since <time>
Only the events at or after this time: a duration (30s, 10m, 2h, 1d) or an ISO time.
--limit <n>
Show the last <n> matching events, from 0 to 1000000. 0 shows all. Default: 200.
--json
Print one JSON object (schema foundation-cli/0.1).
--home <NUU-home>
Read this NUU home. Default: $NUU_HOME, else ~/.nuucognition.
flint foundation ghosts [--root <absolute-repo-or-install-root>]...
Find running processes of this user with NUU evidence and no verified record. The scan is heuristic. An unregistered detached child without current ancestry or recognizable arguments can remain undiscovered. Candidates need review. The command stops no process.
Option
Description
--root <path>
Also accept NUU entrypoints below this absolute root. Repeat it for more roots.
--json
Print one JSON object (schema foundation-cli/0.1).
--home <NUU-home>
Read this NUU home. Default: $NUU_HOME, else ~/.nuucognition.
Preview the stale records, the old temporary files, and the old event logs that can be removed. The event log of an exited process goes when its newest file is older than 7 days. When all logs use more than 200 MiB, the oldest logs of exited processes go until the sum is 200 MiB or less. The log of a live or unknown process always stays. Prune removes only events.jsonl and events.1.jsonl, and then the empty folder. Prune never signals a process and never changes a service registry.
Option
Description
--apply
Remove them after a fresh check. Unknown and invalid records stay.
--json
Print one JSON object (schema foundation-cli/0.1).
--home <NUU-home>
Read this NUU home. Default: $NUU_HOME, else ~/.nuucognition.
flint foundation storage [--no-flints] [--top <n>] [--timeout <ms>]
Measure the disk usage of the NUU home, of the Flints of this machine, and of their Orbh spools. The size is the disk usage: the allocated blocks. The measure does not follow a symbolic link, stays on the device of each area, and counts a file with more than one hard link one time. The command deletes nothing.
Option
Description
--no-flints
Measure only the NUU home. Do not read the Flint registry.
--top <n>
Show the <n> largest spools of each Flint. Default: 5.
--timeout <ms>
Stop the measure after <ms> milliseconds. Default: 20000.
--json
Print one JSON object (schema foundation-cli/0.1).
--home <NUU-home>
Read this NUU home. Default: $NUU_HOME, else ~/.nuucognition.
flint foundation top [--interval <ms>] [--service <service>] [--owner <kind>:<id>] [--tree] [--sort cpu|rss|pid|service] [--no-storage] [--no-mouse] [--once]
Show a live screen of the NUU processes with their CPU, their memory, and the storage sizes. On a terminal, top shows a live view until you press q or Ctrl-C. Press ? for the keys. Tab moves the focus between the process table and the storage panel. The arrow keys, j, k, g, G, PgUp, and PgDn move the panel with the focus. The storage panel lists all areas; it starts folded. + (or =) opens the selected row and - folds it; e opens all rows, c folds all rows. Enter, the left and right arrow keys, and a click on [+] or [-] also open and fold a row. z gives the panel with the focus all rows. The mouse wheel scrolls the panel under the pointer. A click gives a panel the focus and selects a row. The key m turns the mouse reports off, so that the terminal can select text. You can also hold Option (macOS) or Shift to select text. With --json, --once, or no terminal, top takes two samples one interval apart, measures the storage, prints one reply, and ends. An agent uses top --json. CPU: 100 % is one full core. The CPU of the second sample is the difference of the two samples. RSS can count shared pages more than once.
Option
Description
--interval <ms>
The time between two samples, from 250 to 60000. Default: 2000.
--service <service>
Only the processes of this service.
--owner <kind>:<id>
Only the processes of this owner.
--tree
Also show the unregistered descendants of the registered processes.
--sort <key>
Sort the processes by cpu, rss, pid, or service. Default: cpu.
--no-storage
Do not measure the storage. In the live view, the key d starts it.
--no-mouse
Do not turn on the mouse reports in the live view. The key m turns them on.
--once
Take two samples, print one text frame, and end.
--json
Print one JSON object (schema foundation-cli/0.1).
--home <NUU-home>
Read this NUU home. Default: $NUU_HOME, else ~/.nuucognition.
Print the one daemon port of this home. The bound port is the lease of the home, and the recorded port is immutable in code. To change it by hand: stop the daemon (nuu client stop), delete ~/.nuucognition/nclient-dev/port, and start with --port <n>
Ask the nclient daemon to stop (POST /stop with the stop token of this home), and wait until it is gone. It first finishes the requests in progress. No signal is sent
Option
Description
--force
Kill the daemon (SIGKILL) when it is not gone after the wait, or when it hangs. Only with /proc evidence that the pid runs the nclient serve command of this installation and owns the listening socket of this home
--wait <seconds>
How long to wait for the requests in progress (default 155)
Write, enable, and start the systemd user unit of this dev build, with memory and task limits (MemoryMax=1500M, TasksMax=96, KillMode=control-group). A standing daemon on a real machine always runs under it
Option
Description
--dev
Confirm that you mean the DEV unit (nclient-dev.service). A dev build needs it; a prod build refuses it
--uninstall
Stop and disable the unit, and remove its file
--dry-run
Print the unit and the commands, and change nothing
Copy a session of a Flint on this machine to a Flint at another place, and print the address of the copy. The source session stays. The target never replaces a file: remove an old copy there by hand first.
Argument
Description
session-ref
The address of the session, for example @/flint/nuu-test/session/<uuid>
Option
Description
--to <flint-ref>
The target Flint with its place, for example @/flint/nuu-test#nuu-2
--title <title>
The title of the copy
--no-inline
Send the bundle through the storage of NUU Network, also a small one
The org of NUU Network: refresh the cached org slug of this machine; admin only: make an org, or replace its enrollment secret (needs the bootstrap secret of the deployment). The orgs of your NUU account: nuu org list
Scaffold an orbtest/ folder of format 0.0.1 for one platform family: orbtest.toml with the format stamp, one environment under environments/ and one UI profile with the same id under ui/profiles/, one step under ui/steps/, the requirements of that platform under requirements/, empty ui/tasks/, stories/ and ui/fixtures/ folders, and .gitignore. web: profile web-desktop-chromium, step nav.goto, requirements node, probe-tool, playwright-chromium. terminal: profile cli-terminal, step cli.run, requirements node, terminal-program, and no browser. desktop: profile desktop-app, step app.restart, requirements hyprland, wtype, grim, atspi. The output ends with the next commands, each with --root
Option
Description
--root <dir>
Directory that will hold orbtest/ (default: cwd)
--platform <platform>
Platform family of the scaffold profile: web, terminal, desktop (default: web)
--base-url <url>
Web only. Root URL of the app under test (default: http://127.0.0.1:<port>)
--port <n>
Web only. Port for the default base URL (default: 3000); cannot be combined with --base-url
--force
Rewrite the scaffold files of the platform (or of the behaviour layer) when orbtest/ already exists; files outside the scaffold, including .local/, are left alone
--layer <layer>
The layer to scaffold: ui, behaviour (default ui). behaviour: orbtest.toml and .gitignore when orbtest/ is new, environments/local.yaml, stories/example.hello.yaml, and behaviour/specs/example.hello.md with one case that needs no test code; an existing orbtest/ keeps its orbtest.toml and .gitignore
Describe an orbtest/ folder without loading it: the declared format against the format this CLI reads, and the folder against the layout of that format, the behaviour layer included (its findings are warnings; --strict makes them errors). Never writes.
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--json
Print the report as JSON on stdout; human lines go to stderr
--strict
Count the findings of the behaviour layer as errors: exit 2 when there is one (default: warnings)
Execute journey tasks on a profile and write an append-only run record
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--profile <id>
Profile to run on (default: the only registered profile)
--task <id...>
Restrict to these task ids; combines with --story as a union
--story <id...>
Restrict to the tasks of these story ids; combines with --task as a union
--input <key=value...>
Task input overrides
--runs <dir>
Run record directory (default: <orbtest>/.local/runs)
--json
Print the run record as JSON instead of a summary
--agent <kind[:target]>
Agent for agentic steps and verification, e.g. orbh or orbh:claude/s5m (default: profile.agent, then orbtest.toml [agent] target)
--no-agent
Run without an agent even if the profile declares one
--keep-services
Leave profile.setup.start services running after the run
--jobs <n>
Run tasks on up to <n> workers, each with its own services and browser; needs parallel on the profile (default 1)
--keep <n>
After this run, keep only the newest <n> run directories, counting this one (default: orbtest.toml [runs] keep, else keep all)
--confirm
Anchor every met task to the current commit and store each step's fingerprint (refuses with uncommitted changes)
--freeze
After a met run, convert each agentic step's trace into deterministic steps and write a freeze bundle at .local/runs/<run-id>/<task-id>/bundle.json for register
--components <json>
With --freeze: JSON map of locator description to repository path, as author takes it
--watch
Show the run on the current display: a browser window for a web profile, a terminal window that mirrors the screen for a terminal profile. One worker; never with --confirm; the record is the same
--slow <ms>
With --watch: milliseconds to wait before every browser action (default 250)
--hold <ms>
With --watch: milliseconds the window stays open after the run (default 3000)
Detect drift: diff each step's component since its task's confirmed commit (a testid locator goes stale only when its value leaves the file), fold in run signals, and mark stale steps
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--profile <id>
Restrict to tasks on this profile (default: every profile)
--task <id...>
Restrict to these task ids
--runs <dir>
Run record directory (default: <orbtest>/.local/runs)
--json
Print the drift report as JSON instead of a table
--check
Read-only gate: write nothing, need no browser, exit 1 when a blocking task is stale or unconfirmed
Diagnose a profile: environment requirements, services, setup command, app version pin, browser, agent, data sources. Plain doctor starts no service: on a profile that declares setup.start or setup.local_start, a failing setup verify and the app version check are skipped, not failed, and the line names doctor --start. Exit 0 when every other check passes
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--profile <id>
Profile to check (default: all registered)
--start
Start profile.setup.start services before checking, stop them after; setup verify and the app version check then run against them and fail for real
--keep-services
With --start, leave the services running afterwards
--setup
If checks fail, provision this machine from the requirements file (or the deprecated setup.script) through one Orbh session, then re-check
--setup-target <runtime/profile>
Orbh target for the provisioning session (default: profile.agent.target, then orbtest.toml [agent] target, then claude/o5m)
Print the documentation data as JSON instead of markdown
--check
Verify the output lists every registered atom, convention, locator strategy, check type, source provider, platform, command, and behaviour term, and that every schema field has a description; exit 1 otherwise
Profile to run on (default: brief.profile, else the only registered profile)
--input <key=value...>
Brief input overrides
--components <json>
JSON map of locator description to repository path, e.g. {"testid=browse-as-guest": "src/components/auth-gate.tsx", "*": "src/components/mesh-home/mesh-list.tsx"}
--from-run <dir>
Convert the trace of an earlier author run instead of running the agent; rewrites that run's bundle.json
--final-route <url>
With --from-run: the final route when run.json is missing
--agent <kind[:target]>
Agent for the authoring step, e.g. orbh or orbh:claude/s5m (default: profile.agent, then orbtest.toml [agent] target)
--no-agent
Run without an agent even if the profile declares one
--runs <dir>
Run record directory (default: <orbtest>/.local/runs)
Write a reviewed bundle into the definitions: an author bundle adds steps and a task, a freeze bundle replaces agentic steps of a task, a regen bundle sets fields (review only unless --approve)
Option
Description
--bundle <dir>
Directory holding bundle.json, e.g. orbtest/.local/runs/author-<id> or orbtest/.local/runs/<run-id>/<task-id>
--approve
Write the definitions; without it register prints the diff and exits 2
Write one static, read-only HTML page of the definitions: profiles, environments, stories, tasks, steps, suites, requirements, the behaviour layer (specs, cases, flags, newest runs, places, fixtures), and settings (default: orbtest/.local/runs/page/index.html)
Option
Description
--out <path>
Write the page to this file instead
--open
Open the page in the default browser ($BROWSER when set)
--runs <dir>
Run record directory (default: <orbtest>/.local/runs)
--root <dir>
Directory holding orbtest/ (default: cwd)
--json
Print the result as JSON on stdout; human lines go to stderr
Behaviour tests: one Markdown spec per behaviour under orbtest/behaviour/specs/, each ### heading one case, bound to test code in any language by the marker orbtest: <spec-id>/<case-id>, run in an environment and a place, with one run record and one report
List the cases of every behaviour spec: id, kind, the criteria each proves, and the flags the files decide (invalid, unbound, quarantined, waived, repaired, ungated). Writes nothing.
Option
Description
--story <id>
Only the cases of the specs of this story
--kind <kind>
Only the cases of this kind
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Run behaviour cases in their environment and place, write the run record and report.html under .local/runs/<run-id>/, and print report <path>. Exit 0 when no case of a blocking story failed, 1 when one ended fail, error, or budget_exceeded, 2 for a bad argument before any write, 3 when the place or the stage hook failed before any case.
Option
Description
--spec <id...>
Only the cases of these specs. Each filter narrows the selection; with no filter, every case runs
--case <id...>
Only these cases (<spec-id>/<case-id>)
--story <id...>
Only the cases of the specs of these stories
--kind <kind...>
Only the cases of these kinds
--environment <id>
Run every case in this environment (wins over the case, the spec, and orbtest.toml)
--place <id>
Run in this place (wins over the place of the environment)
--jobs <n>
Run cases on up to <n> workers (default 1)
--confirm
Anchor each passed deterministic case to the current commit in its sidecar (refuses a dirty tree)
--keep-scratch
Keep the case folders, the container, or the ssh run folder after the run
--resume <run-id>
Continue an earlier run from its completed cases; the selection of that run stays
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Read the orbtest: <spec-id>/<case-id> markers of the test files and compare them with the sidecars in behaviour/bindings/. With no flag, report and write nothing. --scan writes the sidecars and keeps every anchor. --check writes nothing and exits 1 when a sidecar is not current, a marker names no case, or a case has two markers.
Option
Description
--scan
Write one sidecar per spec under behaviour/bindings/; anchors stay
--check
Write nothing; exit 1 when a sidecar is not current, a marker names no case, or a case has two markers
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Mark each anchored case stale or suspect when its words, its bound test, a component, or a proven criterion changed after the anchor. Writes nothing. --check exits 1 when a case of a blocking story is stale or unconfirmed.
Option
Description
--check
Gate: exit 1 when a case of a blocking story is stale or unconfirmed
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Give each case of a run that is not green one verdict (environment_broken, test_wrong, flaky, spec_outdated, product_bug, unknown) with a rationale that cites evidence, and write heal/<case>.json in the run folder. It never weakens an assertion, never changes the words or the product, and applies a test patch only with --apply.
Option
Description
--run <run-id>
The behaviour run to heal (default: the newest behaviour run)
--case <id...>
Only these cases (default: every case of the run that is not green)
--apply
Apply a test_wrong patch that passes every guard rule; the case is then repaired and waits for review
--target <runtime/profile>
The Orbh agent target of the healer, e.g. claude/o55xh
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
List the fixtures of behaviour/fixtures/: id, form (recipe or script), the fixtures it uses, the cache mode, and the number of verify checks. Writes nothing.
Option
Description
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Build one fixture and its uses chain in a scratch case folder of the place, then run its verify checks. Exit 0 when it builds and verifies, 1 when a build, materialize, or verify step fails.
Argument
Description
id
Fixture id
Option
Description
--place <id>
Build in this place (default: the place of the environment, else local)
--environment <id>
Build in this environment (default: orbtest.toml [behaviour] environment, else local)
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Ask an Orbh agent to propose a fixture recipe for a state in words. The proposal, the prompt, and the reply go to .local/runs/fixture-author-<time>/ and nothing is written under behaviour/fixtures/: a person approves the recipe first. Exit 0 with a proposal, 1 when the reply holds no valid recipe, 3 when no agent answered.
Option
Description
--brief <text>
The state that the fixture must build, in words
--id <id>
The id of the proposed fixture (default: fixture)
--target <runtime/profile>
The Orbh agent target (default: orbtest.toml [agent] target, else claude/o5m)
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
flint orbtest behaviour place check [options] <id>
Check that the place is reachable and has its tools: its check op, else an open, one probe command, and a close. Exit 0 when every check passes, 3 when one fails.
Argument
Description
id
Place id
Option
Description
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
Show a state for each criterion of each story (proven, failing, stale, gap, not-run, waived), from the behaviour cases and the UI tasks that name it, and list the orphan cases, the test files that carry no case, and the quarantined and repaired cases. Writes nothing.
Option
Description
--story <id>
Only this story
--layer <layer>
Which layers prove a criterion: ui, behaviour, all (default all)
--root <dir>
Product root: the directory that holds orbtest/ (default: cwd)
--json
Print one JSON value on stdout; progress and human lines go to stderr
List, show, and change the profiles: under format "0.0.1" one file per profile in ui/profiles/, the driver half, which names its environment in environments/; the profiles.yaml register in the legacy flat layout
Show one profile: the resolved profile, the tasks and suites that use it, its requirements, and the resolved agent target. Under format "0.0.1" the fields are the driver half and the environment half joined, and both files are named.
Argument
Description
id
Profile id
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--json
Print the result as JSON on stdout; human lines go to stderr
Add a profile. Under format "0.0.1" it writes the driver half to ui/profiles/<id>.yaml and, unless --environment names an environment that exists, the environment half to environments/<id>.yaml with the same id; in the legacy flat layout it writes to the profiles.yaml register. Start from the defaults of a platform (--platform), a copy of the driver half of a profile, which names the same environment (--from), or a whole profile from a file (--file). Assignments after the id change the new profile before the write.
Argument
Description
id
Id of the new profile
assignment
Fields to set on the new profile, as <path>=<value>, e.g. base_url=http://127.0.0.1:4180; a field of the environment half goes to the new environment
Option
Description
--platform <platform>
Start from the defaults of a platform: web, terminal, desktop
--from <id>
Start from a copy of the driver half of an existing profile; the new profile names the same environment
--file <path>
Read the whole profile from a JSON or YAML file; its environment fields become the new environment
--environment <id>
Name an environment that exists instead of writing a new one (format "0.0.1" only)
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
flint orbtest profile set [options] <id> <assignment...>
Set one or more fields of a profile. The value is YAML. agent.target is checked against the Orbh profiles; a profile with no agent block gets agent.kind orbh. Under format "0.0.1" this is the driver half: a field of the environment half is refused with the environment set command that owns it, and environment=<id> names another environment.
Argument
Description
id
Profile id
assignment
One or more <path>=<value>, e.g. agent.target=claude/o5m viewport.width=1440; with --file, one bare <path>
Option
Description
--file <path>
Read the value of the one <path> from a JSON or YAML file
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Remove one field from a profile. Under format "0.0.1" this is the driver half; it removes a field of the environment half only when the UI profile file holds it by mistake, and names environment unset otherwise.
Argument
Description
id
Profile id
path
Dotted field path, e.g. agent.target
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Rename a profile. Rewrites task.profile, task.steps[].on, suite.profiles[], and profile: in ui/briefs/*.yaml, and renames its ui/baselines/<suite>/<entry>/<old>.png and .json. The environment keeps its id; rename it with environment rename.
Argument
Description
old
Current profile id
new
New profile id
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Remove a profile: its driver half under ui/profiles/ in format "0.0.1", its entry in the profiles.yaml register in the legacy flat layout. Refused while a task or a suite uses it; each user is named. The environment stays; remove it with environment remove when no other profile names it.
Argument
Description
id
Profile id
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Add an environment to environments/<id>.yaml. Start from the environment half of the defaults of a platform (--platform), a copy of an environment (--from), a whole environment from a file (--file), or, with none of the three, the id alone: a behaviour environment needs no other field, e.g. environment add scratch place=local. Assignments after the id change it before the write. A profile names it with profile set <profile> environment=<id>, or profile add <profile> --environment <id>; a behaviour spec or case names it with environment: <id>.
Argument
Description
id
Id of the new environment
assignment
Fields to set on the new environment, as <path>=<value>, e.g. base_url=http://127.0.0.1:4180
Option
Description
--platform <platform>
Start from the environment half of the defaults of a platform: web, terminal, desktop
--from <id>
Start from a copy of an existing environment
--file <path>
Read the whole environment from a JSON or YAML file
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
flint orbtest environment set [options] <id> <assignment...>
Set one or more fields of an environment. The value is YAML. A field of the UI profile is refused with the profile set command that owns it. Every profile that names the environment sees the change.
Remove one field from an environment. A field of the UI profile is removed only when the environment file holds it by mistake; otherwise the profile unset command that owns it is named.
Argument
Description
id
Environment id
path
Dotted field path, e.g. version_check
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Rename an environment. Rewrites the environment field of every UI profile that names it. A file environments/<old>.yaml that holds only this environment becomes environments/<new>.yaml. A requirement that names the old id in its profiles field is not rewritten: when no profile has the old id, the rename is refused and names the requirement; change it first with requirement set.
Argument
Description
old
Current environment id
new
New environment id
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Append one deterministic check to the final verify of a task. A verify that is one mapping becomes a list that keeps the entry. The check goes into the first deterministic entry, or into a new deterministic entry when there is none
Argument
Description
id
Task id
Option
Description
--kind <type>
Check type: dom, route, sql, or command (any registered type)
--arg <path=value...>
One field of the check, e.g. pattern=/mesh/:id or locator.strategy=role. The value is parsed as YAML
--file <path>
Read the fields of the check from a JSON or YAML mapping; --arg values override it
--verify <n>
Append to this 0-based deterministic verify entry (default: the first deterministic entry)
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Create a negative control: a copy of a task with the profile, story, seed, pacing, steps, and verify of the source, one wrong input, and expect: fail. The file is ui/tasks/<id>.yaml
Argument
Description
source-id
Id of the task to copy
Option
Description
--input <key=value>
The one input to replace and its wrong value. The value is parsed as YAML
--id <id>
Id of the new task (default: <source-id>.wrong-<key>)
--name <text>
Name of the new task (default: "<source name> with the wrong <key>")
--description <text>
Description of the new task (default: a negative-control sentence)
--verify <n>
Keep only this 0-based deterministic verify entry, as one mapping (default: copy verify as it is)
--without-story
Do not copy the story of the source task
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Change the id of a story and rewrite task.story in every task and story: in every brief that names it. A file stories/<old>.yaml that holds only this story becomes stories/<new>.yaml; any other file keeps its name. Refused when the target file exists.
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Change the id of a suite and move ui/baselines/<old>/ to ui/baselines/<new>/. A file ui/suites/<old>.yaml that holds only this suite becomes ui/suites/<new>.yaml.
Argument
Description
old
Current suite id
new
New suite id
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
List, show, and change the machine requirements: one file per requirement in requirements/ under format "0.0.1", requirements.yaml and the files named by profile.requirements in the legacy flat layout
Add a requirement: to requirements/<id>.yaml under format "0.0.1", to requirements.yaml in the legacy flat layout, or to the --in file in either. name, check, and guidance are required. The file is created when it is absent.
Argument
Description
id
Id of the new requirement, unique in its file
assignment
Fields as <path>=<value>, e.g. name="Node.js 22" check="node --version" guidance="Install Node.js 22."
Option
Description
--in <file>
Requirements file, relative to the definitions root. Format "0.0.1": a file in requirements/ (default: requirements/<id>.yaml). Legacy flat layout: a requirements file (default: requirements.yaml, or the one loaded file that holds the id)
--file <path>
Read the whole requirement from a JSON or YAML file
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
flint orbtest requirement set [options] <id> <assignment...>
Set one or more fields of a requirement. The value is YAML.
Argument
Description
id
Requirement id
assignment
One or more <path>=<value>, e.g. version.expect="^v22"; with --file, one bare <path>
Option
Description
--in <file>
Requirements file, relative to the definitions root. Format "0.0.1": a file in requirements/ (default: requirements/<id>.yaml). Legacy flat layout: a requirements file (default: requirements.yaml, or the one loaded file that holds the id)
--file <path>
Read the value of the one <path> from a JSON or YAML file
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Requirements file, relative to the definitions root. Format "0.0.1": a file in requirements/ (default: requirements/<id>.yaml). Legacy flat layout: a requirements file (default: requirements.yaml, or the one loaded file that holds the id)
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Remove a requirement from its file. A file must keep at least one requirement.
Argument
Description
id
Requirement id
Option
Description
--in <file>
Requirements file, relative to the definitions root. Format "0.0.1": a file in requirements/ (default: requirements/<id>.yaml). Legacy flat layout: a requirements file (default: requirements.yaml, or the one loaded file that holds the id)
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
flint orbtest services set [options] <name> <assignment...>
Add a service to the machine-local services file, or change one. A new service needs command and ready. Refused while git would commit the file (gitignore *.local.yaml).
Argument
Description
name
Service name; a new name adds a service
assignment
One or more <path>=<value>: command, ready, cwd, timeout_ms, env.<NAME>; with --file, one bare <path>
Option
Description
--profile <id>
The profile whose setup.local_start names the file (default: the one file all profiles name)
--file <path>
Read the value of the one <path> from a JSON or YAML file
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
List each env:// name the definitions reference, and each name in .local/secrets, with its state: set, empty, or missing. A folder that has not moved yet is read from .secrets-orbtest too, as the harness reads it. Never prints a value.
Option
Description
--root <dir>
Directory holding orbtest/ (default: cwd)
--json
Print the result as JSON on stdout; human lines go to stderr
Add names to .local/secrets with an empty value. A name already in .local/secrets or in .secrets-orbtest is left as it is. The agent adds names only; the human enters the values with secret enter.
Argument
Description
name
One or more environment variable names, e.g. ONYX_EMAIL
Option
Description
--dry-run
Print the names the command would add, and write nothing
--root <dir>
Directory holding orbtest/ (default: cwd)
--json
Print the result as JSON on stdout; human lines go to stderr
Ask the human for secret values in a local browser page, and write them to .local/secrets. Serves one form on 127.0.0.1 with a one-time token, accepts one submit, then stops. Prints only the names it set. Refused while .local/secrets is not gitignored.
Argument
Description
name
Names to ask for (default: every referenced or listed name with no value)
Option
Description
--timeout <ms>
Stop and write nothing after this many milliseconds (default: 600000)
--no-open
Do not open a browser; print the URL only
--root <dir>
Directory holding orbtest/ (default: cwd)
--json
Print the result as JSON on stdout; human lines go to stderr
Delete old run folders of each kind: task runs (<run-id>), author-, snapshot-, doctor-, and behaviour-. The newest --keep of each kind stay. A snapshot run that a baseline names in its run field always stays, and a behaviour run that a sidecar anchor names always stays; neither counts against --keep.
Option
Description
--kind <kind>
Only this kind: run, author, snapshot, doctor, behaviour (default: every kind)
--keep <n>
Folders to keep per kind, newest first, 0 or more (default: [runs] keep of orbtest.toml)
--runs <dir>
Run record directory (default: <orbtest>/.local/runs); it must be inside the definitions root
--root <dir>
Directory holding orbtest/ (default: cwd)
--dry-run
Print a unified diff of each file the change would write, and write nothing
--json
Print the result as JSON on stdout; human lines go to stderr
Port to bind in --ephemeral mode (default: the first free port from 14040)
--path <dir>
Path to flint (default: auto-detect)
--steel-url <url>
Paired Steel host URL for cascading shutdown
--ephemeral
Run unregistered (no registry/discovery) — for a dev instance parallel to a live server
--dev-plate <name=url>
In-memory dev-plate override (repeatable), e.g. tasks=http://127.0.0.1:13501 (default: [])
--dev-origin <origin>
Approve the origin of a web client of this --ephemeral server, such as the Steel of steel dev --ephemeral (repeatable; http://127.0.0.1:<port> or http://localhost:<port>) (default: [])
Serve the Steel host from the Steel build of this CLI. --machine: one host for every Flint of this computer (http://<flint>.localhost:<port>/), the mode that Blacksmith runs
Option
Description
--machine
Serve every Flint of this computer from one port (default 13035)
--port <port>
The port of the Steel host
--host <host>
The host to bind to (default 127.0.0.1)
--server <url>
Without --machine: the URL of the Flint server (default: found or started for the Flint of --path)
--path <dir>
Without --machine: the path of the Flint (default: the Flint of the current folder)