Command reference — Virgo Documentation

Shipped

These commands and options are the behaviour of the pinned release below. Every option here is one the released binary parses; the reference is checked against it, in both directions, so it can neither invent an option nor quietly omit one.

Shipped behaviour anchored to: src/cli.ts @ d62e85485903a5537ee2b73c14201597e29bdaa5

Global options

Option	Meaning
`-h, --help`	Print the usage summary and exit.

virgo onboard

Prepare this machine and record what it proves. The first run without --profile creates a private machine profile interactively; supplying --profile replays it unattended, where satisfied checks pass silently, human checkpoints remain waiting, and no prompt is issued.

virgo onboardShipped

virgo onboard [--profile PATH] [--manifest PATH] [--inspect] [--dry-run] [--json]

Measure the host, persist a resumable manifest, and pause at human-only gates.

Options

Option	Meaning
`--profile PATH`	Read a saved machine profile and replay unattended.
`--manifest PATH`	Override the resumable manifest path.
`--inspect`	Inspect only; do not write a manifest.
`--dry-run`	Show current state and remediation; write nothing.
`--json`	Emit the complete manifest as JSON.

virgo init

Create the owner's canon and the immutable implicit home workspace. Distinct from onboard: onboard makes a MACHINE part of an installation, init brings the OWNER's knowledge base into existence.

virgo initShipped

virgo init

Scaffold canon once per installation. Re-running is a guided no-op.

virgo workspace

Work-domain isolation boundaries. The implicit home workspace exists from init and its id is immutable.

virgo workspace addShipped

virgo workspace add NAME

Create an isolated work domain.

virgo workspace listShipped

virgo workspace list

List registered work domains.

virgo persona

Resident persona registration and retirement. The address is the transport address; the owner-facing name is separate metadata.

virgo persona addShipped

virgo persona add [NAME] [--scope SCOPE] [--project PROJECT] [--role ROLE] [--character TEXT] [--language TEXT] [--tone TEXT]

Options

Option	Meaning
`--scope SCOPE`	Workspace scope for the address.
`--project PROJECT`	Project segment, for a three-segment project duty.
`--role ROLE`	Role from the class registry.
`--character TEXT`	Short personality description for the character overlay.
`--language TEXT`	Working language for this persona.
`--tone TEXT`	Tone for this persona's voice.

virgo persona listShipped

virgo persona list

Read personas and their duty bindings.

virgo persona retireShipped

virgo persona retire ID_OR_ADDRESS

Stop placement and new delivery without deleting lineage. There is no remove verb — retirement preserves history.

virgo skill

Work-skill management. Personal persona skills change inside that persona's authority; shared class and workspace skills are gated by propose-approve, and activation writes an owner-private signed approval record bound to the exact proposed revision hash.

virgo skill listShipped

virgo skill list [--level LEVEL] [--target TARGET]

List skills, optionally filtered. Prints level/target/name, status, and revision hash.

Options

Option	Meaning
`--level LEVEL`	Filter by persona, class, or workspace level.
`--target TARGET`	Filter by the level's target identifier.

virgo skill add / editShipped

virgo skill <add|edit> NAME [--level LEVEL] [--target TARGET] [--content TEXT]

Create or change a skill. A personal skill activates in scope; editing a shared skill creates a proposed revision and clears any prior approval.

Options

Option	Meaning
`--level LEVEL`	persona, class, or workspace.
`--target TARGET`	The persona address, class id, or workspace id.
`--content TEXT`	The skill body.

Refusals that are part of the contract

A missing skill name refuses with skill_name_required.
An unrecognised option refuses with unknown_option rather than being ignored.

virgo skill approveShipped

virgo skill approve NAME [--level LEVEL] [--target TARGET]

Activate a proposed shared skill. Writes the signed approval record for the exact revision hash; active reads revalidate it.

Options

Option	Meaning
`--level LEVEL`	persona, class, or workspace.
`--target TARGET`	The level's target identifier.

virgo hub

Operate the pinned store runtime. Status reports unhealthy, stopped, absent, and specification mismatch instead of calling any of them running; stop preserves the container and its data.

virgo hub startShipped

virgo hub start [--config PATH]

Start or exactly resume the configured store container.

Options

Option	Meaning
`--config PATH`	Read the strict hub configuration. Defaults to $VIRGO_HUB_CONFIG, then ~/.config/virgo/hub/hub.json.

virgo hub statusShipped

virgo hub status [--config PATH]

Read health and whether the runtime matches its specification.

Options

Option	Meaning
`--config PATH`	Read the strict hub configuration. Defaults to $VIRGO_HUB_CONFIG, then ~/.config/virgo/hub/hub.json.

virgo hub stopShipped

virgo hub stop [--config PATH]

Stop idempotently, preserving container and data.

Options

Option	Meaning
`--config PATH`	Read the strict hub configuration. Defaults to $VIRGO_HUB_CONFIG, then ~/.config/virgo/hub/hub.json.

virgo records

Record-graph ingestion as an explicit four-step pipeline. Each step is separate so a change can be planned and verified before anything is applied.

virgo records plan / apply / verify / materializeShipped

