Command reference
From the project documentation.
These commands describe the implemented CLI. From an unlinked source
checkout, replace corb with
node src/cli.ts.
Run
corb run [DIR] [flags] [-- PI_ARGS...]Start a VM and run Pi interactively in the foreground.
DIR defaults to the current directory unless
--workspace is given without DIR. Corb selects a workspace
by a matching host path, or uses global settings when none matches.
--workspace NAME: Select a workspace from the configured sources. Without DIR, use its configured mounts and global mounts. Corb does not add cwd.--dir NAME=HOST[:ro|:rw]: Add or override a directory mount. Repeatable. The default mode is read/write.--primary NAME: Select the mount where Pi starts. An inside DIR uses the matching workspace mount. Without DIR, the first hosted workspace entry is primary. An added positional directory uses its basename. Pi starts at the primary mount's root.--trust-config: Accept the persistent configuration when the trust verdict requires confirmation.--dry-run: Print configuration and trust information without booting a VM or requiring a bound credential.--expose PORT: Expose one guest loopback port through Gondolin's ingress reverse proxy. Corb prints the host URL and records it in the session sidecar.-- PI_ARGS...: Forward everything after a literal--to Pi.
corb run ~/Code/packet-loss --trust-config
corb run ~/Code/packet-loss --dry-run
corb run ~/Code/packet-loss --expose 3000
corb run ~/Code/packet-loss -- "Read the README and propose a feature plan."Paths passed to Pi after -- are guest paths, such as
/work/packet-loss. For persistent Pi transcripts and
--continue, see the walkthrough.
Explain
corb explain [DIR] [--workspace NAME] [--dir NAME=HOST[:ro|:rw]] \
[--primary NAME] [--trusted] [--json]Print the merged configuration and trust verdict without starting a
session. Use the same mount flags as the run you want to inspect.
--json emits machine-readable output. Both formats show the
selected workspace, primary mount, and trust key. JSON uses
null for DIR when an explicit workspace has no DIR.
Selection, no-DIR behavior, and errors match corb run.
See Workspaces
for the matching rules.
--trusted adds the complete accepted snapshot for the
selected key. It works with the usual DIR, workspace and mount flags.
With no record, text says so and JSON has
acceptedSnapshot: null. Without this flag, output has no
accepted snapshot. The snapshot contains secret names and host metadata,
never secret values.
Workspaces
corb workspace ls [--json]
corb workspace show <name> [--json]workspace ls lists each workspace's source, own hosted
mounts and worst trust status. The statuses are none,
trusted, narrowed, changed and
error. It also shows invalid names, replaced copies and
orphan trust records. The command only reads. It never deletes
records.
workspace show displays one definition, its current
config and full accepted snapshots. It compares host records together
and extra-mount records against their saved DIR. A deleted extra-mount
directory shows cannot compare. Implied-host labels appear
on current config only. Accepted snapshots carry no source labels.
show takes no DIR. Use
corb explain --workspace <name> DIR --trusted to
inspect a particular folder. If a workspace has no own hosted mount,
show still lists its details and extra-mount records. Run
it with corb run --workspace <name> DIR.
Login
corb login [PROVIDER] [--device-code]
corb logout PROVIDERLog in to a subscription provider on the host.
openai-codex (ChatGPT Plus or Pro) is the only provider so
far. With no provider, login lists the providers and
whether each has a stored login.
The default login prints a URL to open in a browser. The browser
returns to localhost:1455 on the host when the login is
done. If the browser runs on another machine, or another program uses
that port, paste the address the browser ends on into the terminal.
--device-code prints a code to enter at the provider's site
instead.
logout deletes the stored login from the host. It does
not revoke it at the provider.
See Subscription logins for the configuration a session needs.
Session commands
corb ls [--json]
corb attach <session>
corb kill <session>
corb gc [--older-than DURATION] [--dry-run|-n]ls lists known sessions by joining Gondolin's registry
with Corb's sidecars. Use a session identifier from its output with
attach or kill.
attach opens a new interactive shell in a running VM. It
does not rejoin or mirror Pi's terminal.
kill sends SIGTERM to the host process that
owns the session. This allows the VM, sidecar, and audit writer to
close. There is no force-kill flag.
gc removes stale registry entries and orphaned sidecars.
It preserves a sidecar while its recorded host process is alive. Inspect
proposed removals with --dry-run.
Doctor
corb doctor [--verify-secrets] [--json]Check the host environment, dependencies, cgroup delegation, and
required credential variables. When [agent].provider uses a
subscription login, it also checks that the login exists and reports the
API hosts Corb allows automatically. --verify-secrets
additionally sends the configured credential-verification requests.
--json prints one JSON object with a checks
array and an overall ok boolean. Each check contains
name, status (ok,
warn, or fail), and detail.
Warnings keep ok true. Any failed check sets
ok to false.
If any check fails, Doctor exits with code 1. Otherwise, it exits
with code 0. Both output formats use these exit codes. Combine
--json with --verify-secrets to include
credential checks. Neither format prints secret values.
The workspace-trust line counts trusted, changed and
never-trusted workspaces. Narrowed settings count as trusted. Pending
--trust-config changes are normal and do not cause a
warning. An unreadable workspace causes a warning. A corrupt
trusted.json causes a failure.
Doctor also checks providers set only in workspace files. This includes files without own mounts. A missing workspace-only login produces a warning. A missing global login remains a failure. Workspace-only login details show a workspace count and do not list workspace names.
Image build
corb image build [--config FILE] [--tag REF] \
[--arch x86_64|aarch64]Build, verify, and tag a guest image. The default image configuration
is image/corb-image.json from the checkout.
A successful default build writes
corb:<packageVersion>-<arch>-<hash> and
the corb:<packageVersion> alias. With
--tag REF, the build writes only REF. This
includes an explicitly requested version alias. A failed verification
writes no refs and imports no object.
The hash covers the effective config, configured init files, and each
resolved postBuild.copy source and destination. Corb
resolves referenced files against the config directory and rejects
missing inputs before building. Field boundaries and config order keep
the input sequence distinct. This tag identifies effective build inputs.
It does not identify a reproducible disk or an immutable package
repository snapshot. Keep exact asset checksums and the Gondolin build
ID when recording local images.
Image inspection and sharing
corb image pin [--workspace NAME]
corb image layer build [--workspace NAME]
corb image layer push REGISTRY/REPOSITORY:TAG [--workspace NAME] [--registry-config FILE] [--ca-file FILE]
corb image layer pull [--workspace NAME] [--registry-config FILE] [--ca-file FILE]
corb image ls [--json]
corb image verify [SELECTOR]
corb image push REGISTRY/REPOSITORY:TAG [--image SELECTOR] [--registry-config FILE] [--ca-file FILE]
corb image pull REGISTRY/REPOSITORY@sha256:DIGEST [--tag REF] [--registry-config FILE] [--ca-file FILE]Commands reject unknown flags and extra positional arguments. Layer commands select the winning workspace by explicit name or ordinary cwd selection. An explicit name needs no hosted directory or primary mount.
Pin refreshes authenticated inputs. Build composes the exact cached
inputs on the selected local base. Layer push publishes inputs and binds
their immutable digest in corb.sum. Layer pull uses that
locked digest and composes locally. These commands never write
trusted.json. Base push/pull never changes workspace pins
or composition pointers.
Listing reports SDK refs and known local composition records without a VM, network or writes. Its version-1 JSON explicitly identifies the refs-only inventory. Untagged objects may be absent.
Verify resolves a selector locally. It uses the ordinary base by default and requires package coherence plus all seven gates. It neither repairs nor tags the image. See the complete sharing workflow and limits.
Current CLI limits
There are no run flags yet for image selection, memory, CPUs, network allowlists, Git repositories, per-path rules, or session duration. Configure those settings in config.toml.
Only one positional DIR is accepted. --workspace selects
a definition by name. Use repeated --dir flags for
additional mounts. --expose supports one port.