Command-line reference

Parsing and startup

Without a subcommand, aii starts the identity application. Runtime flags are -version (print version/build and exit), -dir DIRECTORY (change into identity install directory), -config FILE (select config; default install resolver uses config/config.json, with legacy config.json support). Starting the application is consequential: it can write defaults, start services and later contact configured endpoints.

The first argument selects a subcommand before runtime flag parsing. Put command-specific flags after the command and before positional arguments: aii verify -ledger COPY, not aii -dir DIRECTORY verify. These are Go flag parsers: named flags generally accept one or two leading hyphens and =value; boolean false uses -flag=false. -h/-help request parser help where a FlagSet is used, but help exit handling varies. -- ends flag parsing; flags after the first positional argument are not generally parsed. Do not assume global --help, a help verb, or Unix-style flag intermixing. slots and hardware-probe handlers ignore supplied arguments, not general flag support.

Operator commands: complete dispatched inventory

Use these direct links to find each command; syntax and consequences follow.

init

Syntax: init

-no-start: create the next slot without registering/starting. Otherwise creates a slot and attempts service startup; this is not itself successful Birth. Partial startup failure can leave a ready slot.

slots

Syntax: slots

No declared flags; lists existing slots/names/configured ports.

register

Syntax: register SLOT

No declared flags; registers and starts an existing slot, with machine-service coordination.

stop

Syntax: stop SLOT

No declared flags; requests shutdown, leaving registration. Not data deletion or rollback of completed effects.

unregister

Syntax: unregister SLOT

No declared flags; stops/removes startup registration, retains slot data, asks machine service to release references; last-slot handling may retire machine registration.

uninstall

Syntax: uninstall

-plan reports without executing; -yes bypasses confirmation; -json selects report format. Account-wide/destructive: stops/unregisters identities and machine service and removes account plugin stores/service directory; identity slots/keys/records remain. Program removal is separate. Exit 3 means partial completion, not nothing happened.

machine

Syntax: machine

-dir DIRECTORY runs a development machine service there; without it runs the account service. Desktop targets only (Linux, macOS, Windows). Shared across identities in the account.

machine register

Syntax: machine register

No declared flags; registers the installed program, or named build when no installed program, as account machine service.

machine store

Syntax: machine store DIRECTORY SLOT / machine store -list

-list only lists store paths; move form authenticates through the slot key and changes account plugin-store placement. Material copies by digest as needed and old stores drain; destination must support hard links. Not a private per-identity move.

verify

Syntax: verify

-ledger FILE required; repeatable -cross OTHER_LEDGER checks citations against supplied copies. Offline chain/signature verification, not truth verification or proof all citations were checked. Exit 0 verified/all matched; 1 failure/mismatch; 3 some unchecked citations.

plugin verify

Syntax: plugin verify [flags] BUNDLE

-certifier-key FILE, -reviewer-key FILE, -platform-key FILE, -trust-dir DIRECTORY supply pinned public roots/revocation status for tier verification offline. Verification neither installs nor grants capabilities.

plugin catalog

Syntax: plugin catalog [flags] [search QUERY]

-platform-key FILE, -catalog-dir DIRECTORY verify/browse a local signed catalogue, optionally searching. It is not an install command; availability for this host is reported separately.

dashboard-token

Syntax: dashboard-token

-dir DIRECTORY, -config FILE, -rotate. Without rotation prints existing secret access token; do not capture/share stdout. Rotation persists a fresh token; next configuration reload applies it and browsers must sign in again.

dashboard-port

Syntax: dashboard-port PORT

-dir DIRECTORY, -config FILE; saves port for next identity start and changes browser address. Relative config joins the named directory.

log

Syntax: log

Flags -dir DIRECTORY, -config FILE precede the log verb. A bare command shows logging.

• level [LEVEL] [CATEGORY=LEVEL…] (at least one setting) writes overlay levels (trace, debug, info, warn, error).
• details enumerates diagnostic details; groups lists derived/defined groups.
• tap [CATEGORY [on|off|clear]] controls captures; tap CATEGORY clear removes its overlay.
• log clear removes the whole overlay, not log history.
• Only tap CATEGORY on --for DURATION (also --for=DURATION) adds expiry. Omit duration and capture can continue without expiry.

Before capture: Raw payload taps can record private content. Stopping a tap does not cancel an in-flight capture.

memory-score

Syntax: memory-score

-db FILE, -fixtures FILE, -k N, -policies LIST, -eval DIRECTORY, -basis FILE, -origins. DB mode opens read-only, scores word/fuzzy retrieval without reinforcing or consulting a provider; origins mode counts origin support. Eval mode uses frozen corpus/optional recorded vectors in a throwaway store, only the first listed policy; threshold failure exits 3. Read-only still means reading potentially private data.

snapshot open

Syntax: snapshot open

-dir DIRECTORY, -key FILE, -in FILE, -out DIRECTORY: decrypt/unpack/check snapshot files into a new directory; this is not restoring a live identity.

escrow

Syntax: escrow create, escrow check, escrow restore

Shared recognized flags: -dir DIRECTORY, -key FILE (identity key), -snapshot-key FILE, -in FILE, -out FILE, -ledger FILE, -fingerprint HEX. Passphrase comes from the terminal, not an invented flag. These are sensitive operator operations, not routine diagnostic shortcuts.

escrow create

aii escrow create needs output (-out FILE). It exports recovery material. Protect the resulting file and passphrase; do not capture them in chat or diagnostics.

escrow check

aii escrow check needs input (-in FILE) and exactly one identity check (-ledger FILE or -fingerprint HEX). A check can record escrow-check state; it is not simply inert file inspection.

escrow restore

aii escrow restore needs input (-in FILE) and exactly one identity check (-ledger FILE or -fingerprint HEX). Restore can write key material. Do not confuse it with a non-restoring snapshot integrity check.

For backup, key recovery, snapshot opening and update workflows, prerequisites and cautions, use Operations; the rows above describe command surfaces, not replacement procedures. There is no dispatched backup, restore, update, config, chat, send, note or commit verb.

Internal dispatched commands, not ordinary operator workflows

plugin-worker MODULE.wasm: -memory-max BYTES, -invoke-timeout DURATION, -forward, -module-sha256 DIGEST, -describe, -descriptor-proof VALUE, -startup-timeout DURATION. Runs supervised plugin code/protocol. Memory ceiling, deadlines, forwarding and descriptor/digest checks are host/packager concerns; -describe still instantiates guest code, not inert file reading. Do not invoke it as an operator shortcut to grants.

_hardware-vulkan: no declared flags; internal Windows hardware helper; other-platform handler refuses. This is distinct from a general diagnostics CLI.

Identity organs such as recall, note, commit, work, send, tool discovery and backup take/verify are model-facing host operations, not aii subcommands. Their availability does not grant the operator CLI matching verbs or the identity permission to run key/account-maintenance commands. Other standalone binaries in source are outside this dispatch inventory.

Back to section overview · Documentation home