virgo records <plan|apply|verify|materialize> --source PATH [--ledger PATH] [--expected PATH] [--password-file PATH] [--expected-current HASH|none] [--out PATH]

Plan a change, apply it, verify the result, or materialize a human-readable view.

Options

Option	Meaning
`--source PATH`	The source tree to ingest. Required.
`--ledger PATH`	The ingestion ledger to read and write.
`--expected PATH`	The expected-state file to compare against.
`--password-file PATH`	Read the store credential from a file rather than a prompt or an argument.
`--expected-current HASH\|none`	Require the current pointer to match, or none for an empty start. A compare-and-set: a mismatch refuses rather than overwriting.
`--out PATH`	Where to write the materialized output.

virgo record

Per-source record operations: register a source once, then keep it reconciled.

virgo record bootstrapShipped

virgo record bootstrap SOURCE_ADDRESS --workspace ID --persona ID --governing-document SHA [--password-file PATH]

Register a source address for the first time, bound to a workspace, a persona, and the governing document that authorises it.

Options

Option	Meaning
`--workspace ID`	Owning workspace. Required.
`--persona ID`	Owning persona. Required.
`--governing-document SHA`	The document hash authorising this source. Required.
`--password-file PATH`	Read the store credential from a file.

virgo record sync / statusShipped

virgo record <sync|status> [SOURCE_ADDRESS] [--source PATH --ledger PATH --expected PATH] [--password-file PATH] [--profile PATH] [--trigger manual|periodic|push] [--dry-run]

Reconcile a registered source, or report where it stands.

Options

Option	Meaning
`--source PATH`	Override the source tree path.
`--ledger PATH`	Override the ledger path.
`--expected PATH`	Override the expected-state path.
`--password-file PATH`	Read the store credential from a file.
`--profile PATH`	Read a saved profile for unattended operation.
`--trigger manual\|periodic\|push`	Record what caused this sync, so a run is attributable.
`--dry-run`	Report what would change; write nothing.

Designed

These are approved design surfaces that the pinned release does NOT expose. They are documented so the intended shape is public, and kept separate so nothing here reads as available today.

Designed surface anchored to: docs/design/CLI-SPEC.md @ d62e85485903a5537ee2b73c14201597e29bdaa5

virgo agent

Manage AI engines available on a machine. An engine install is per-machine capacity; a model is a binding chosen at persona level, not a separate install.

virgo agent list / add / removeDesigned

virgo agent <list|add|remove> [--machine HOST]

Record which engines a machine offers, with the models each provides.

virgo agent repairDesigned

virgo agent repair [--machine HOST]

Re-run login and health for an existing agent record. Expired logins are a measured state, surfaced by virgo status.

virgo adapter

Human-channel adapters. A binding is adapter × persona address × direction, and is live only after a verified delivery receipt — a real message round-trip, not a configuration check.

virgo adapter addDesigned

virgo adapter add

Pick a type, run its credential wizard, bind to a persona address and direction.

virgo adapter list / removeDesigned

virgo adapter <list|remove>

Inspect or remove bindings.

virgo adapter doctorDesigned

virgo adapter doctor [BINDING]

Wrap the channel diagnostic for a binding.

virgo persona (lifecycle)

Lifecycle verbs beyond registration. Single active copy is enforced by the hub, not by the client: a second up while a fence is held elsewhere refuses.

virgo persona up / downDesigned

virgo persona <up|down> NAME

Restore or checkpoint-and-stop, behind acceptance gates and lifecycle tokens.

virgo persona statusDesigned

virgo persona status NAME

Show fence, host, identity, health, and last-consumed age.

virgo persona checkpointDesigned

virgo persona checkpoint NAME

Land and ingest a live persona's state without stopping it.

virgo persona reincarnateDesigned

virgo persona reincarnate NAME

Context renewal for a long-resident persona: checkpoint, clear the session context, regenerate the briefing from clean records, resume as the same identity.

virgo persona launchDesigned

virgo persona launch PROJECT

Activate a project's lead or deputy on demand from its class profile.

Operations

The remaining approved verbs: scheduled duties, whole-system status, rendering, attestation, and the owner-specificity screen.

virgo statusDesigned

virgo status

Whole-system view: machines, personas, fences, queues, channel last-consumed ages.

virgo duty list / addDesigned

virgo duty <list|add>

Scheduled obligations. The scheduler executes them and emits a receipt per run.

virgo renderDesigned

virgo render [--scan]

Render config artifacts from canon. --scan reports drift instead of writing; drift is detected, never adopted.

virgo operator verify-contextDesigned

virgo operator verify-context

Produce an execution-context attestation receipt.

virgo operator promote-completionDesigned

virgo operator promote-completion

Receipt-bearing completion promotion.

virgo screenDesigned

virgo screen

Owner-specificity scan before any repository publication.

virgo machine profileDesigned

virgo machine profile

Canonical machine paths and identity — the single source for path questions.

virgo channel doctorDesigned

virgo channel doctor [BINDING]

Diagnose a silent human channel with a receipt trail, without inspecting message content.

virgo project add / list / onboardDesigned

virgo project <add|list|onboard>

Work units inside a workspace. onboard instantiates the coding-work template.