CLI commands
This page maps the command surface. For a command’s exact options, run
orbit .
Global options
Section titled “Global options”| Option | Effect |
|---|---|
--root |
Override the Orbit root directory. Highest precedence. |
--workspace |
Select a workspace by registered name, logical ID (ws_), or absolute checkout path. Only an active workspace can be selected. Unlike --root, it does not change the root directory. |
--format |
auto (default: a table on a terminal, plain text when piped), table, plain (full tab-separated values on any sink), json, or ndjson. |
--json |
Shorthand for JSON output, always pretty-printed. Accepted throughout the command tree, including plugin groups. Plugin-derived --json tool-input flags keep their own meaning; select output JSON at the root/group or with --format . A conflicting --format produces a JSON usage error on stderr and exit 2. |
--header |
Start plain output with a tab-separated header row. Table output always has one. |
Every subcommand accepts these options too, so orbit
and orbit are equivalent. This site puts them
before the subcommand. audit keeps its command-local --format
for the exported file; --json selects the output mode independently and
leaves the existing export confirmation unchanged.
Environment
Section titled “Environment”| Command | Purpose |
|---|---|
orbit |
Set up the global Orbit root, this machine’s [machine] identity and task-ID prefix, and the default skills. --machine- and --task- choose a fresh identity. --force resets the global root to shipped defaults, including the machine identity, and creates a new machine ID. --non- skips prompts and requires both identity flags on a fresh machine or forced reset; missing or invalid flags are refused before deleting the root. Ordinary re-init preserves the identity. --skip- (or ORBIT_) leaves the Linux Bubblewrap and AppArmor setup to the host’s administrator. |
orbit |
Register the current repository as a workspace. --name, --base-, --ship-, --role (replica requires --owner ), --task-, --mcp, --inject-, --preset (see workspace presets); --force reconciles an already registered workspace. |
orbit | show | sync | role |
List and show registered workspaces, converge managed artifacts (sync), and validate this checkout’s role (role). |
orbit |
Print the workspace’s ship mode, or rebind it in the workspace registry without re-running init. Config files and managed defaults are left untouched. |
orbit | rebind |
Show the workspace’s source-repository identity, or replace the source remote after a repository transfer (rebind ; try --dry- first). Use a credential-free Git origin and a credential helper: fresh registration refuses origins containing embedded credentials. |
orbit | show | rebind | remove |
Manage this owner’s binding to a dedicated task-publication repository. See Publish and Restore Tasks. |
orbit | teardown |
remove deregisters a workspace; teardown removes Orbit artifacts from it. |
orbit | get | set | keys | path |
Read and write configuration, including this machine’s identity under machine.. Rename the machine with orbit . See Configuration. |
orbit | list | show | rename | remove |
Register and inspect the remote Orbit hosts this machine reaches over SSH. add reads the host’s machine ID, name and task prefix from the host; list and show read reachability, version, pull protocol and workspaces live; remove drops a host a replica or pull drain still uses. Federated MCP, pull drains and replica worktree GC route to these hosts. |
orbit | install | verify | remove |
Install, verify and remove the headless browser kit that workers use to check UIs. The kit lives in ~/ (Playwright at the version this release pins, plus Chromium’s headless shell, downloaded from Playwright’s CDN) and needs Node installed. Once verify passes, every agent receives PLAYWRIGHT_, PLAYWRIGHT_ and ORBIT_. Run it on the host, as the user who runs workers. |
orbit | list | show | upgrade | enable | disable | remove | doctor | sync |
Install and manage plugins. See Install and grant plugins for the install, grant and enable workflow. validate, test, scaffold, and migrate support plugin authoring. Installed plugins’ command groups appear under Plugins: in orbit . |
orbit | list | rm |
Manage the secrets a plugin declares in spec.. set reads the value from stdin or a no-echo prompt, never from an argument. list shows whether each secret is set, never its value. rm deletes one. |
orbit |
List pending . layout and store migrations; --confirm applies them. |
orbit |
Install a published release and converge to it. --check, --version, --allow-. --preflight checks whether running Orbit processes prevent an upgrade without opening stores, and --contract describes the executable admission protocol without opening state. --local- installs an operator-attested local build pinned to a full commit, with --write-, then --candidate- and --install-. |
A plugin source keeps its plugin in a . directory that holds
plugin.. That directory is the plugin root and the only tree installed.
plugin , validate, test, sync, and upgrade refuse a top-level
plugin., with no fallback: move plugin. and its tree into
., or run orbit to create the current layout.
Plugins install once per machine; a checkout pins the plugins it uses in
., which git ignores with the rest of ..
Knowledge
Section titled “Knowledge”A task ID’s prefix names the host that holds it. A command that addresses one
task by ID (show, update, artifact and put, review-reset,
reconcile-review, and orbit of those tools) goes to that host when
it names no --workspace. An ID with this machine’s prefix runs here; a
registered host’s prefix is answered by that host; any other prefix is refused
with unknown_task_prefix. If the holder does not answer, the command fails
with owner_unreachable rather than reading a local copy. To read a local
mirror, pass --workspace explicitly. --host names the host for
--workspace, by name or machine ID, so you can write --host instead of the selector alpha lists.
| Command | Purpose |
|---|---|
orbit |
Create a task. --title and --complexity are required. --origin records why it was filed: operator_, orchestrator_ or automation. |
orbit |
Update fields. --approve takes the next approval step (proposed , review ) and is refused while a non-terminal local run lists the task. --status follows the lifecycle table; --force overrides it. |
orbit |
List tasks of every status by default. Filter with --status, --tag, --origin, --path, --ready, --ref. --scheduled lists future schedules soonest first, including proposed tasks labelled by status. --not- and --not- accept inclusive RFC 3339 bounds. |
orbit |
List backlog and proposed tasks whose context-file lock surface overlaps no in- or review task, by the same lock test automatic dispatch uses. Nothing else is checked: not dependencies, complexity, groups, crew, or overlap between candidates. --status , --path, --limit; --explain also lists held-back candidates with the overlapping file and the task holding it. Read-only. JSON shape: Response shapes. |
orbit |
Show one task: on this machine, found by ID across registered workspaces, or on the host its prefix names. A proposed or backlog task gets a Readiness: line naming what blocks drain approval or admission, with a fix for each gap. A task a failed run left blocked prints a Next: line, and a recorded final-recovery decision prints Final ; a routed show uses the same words. --json carries next_ and final_. --fields selects specific fields. |
orbit |
Archive an open task. done and rejected tasks cannot transition to archived. Archived is terminal; a human can restore it with task . |
orbit |
Manage task artifact files. See Task artifacts. |
orbit |
Flag context declarations that need repair and vague acceptance criteria. Without an ID, sweeps active tasks; --status narrows the sweep. --restore- re-declares context_ entries that an earlier prune recorded in task history. |
orbit | submit | status | accept- |
Let a review task complete when a recovered follower’s delivery has already merged. inspect shows whether the merged delivery can be reconciled, and why not. submit validates and independently reviews the merged head; resubmitting the same --request key replays the same reconciliation. status shows reconciliation outcomes, their runs, and the next step (--reconciliation narrows it to one). accept- records an audited disposition of a required command that already fails at the base: --reconciliation, --command, --remediation (a commit on the landing branch that remediates the failure), and --reason are all required. |
orbit |
Show filed-versus-closed rates over time, to tell whether the backlog is draining. |
orbit |
List tasks blocked by a missing provider launcher or transient infrastructure (such as a busy lock), and whether the cause has cleared. --confirm returns cleared tasks to backlog. A transient block also requires a stopped run, writable store, and free task lock; a stopped unpublished run can requeue when those checks pass, while a published candidate requires an authenticated handoff. Unbound or unauthenticated publications and later human intervention leave it for task . Each published candidate (or unpublished task) is automatically requeued at most twice. Tasks blocked by their own failure stay blocked. The launcher is resolved from the invoking shell’s PATH and HOME. |
orbit |
Reset one review lineage’s budget with an audited reason. --lineage and --reason are required; --adopt- takes the current configured budget instead of the captured one. |
orbit |
Return a blocked task to the queue onto its published candidate, with an audited reason. --discard- reruns it from scratch instead. |
orbit |
Retry a stopped authorized handoff through normal owner landing. Every expectation is required, so a stale view is refused: --owner-, --candidate, --base, --attempt, --state , --reason, and a --request key that replays a retry after a lost reply. |
orbit |
Operator only, on the owner: recover a live follower claim to blocked or backlog, fencing its attempt and releasing its reservation. --phase, --status, --reason and --request are required; reuse the request key after a lost reply. |
orbit |
Operator only, on the owner: revoke an accepted handoff’s completion authority while its task stays in review. --candidate, --base, --reason and --request are required; an unresolved external merge intent refuses revocation. |
orbit |
Settle a blocked, in- or review task to done when its Orbit delivery pull request was merged outside Orbit and no run or claim of its own is live. It records a landing note naming the pull request and merge commit and starts no work. Without an ID, it matches every candidate task against recently merged pull requests; each orbit pass does the same. |
orbit |
Settle an owner-recovered follower claim’s merged delivery when its handoff was refused and its PR was rescued by hand. Supply the full original published head. The owner verifies the admission’s landing branch and delivery identity, records the operator-reported original head, merged head and merge commit as operator-, and moves the task to done without force. The recovered claim stays revoked. |
orbit | contention | reserve | release |
Inspect and manage the file locks that gate parallel dispatch. |
orbit | import | reindex |
Export and import portable tar. task bundles, and rebuild the task index. |
orbit | status | inspect | restore |
Publish, check, read, or restore a task snapshot. Nothing publishes automatically. |
Scheduled tasks
Section titled “Scheduled tasks”Set a task’s earliest start with orbit ;
clear it with --clear-not-before. The CLI accepts RFC 3339 with an offset or
a local YYYY-MM-DDTHH:MM. orbit shows future times
in schedule order in text and JSON, including proposed tasks. Approval and
dispatch remain separate; the schedule is an earliest start, not an exact-time
promise. orbit shows Scheduled and Actual start separately;
--fields selects those values.
An operator can start named tasks early with
orbit . It records a schedule_overridden
history event for that scheduled time; changing not_before reinstates the
hold for the new time. The override is available only on the CLI.
The dashboard task detail has the same Scheduled value and actual first start. Its editor accepts RFC 3339 with an offset and clears on an empty save. A backlog card shows a Scheduled chip while its hold applies. The forecast waits for the scheduled instant before admitting the task.
Decision requests
Section titled “Decision requests”With decision_channel. on (see Configuration), work
held on a human decision — a blocked-task triage proposal or a task-pilot
admission hold — raises a decision request. orbit lists a task’s
open requests in open_decisions.
| Command | Purpose |
|---|---|
orbit |
List open decision requests. --gate and --task filter; --all also shows answered, superseded and expired requests. The MCP tool orbit. returns the same. |
orbit |
Show one request with its allowed answers, binding, expiry and resolution. The MCP tool is orbit.. |
orbit |
Answer one open request as the operator; --note keeps evidence with the answer (a pilot-admission verdict uses it as its evidence). The answer lands as a human write and the request then reads answered. A superseded or expired request is refused and nothing changes. There is no answering tool: an agent can list a request but cannot answer it. The dashboard’s task detail offers the same answers as buttons. |
orbit |
Submit a human’s answer through a registered decision channel: --channel and that request’s --token are required; --note keeps evidence with it. |
orbit |
Raise any missing approval requests for a channel and show its decision digest. |
orbit | list | revoke | rotate- |
Register, list, revoke and rotate this host’s decision channels. |
For channel setup, plugin authentication and token recovery, see Decision channels.
With task , a single field returns its bare JSON value,
whether read locally or from another host. The terminal field stays keyed as
{"terminal": or {"terminal": . Multiple fields return an object
keyed by the requested field names.
Friction and search
Section titled “Friction and search”| Command | Purpose |
|---|---|
orbit | list | show | stats | tags | update | resolve | rehome |
Report and triage friction records. rehome moves a record to the registered workspace that owns it. |
orbit |
Lexical search over tasks and frictions. Task fields use FTS5 BM25 ranking, and query terms need not be adjacent. --workspaces (repeatable) adds other registered checkouts and is separate from the global --workspace; --all- searches every active workspace on this machine. |
orbit |
Rebuild the lexical task index after an import or restore. Reports task and chunk counts. |
Operate
Section titled “Operate”Workflows
Section titled “Workflows”| Command | Purpose |
|---|---|
orbit |
Ship the selected tasks, or the ready backlog, through the gated pipeline. Returns a run ID immediately. --base, --allow-, --strict-, --claim-. |
orbit |
Deliver in place instead of opening a pull request. |
orbit |
Drain the backlog for a time window. --concurrency; --allow-; --low-, --medium-, --hard-, --xhard- (crew pools for tasks with no crew, as crew or crew:, overriding the [workflow] pools); --strict- (require a systemd user scope for the coordinator and every worker, overriding machine. with strict for this drain); --auto- (forecast admission mode for this local drain, overriding machine.; pull drains inherit their host’s mode and refuse it); --claim- when another operator holds the workspace claim. |
orbit |
Authorize every pass of a local drain to pilot and approve qualifying proposed tasks, including tasks filed during the window. Qualifies with no-, or context files and an assessed complexity; duplicate, already-landed, conflict or warning findings keep it proposed. no- opts out. Off by default; approval is separate from --complete. See Authorize the backlog. |
orbit |
On a replica checkout, pull work from the owner named by the host-qualified selector, or by --pull . Each claim runs as a leaf that ends at a pull request handed back to the owner, which keeps landing authority. Takes --for and --concurrency; --allow- limits which crews’ tasks are claimed. Conflicts with --complete, --approve-, --strict-, the crew-pool flags, --claim-, and --stop. See Set Up a Distributed Drain. |
orbit |
Stop new admissions for this workspace’s active auto coordinator. Admitted workers keep running; this is not cancellation. On a replica it also delivers any recorded pull settlements to the owner, even with no active drain. |
orbit |
Authorize a local drain to repair the pull requests its runs opened when a required check fails or the branch conflicts with its base, using a crew from workflow., else workflow.. Pending checks wait. Approvals, permissions, admin rules, unknown status and optional-check failures get no agent. At most three repairs per PR. Never merges; add --complete for that. Off by default; conflicts with --pull and --stop. See Repair blocked pull requests. |
orbit / orbit |
Add before- or before- review to this run when workspace policy applies none. The layer review. already applies is accepted unchanged. The other layer, a workspace that sets neither workflow. nor workflow., and local-only delivery are refused before the run starts. Conflicts with --pull and --stop. Children and resumes keep the captured layer. See Review layers. |
orbit / orbit |
Also authorize the run to finish delivery and move the tasks it ships from review to done. Off by default. |
orbit |
Explain, read-only, why backlog tasks can or cannot start. --concurrency overrides the ceiling; omit it to use the live local drain’s ceiling, else a live pull drain’s (including orbit ), else 5. --json names that choice as capacity. and carries weekly usage pressure per provider account and crew (provider_, crew_). --allow-, --limit. |
orbit |
Preflight proposed and backlog tasks and save validated selectors. Omit IDs to discover tasks automatically. --base-, --max-, --max-, --wait. |
orbit |
Run any job by ID or YAML path. --input , --wait. |
orbit |
Operator only. Run an agent on the host to investigate and report. It runs outside the filesystem sandbox, changes no task, and dispatches nothing. --cwd, --crew, --timeout (default 1800 s, max 7200), --wait, --idempotency-, --provider-. Returns a run ID to read with orbit or logs; --wait blocks and prints the answer instead. |
See Delivery Workflows.
--allow-crew accepts a named crew or an alias with the same provider, model
and provider account. A crew with its own env has a separate account, so
allow it explicitly even when its model matches another permitted crew.
Pull drains with before-landing review can admit replacements while leaves
are reviewing: at an unchanged concurrency of N, at most N leaves implement
and at most 2N are occupied, absent pre-existing excess. Lowering the ceiling
keeps running leaves. orbit reports the claim stages.
Run inspection
Section titled “Run inspection”| Command | Purpose |
|---|---|
orbit |
Recent job runs. -j , --task , --state (comma-separated) and --since filter; --limit defaults to 50. --incidents shows one row per incident, folding runs that failed only because a child failed into the run that failed on its own. --failures shows one row per task and root cause: the root-cause run, its step and crew, the cause’s first line, and the orbit command for that run. --no- reports stored records as they are. |
orbit |
State and step summary for a run; defaults to the most recent. -s shows one step. A delivery run with a review layer prints a Review: line with the layer and its origin: the run’s --review option, workspace policy (with the key’s source), or the owner’s claim. A worktree GC run lists each worktree it kept, with the reason and retained_, and each dirty worktree it removed, with where the candidate went. |
orbit |
Raw stdout and stderr captured for a run. --follow streams until the run ends. |
orbit |
Audit events recorded for a run. |
orbit |
Parent/child tree of a run’s audit events. |
orbit |
This host’s delivery resource profiles, one row per workspace, work class and complexity (auto- profiles have none): completed deliveries, horizon, peak CPU and memory with the minute each occurs, the nearest-rank p50 and p90 of each delivery’s own single-minute peak CPU and memory (these stay high when peaks fall in different minutes, and a sparse profile still shows them), and how much deliveries spread around them. Flags no-diff work that used more than 1 core for 2 minutes and names those deliveries; templates that build by design, such as qa-, are exempt. --json adds the full per-minute series and those quantiles (delivery_, delivery_). --accuracy instead compares the forecasts drains in shadow or enforce recorded (by default the newest 5000 forecasts, whatever their age; --last another count, --since a time bound) with the host’s measured CPU and memory at +5, +10, +20 and +30 minutes (mean error, how often the forecast was under, worst miss), and counts per drain the tasks shadow would have held or added plus the tasks enforce admitted, the tasks gap fit held and the enforce pull requests held; with --json it adds the raw pairs and the held task ids. |
orbit |
On an owner, the failure and release settlements that claimed leaves on follower hosts sent it, newest first, with each one’s evidence class. Those leaves never appear in the owner’s run . --since , --json, --no-. |
Leases
Section titled “Leases”| Command | Purpose |
|---|---|
orbit / renew / expand / release |
Request or manage a workspace path lease. |
orbit / show / check / notices |
Inspect leases, conflicts and notices. |
orbit / list / revoke |
Manage scoped listener tokens as the listener user. |
orbit |
Run the token-only network listener as the listener user. |
See Hold paths with leases for setup, scope, listener authentication and examples.
Maintenance
Section titled “Maintenance”| Command | Purpose |
|---|---|
orbit |
Cancel a pending or running job run and release its task reservations. A task leaf returns to backlog with its candidate resumable; --block keeps it blocked for manual recovery. --reason records a note with the cancellation audit event. A pull drain cancels gracefully: unlaunched claims return to the owner’s backlog, and launched leaves finish and settle. --force also stops a drain’s in-flight leaves. |
orbit |
Move a live orbit window, or a replica’s --pull drain, to the later of its current deadline and now plus --for, without restarting it: the run ID, completion authorization and in-flight tasks carry over. It never shortens a window, and refuses a drain stopped with --stop, one being cancelled, and one started without --for. --concurrency also sets the admission ceiling; --reason; --claim- as for run . |
orbit |
Change how many tasks a live drain keeps in flight. --reason, --if-. --claim- (or ORBIT_) supplies this workspace’s exclusive claim when another operator holds one. |
orbit |
Report job-run worktrees whose task has settled; --confirm reaps them. --run limits to one run; --older- to runs finished at least that long ago. A whole-worktree dry run skips the size estimate unless you pass --estimate-. --reclaim reports bytes per declared worktree. pattern and reclaims those paths with --confirm, keeping the checkout. Terminal runs, registration, worker liveness, confinement, symlinks and Git content are checked. --target- remains an alias. A kept worktree reports retained_, its remaining size, with --confirm or --estimate-. A manual pass keeps every dirty worktree (skipped:); only the scheduled worktree_ removes a settled run’s dirty worktree, after it preserves the candidate. |
orbit |
Report deployment directories in ~/, replaced-executable copies in ~/ and ~/ store copies beyond the newest of each class; --confirm removes them. --keep (default 2) sets how many of each class stay. The installed executable and every . rollback copy are never removed. |
orbit |
Report audit rows older than retention. (host-wide command audit, this workspace’s run audit, and run audit of workspace ids that are no longer registered) and the audit blobs no remaining row names, with rows and bytes per table and blob root; --apply deletes them in batches of 1,000 rows. Another registered workspace keeps its own window. A blob written in the last 24 hours or marked pending by a write in progress is kept. Reports the store file’s freelist; run VACUUM yourself to return it. --older-. |
orbit |
Report terminal runs older than retention. that still keep pipeline state, for this workspace and for workspace ids that are no longer registered; --apply drops that state and stamps the run archived. Another registered workspace keeps its own window. The run, its steps and its summary stay, so run and run history keep working. Held and non-terminal runs are never touched. The host’s per-minute resource history and recorded admission forecasts older than 30 days go in the same pass, except rows kept at any age by count: each workspace, work class and complexity’s newest max(200, deliveries, the newest 10,000 forecasts, and host minutes from the oldest kept forecast onward. --older-. |
orbit |
Report applied task commit journal rows older than retention. (default 14), for this workspace and for workspace ids that are no longer registered, with rows and bytes; --apply deletes them. Each task’s newest applied row, every prepared or committed row recovery may replay, and aborted rows are kept. Another registered workspace keeps its own window. The rows are selected by one read that holds no write lock, then deleted by key in batches of 1,000. --older-. |
orbit |
Report this workspace checkout’s scratch contents (.) and empty it with --confirm, keeping the directory. --confirm refuses while any job run is pending, running, or retrying, and the command needs Linux or macOS. Without --confirm it only reports; --dry- requests that default explicitly. |
On a replica, orbit reaps a claimed run whose claim is already
settled with the owner without checking its task. For any other run, it asks
the owner machine for the task’s status. A failed lookup is skipped and
reported as skipped:owner_unreachable (transport failure),
skipped:owner_lookup_failed (any other lookup failure), or
skipped:no_owner_route (no route to the owner), with the reason in detail.
Jobs and tools
Section titled “Jobs and tools”| Command | Purpose |
|---|---|
orbit | show | run | replay | resume |
List job definitions and the activity each step runs. Run a job by ID or YAML path, replay a previous run from step 0, or resume an interrupted run from its step checkpoints. See Activities and Jobs. |
orbit | show | run | add | scaffold | remove | enable | disable | doctor |
List, inspect, and run registered tools; manage external tools and MCP plugins; check tool health. scaffold is a deprecated alias for orbit . |
Experiments
Section titled “Experiments”| Command | Purpose |
|---|---|
orbit | update | clone |
Define a draft experiment: --arms (a JSON array of {name, with exactly one control), --hypothesis, --population, --primary-, --guardrails, --min-, --max- and --mode . Only a draft can be edited; clone copies a definition into a new draft. |
orbit | pause | resume | reweight | conclude | abandon |
Move an experiment through its lifecycle. start needs experiments. and a free experiments. slot; reweight or --retire opens a new segment. conclude records the chosen arm, stores the readout at that moment and files one proposed task naming the experiment, arm, verdict and overlay; omitting --arm records no winner and files nothing. Concluding changes no configuration or repository file. pause, reweight, conclude and abandon require --reason. Only an operator may run these. |
orbit |
Force a nonterminal task into an active arm of a running experiment, shadow or live. The task must have no arm assignment or an explicit_ exclusion for this experiment; that exclusion is replaced. Records forced:; existing arm assignments and other exclusions for the experiment stay sticky, and overlapping surfaces owned by another experiment are refused. Forced assignments are left out of the readout. Operator only. See Run an experiment. |
orbit |
Show per-arm outcomes computed now, intention-to-treat with forced assignments left out and counted: n, mean and median with 95% bootstrap intervals (fixed seed) or Wilson intervals for rates, open (lagging) outcomes, crew mix, each arm’s difference from control post-stratified by complexity, guardrail status, a sample-ratio chi-square against the weights (verdict withheld below p = 0.001), and overlay-digest drift. The verdict is collecting until every arm reaches --min- or --max- passes, then winner , no , or inconclusive. --metric reports only that metric; the verdict is still read on the primary metric and guardrails. The shape carries schema_. Read-only; agents may call orbit.. |
orbit | list |
Show one experiment with its arms and every event in order, with actor, time and reason, or list the workspace’s experiments (--status filters). Agents may call orbit., orbit., and orbit.. |
Observe
Section titled “Observe”| Command | Purpose |
|---|---|
orbit | show | prune | export | stats |
Query the audit event log. |
orbit |
Rank repository paths by how often done tasks regressed at a recorded site under them, how often the tasks that declared them widened their footprint onto them, were blocked by a run failure or were rejected after a run, plus lock contention and paths reserved together, and list the paths in several rankings. A done task counts as regressed under a path only where a regression_ link to it records a defect site (regression.) under that path, not against its whole footprint. A regressed task none of whose links record a site counts under no path; the Regressions ranking reports it as unsited. Its denominator is the done tasks that declared the path or were sited under it, so a task whose site names a path it never declared adds that task there. Each rate shows its numerator and denominator. --window (default 90d), --min- (smallest denominator a ranked row needs, default 15) and --rollup . The table shows each ranking’s top rows; --json is the dashboard’s Codebase payload. The MCP tool orbit. returns the same. |
orbit |
One path’s rate, numerator, denominator and place in every ranking, with the task IDs behind each numerator (refused requesters for lock contention, and the requesters behind each coupled pair). The Regressions ranking also lists the defect sites recorded under the path with the regressed tasks that name each, and counts the regressed tasks that declared the path but record no site. Takes the same selection flags; the path is a key at the chosen rollup. The MCP tool is orbit.. |
orbit |
List files that usually change alongside one repository file, from tasks that landed together. --window (default 30d), --min- (shared landed tasks, default 15) and --top (1–100, default 10). |
orbit |
Rank one agent role’s crews and models: orchestrators (by tasks’ orchestrator attribution, with model ), implementers, reviewers or pilots. Each term’s count per 100 units of the role’s work is weighted and summed, then pulled down toward the fleet average when above it; the table shows rank (below under the minimum support), crew, model, units, score and each term’s count, then the weights. A role not computed yet says so. --window (default 30d; all is served as 90 days; lastN reaches back to the start of the newest N delivery attempts within the 90-day scan, whatever their age) and --min- (the units a row needs before it is ranked, default 10). Each call scans once and reports cache_. --json is the dashboard’s / payload; the MCP tool orbit. returns the same. Implementers only: --by- splits rows by task type within each complexity tier; --by- (for example orbit ) compares recorded draw shares with the shares the crew-performance factor would have given, and --shadow requires --by-; --per- exports one row per implemented task (use --json for the machine-readable export) and cannot be combined with --by- or --shadow. |
orbit |
One row’s terms, each with its weight, count, rate and contribution, and the tasks behind every count with the records that made it. --model picks the row when the crew has several. Takes the same selection flags; the MCP tool is orbit. (the row’s model is row_ there). |
orbit | show |
Deprecated aliases of orbit , removed in the next release. They print a note naming the replacement to stderr; --json and the orbit. tools carry it as deprecation. |
orbit |
Tail the unified Orbit log feed. |
orbit |
Check workspace health: config, database, disk, indexes, locks, runs, and tasks blocked by a missing provider launcher (infra-). Rows are ordered by severity: errors, warnings, ok, info, then skipped. The failure and warning count is written to stderr before the report, so it appears above a terminal table without becoming a plain stdout record; plain output remains tab-separated rows and JSON remains the full unfiltered array. --problems limits the human report to errors and warnings. Terminal tables are followed by full non-ok findings, with messages and Fix: actions wrapped to the sink width and ordered errors, warnings, then skipped. Truncated tables with findings point to --format or --json; all-ok output has no findings or hint. The --fix- flags are opt-in repairs, and --remove- removes retired graph state from this worktree and the shared workspace. --confirm authorizes the destructive repairs, such as --fix-. |
orbit |
Show owner admission receipt counts and logical payload bytes, with claim-mutation receipts reported separately. --compact replaces idle receipts, landed claim receipts and receipts of failed or revoked claims without a preserved PR with permanent tombstones keeping the machine ID, request ID and input digest; a tombstoned request is refused on replay and never admits again. Failed and revoked claims with a preserved PR keep full receipts for later external-merge settlement, even if no handoff was accepted. Claimed, running, handed-off and repair-pending claims keep full receipts; a missing claim also keeps its receipt. |
orbit |
Show each executor’s provider CLI, whether dispatch can find it (and where), and its resolved sandbox mode. |
orbit |
Dry-run a workspace-relative path against a filesystem profile’s read and modify rules. See Policy Format and Scoping. |
Scheduler
Section titled “Scheduler”| Command | Purpose |
|---|---|
orbit |
Run one scheduler pass: fire due routines and mint due auto-tasks. --dry-, --verbose. The global --workspace limits the pass to one registered workspace. |
orbit |
Alias for orbit , with the same arguments and output. |
orbit | show | pause | resume |
Inspect routines, and pause or resume them on this host only. list (alias --all) also shows routines seeded by a plugin that is switched off, marked inactive with the reason. |
orbit | pause | enable | set |
Control the host OS scheduler clock. |
orbit |
Rewrite the installed clock unit when it names a missing, moved, or stale program, then re-register it. orbit runs this as its last step. |
orbit |
Read this machine’s identity; --install- also installs the OS clock unit. |
orbit | list | show | update | toggle | mint |
Define recurring auto-task templates and mint tasks from them. list (alias --all) also shows definitions seeded by a plugin that is switched off, marked inactive with the reason. |
orbit | restore |
delete removes a definition with its scheduler cursor and delivery consumer state (--force works even while a minted task is open). restore reinstates a deleted shipped default with its shipped content. A deleted shipped default stays out of later reseeds. |
orbit | reset |
Preview or apply an audited repair of a delivery consumer. recover unsticks one stalled by a settings change and keeps its coverage debt; reset forgets the debt and re-baselines at the branch head. |
Services
Section titled “Services”| Command | Purpose |
|---|---|
orbit / orbit |
Register or unregister an MCP client integration. Clients: claude, codex, gemini, antigravity, grok, cursor, vscode, windsurf, or --all. --scope (default, repo-local) or home (user-level). --federated manages the mux entry separately. |
orbit |
Serve the MCP tool surface over stdio, or act as a client with --mode or --mode . --operator serves operator authority; in a client mode it is also the operator statement for every SSH destination opened. --orchestrator sets the orchestrator recorded on tasks the session creates and grants nothing. |
orbit |
Serve the same surface on a TCP socket. Binds 127. unless you pass --allow-. --workspace binds each accepted session to that workspace by default. |
orbit |
Serve the Orbit dashboard for the registry under the resolved root, so orbit shows only <ROOT>’s workspaces. --workspace preselects one. --operator enables Operations controls without a TTY or ORBIT_. |
orbit |
Open a remote workspace’s dashboard over an SSH tunnel. --workspace preselects the remote workspace; --root is refused. The remote server starts with --operator unless you pass --no-, which keeps Operations read-only. |
orbit |
Reopen a running, session-enabled local dashboard with a fresh private URL. --no- prints the URL without opening a browser; treat it as a credential. See Private browser sessions. |
See Use the Dashboard for connection, workspace scope, Operations controls, and authorization. See Connect Your Agent for the agent tool surface.