Command line
Every command in the MoxiVue command line
MoxiVue does from the terminal everything it does from the window. Every command prints machine-readable JSON and ends with a documented exit code, so scripts and automation get the same surface a person does.
This page is complete and authoritative. It lists every command this version of MoxiVue exposes, taken straight from moxivue help --json on the machine itself. Run that command to see the same list, with exit codes, for the version you have installed.
How these commands work
One program, moxivue, runs on the computer you work at (the console) and on each machine (the agent). The window and the command line send the same requests, so anything you can do in one you can do in the other. Packet capture stays in the window.
- JSON for scripts. Add
--jsonto a command to get its answer as JSON. Almost every command supports it; the few that do not, an interactive sign-in or an SSH session, pass through the underlying tool instead. - Exit codes. Every command ends with one of the codes below. A command refuses an option it does not know with exit 2 and does nothing, so a typo never changes your account by accident.
- Safe to re-run. A command that asks for a change and finds it already made reports that and ends 0, so a script can run again without harm.
- Skipping the prompt, not the proof. --yes skips a prompt only: it never replaces typed words, a typed number, the console unlock, or the audit entry.
- Root on the machine. A few commands run on the machine itself as root, shown with root and
sudo: enrolling the machine, its services, and the machine's own switches. Everything else runs as you on the console. - Unattended joins. An owner or admin issues short-lived install tokens with
moxivue token issueand--automationinvitations, so a script, a cron job or CI gets its own narrowly scoped device and never a person's keys.
Exit codes
Every command ends with one of these. Each table's Exit column lists the codes that command can end with.
| Code | What it means |
|---|---|
| 0 | done (also: it was already so) |
| 1 | refused or failed (the message says which rule or what failed) |
| 2 | usage: the command was not given what it needs; nothing was done |
| 3 | waiting: for a second device's confirmation or the other side of a run; run it again later |
| 4 | mismatch: the code, words, number or paper did not match; nothing was done |
| 5 | not fresh: no fresh witnessed account state; nothing was done; try again |
| 6 | console locked: unlock it with this computer's password (moxivue unlock); --yes does not replace it |
| 7 | limit: the account's 10 machines |
This computer and the console lock
See this computer's state, and lock or unlock the console.
| Command | What it does | Exit |
|---|---|---|
moxivue help [--json] | every command; with --json every 5.0 command and its exit codes | 0 |
moxivue status [--more|--all] [--json] | this computer at a glance, with this user's console identities and the machine identity apart | 0 1 |
moxivue overview [--json] | this user's 5.0 accounts: role, set-up state in words, machines n of the account's limit, what waits for a confirmation, alarms and recovery notices | 0 1 |
moxivue lock [--json] | lock the console now | 0 1 2 |
moxivue unlock [--json] | unlock the console for 15 minutes with this computer's password (asked on the terminal; time asleep counts; it locks with the screen) | 0 1 2 |
moxivue lock --status [--json] | whether the console is locked, and for how long it stays unlocked | 0 1 2 |
Signing in
A sign-in only says who a person is. It never grants a key or a role.
| Command | What it does | Exit |
|---|---|---|
moxivue login --email A | --microsoft | --github | --apple | --oidc | sign in (a sign-in identifies a person; it never gives a key or a role) | 0 1 2 |
moxivue signin oidc add|remove|require on|off|list [--json] | owners: the account's company sign-in (OpenID Connect) | 0 1 2 3 |
Accounts and consoles
Make an account, invite another console, join one, and confirm a join from a second device.
| Command | What it does | Exit |
|---|---|---|
moxivue account create --name N [--person P] [--json] | a new account with this console as its first owner, for the person signed in with moxivue login; the recovery paper is shown once | 0 1 2 5 |
moxivue invite [--role R] [--site S [--group G]] [--person new|mine] [--automation] [--account A] [--json] | an 8-digit code for a new console (role up to your own; owner and auditor only by an owner) | 0 1 2 5 6 |
moxivue invite status <run> [--json] | where an invitation stands | 0 1 2 3 |
moxivue invite words <run> "<w1 w2 w3>" [--json] | the three words the new console shows, typed here; proposes the join for a second device's confirmation | 1 2 3 4 5 6 |
moxivue join <code> [--account A] [--no-wait] [--json] | join with the code from the inviting console; shows three words to type there | 0 1 2 3 4 5 |
moxivue join --status [--json] | where this console's join stands | 0 1 2 3 |
moxivue confirm [--json] | what waits for this console's confirmation, with the words recomputed and who proposed it | 0 1 |
moxivue confirm <id> [--json] | confirm it, after comparing the words with the new console's screen in person or by voice | 0 1 2 5 6 |
moxivue confirm refuse <id> [--json] | refuse it | 0 1 2 5 |
moxivue person move <device> <person> [--json] | a console moved to another person: a second owner or admin device confirms | 0 1 2 3 5 6 |
moxivue leave [--account A] [--json] | this console leaves the account | 0 1 2 5 6 |
moxivue account delete [--account A] [--json] | an owner: the account's signed deletion, confirmed by a second device; then the Dispatcher deletes its data; not reversible | 0 1 2 3 4 5 6 |
Adding machines
Add a machine from the console, then finish the join on the machine as root, or join many machines with install tokens.
| Command | What it does | Exit |
|---|---|---|
moxivue machine add [--site S [--group G]] [--account A] [--json] | a rendezvous to type on the new machine (sudo moxivue machine join <rendezvous>) | 0 1 2 5 7 |
moxivue machine accept <rendezvous> --number N [--no-wait] [--json] | the number the machine shows, typed here; then three words shown here to type on the machine | 0 1 2 3 4 5 6 7 |
moxivue machine status <rendezvous> [--json] | where a machine's join stands | 0 1 2 3 |
sudo moxivue machine identity [--json] root | on the machine, as root: whether each machine identity seals, is rotating (a restored disk), is a cloned image to join as a new machine, or must be enrolled again | 0 1 2 |
sudo moxivue machine join <rendezvous> root | on the machine, as root: root's consent, the number to type on the console, then the console's three words typed here | 0 1 2 4 5 |
sudo moxivue machine join --token --fingerprint F root | on the machine, as root: join with an install token (read from the terminal) and the full account fingerprint | 0 1 2 4 5 |
moxivue token issue --count N [--site S [--group G]] --hours H [--json] | install tokens for scripted machine joins: machines only, 1 to 24 hours, one machine each, not in set-up; shown once | 0 1 2 5 7 |
moxivue token revoke <id> [--json] | revoke an install token | 0 1 2 5 |
moxivue token list [--json] | install tokens: open, used, revoked, expired | 0 1 |
Sites, groups, devices and names
Organise the account into sites and groups, place and name devices, and read the account's names.
| Command | What it does | Exit |
|---|---|---|
moxivue site add <name> [--json] | a new site of the account with its name, sealed in its entry (owners and admins of the whole account; the same command again changes nothing); renamed with moxivue names set | 0 1 2 5 |
moxivue group add <site> <name> [--json] | a new group in a site with its name (owners and admins covering the site); renamed with moxivue names set | 0 1 2 5 |
moxivue device list [--account A] [--json] | places, persons and devices of the account, with their numbers | 0 1 2 |
moxivue device role <device> <role> | device place <device> [--site S [--group G]] | device remove <device> [--json] | a console's role, its reach or a machine's place, or removing a device: a second owner or admin device confirms | 0 1 2 3 5 6 |
moxivue names [show] [--file F] [--json] | the names of the account, its places, persons and devices (sealed: ids where this console reads none) | 0 1 2 |
moxivue names set NAME [--site S [--group G]] [--json] | rename the account, a site or a group (owners and admins covering it) | 0 1 2 5 |
moxivue names person <person> NAME [--json] | name a person (owners and admins of the whole account) | 0 1 2 5 |
moxivue names device <device> NAME [--json] | name a device (owners and admins covering its place) | 0 1 2 5 |
moxivue names reseal [--json] | re-seal names documents that a machine or a console cannot open yet (also again: nothing new) | 0 1 2 5 |
moxivue names keys --out F [--json] | write the keys of the names documents this console opens, for verify-audit5.py --names | 0 1 2 |
Roles, settings and access control
Show and change settings, allow SSH to machines, grant place history, and manage auditor consoles.
| Command | What it does | Exit |
|---|---|---|
moxivue settings [show] [SCOPE] [--file F] [--json] | the settings of the account, a site, a group or a machine | 0 1 2 |
moxivue settings set NAME=VALUE ... [SCOPE] [--json] | a new version of a scope's settings (a sensitive one waits for a confirmation) | 0 1 2 3 5 6 |
moxivue ssh-host on|off [--site S [--group G] | --machine M] [--json] | allow SSH to machines (owners; on needs a confirmation) | 0 1 2 3 5 6 |
moxivue history grant <person> --yes [--json] | give a person's consoles the place history (owners; a second device confirms) | 0 1 2 3 5 6 |
moxivue auditor add [--site S [--group G]] | invite an auditor console (an owner; a second device confirms) | 0 1 2 3 6 |
moxivue auditor remove <device> | propose removing an auditor console (a second device confirms) | 0 1 2 3 6 |
moxivue auditor list [--json] | the account's auditor consoles | 0 1 |
moxivue fingerprint [--json] | the full account fingerprint of each account of this user (for install-token joins) | 0 1 |
moxivue keys [--file F] [--json] | generations and readers periods (read only) | 0 1 2 |
Recovery paper
Recover an account from its recovery paper, and replace the paper.
| Command | What it does | Exit |
|---|---|---|
moxivue recovery start --account A [--keep D,D] [--json] | on a new console: a recovery request from the recovery paper (read from the terminal) | 1 2 3 5 6 |
moxivue recovery status [--json] | recovery requests of this user's accounts, with when they can complete | 0 1 |
moxivue recovery cancel <id> [--json] | cancel a recovery request: lodged with both witnesses | 0 1 2 5 6 |
moxivue recovery complete <id> [--words W] [--json] | complete a request after its waiting time; the new paper is shown on a separate new console | 0 1 2 3 4 5 6 |
moxivue recovery replace [--run R --words W [--holder P]] [--json] | replace the recovery paper: the new paper is shown on a separate new console; a second device confirms | 0 1 2 3 4 5 6 |
moxivue recovery paper <code> [--account A] [--json] | on a separate new console: shows the new recovery paper once, and three words to type on the other console | 0 1 2 3 |
Reaching a machine
List machines, read a machine's live data, choose the path, and wake a machine.
| Command | What it does | Exit |
|---|---|---|
moxivue machines [--json] | the machines of this user's accounts: number, place, when the newest signed status is dated | 0 1 |
moxivue view <machine> [<read route>] [--json] | one read of a machine's live data (its info by default), checked by the machine and recorded there (owner, admin, operator; never an auditor) | 0 1 2 |
moxivue views [--json] | what of the account is connected to this computer now (views, terminals, forwards, SSH) | 0 |
moxivue path [auto|direct|dispatcher] [--json] | how this computer reaches machines, and each machine's path | 0 1 2 |
moxivue path test <device> [--json] | open a direct link to a machine now and show its key exchange | 0 1 2 |
moxivue wake <machine> <mac> | the machine sends a Wake-on-LAN packet on its network | 0 1 2 6 |
Terminals, SSH and port forwards
Open a recorded terminal, forward a port, and reach devices by SSH through a machine.
| Command | What it does | Exit |
|---|---|---|
moxivue terminal <machine> [--account A] [-- command] | a terminal on a machine (its number), through its root executor's session.start; recorded where the account records | 0 1 2 6 |
moxivue ask [--json] | ask allow|deny <id> [--json] | sessions waiting at this computer for its person's approval (ask each time); only a person at it answers | 0 1 2 |
sudo moxivue machine ask [on|off terminal|forward|all] [--json] root | root's own switch on the machine: also ask the person at it before a terminal, forward or SSH session (it only adds the question) | 0 1 2 |
moxivue fwd <machine> <local>:<remote> | fwd list | fwd remove <local> | forward a local port to a port of the machine | 0 1 2 6 |
moxivue fwd <machine> <local>:<host>:<port> | forward a local port to a device behind the machine (on a network it is directly connected to; the machine checks it) | 0 1 2 6 |
moxivue fwd-stdio <machine> <host>:<port> | one connection to a device behind the machine over standard input and output (ssh's ProxyCommand) | 0 1 2 6 |
moxivue ssh list [--site S] [--json] | the account's SSH list: devices behind its machines and their pinned host keys | 0 1 |
moxivue ssh add <name> <address> --via <machine> [--port P] [--user U] [--site S] [--json] | add a device behind a machine to the account's SSH list (owner or admin; a signed settings change) | 0 1 2 3 5 |
moxivue ssh remove <name> [--site S] [--json] | take a device off the account's SSH list (a signed settings change) | 0 1 2 3 5 |
moxivue ssh accept <name> [--replace] [--site S] [--json] | fetch a listed device's host keys through its machine (no login) and pin them; other keys later need --replace | 0 1 2 3 5 6 |
moxivue ssh <name> [-- command] | an SSH session to a listed device behind a machine, its pinned host keys only | 0 1 2 6 |
moxivue ssh <machine> [--user U] [--check] [--json] [-- command] | ssh over this console's channel into your own account on the machine (number or name), where ssh.host and users are on and the console holds a grant; --check only says which account; otherwise the exit code is ssh's | 0 1 2 6 |
moxivue ssh grant <machine> --to <console> --key K [--days N] [--unattended] | an owner grants a console's SSH key on one machine, at most 30 days | 0 1 2 5 6 |
Session recordings
Switch recording on or off, set how long recordings are kept, and play, export or re-seal them.
| Command | What it does | Exit |
|---|---|---|
moxivue recording off|on [--site S [--group G] | --machine M] [--json] | an owner switches session recording off or on (machines take it only from an owner's settings; on by default) | 0 1 2 5 |
moxivue recordings keep [<30-400>] [--json] | how long the Dispatcher keeps this account's recordings (90 days unless an owner set 30 to 400; shortening waits for a confirmation) | 0 1 2 3 5 |
moxivue recordings [--account A] [--json] | the stored session recordings this console may read (owner, admin, auditor) | 0 1 |
moxivue recording play <session> [--json] | a recording, opened and checked chunk by chunk (asciicast v2) | 0 1 2 |
moxivue recording export <session> --dir D [--json] | a recording written to <D>/<session>.cast | 0 1 2 |
moxivue recording reseal <session> --to <device> [--json] | an owner's copy of a recording's key for a reader added later (RESEAL-1) | 0 1 2 6 |
The signed log and audit
Read and verify the account's signed log, and export or stream the audit trail.
| Command | What it does | Exit |
|---|---|---|
moxivue log [--file F] [--json] | the account log in words, verified from its genesis | 0 1 2 |
moxivue log verify [--file F] [--json] | verify the account log from its genesis; the first failing entry and its rule | 0 1 2 |
moxivue log fetch [--account A] [--out F] [--json] | the account's log as the Dispatcher holds it, verified from its genesis, into a file (what moxivue log, settings and verify-audit5.py read) | 0 1 2 |
moxivue witness status [--file F] [--json] | both witnesses: anchors, ages, last answers, freshness and alarms (0 fresh, 5 not fresh, 1 no state or a tamper alarm) | 0 1 2 5 |
moxivue audit export --dir D [--format jsonl|csv] [--recordings] [--json] | the audit trail this console can read, in a new folder anyone can check (log, sealed records, action records, lines, recordings, manifest); recorded first | 0 1 2 6 |
moxivue audit stream add syslog <host:port> [--ca F] | add otlp <url> [--headers F] | list | remove <id> | run | hand new audit lines to the owner's syslog (TLS) or OpenTelemetry collector; owner, admin or auditor | 0 1 2 6 |
moxivue recordings push s3 --endpoint URL --bucket B --credentials F [--region R] [--retain-days N] [--prefix P] | recordings not pushed yet to S3-compatible storage, write-once (Object Lock); each export recorded first | 0 1 2 6 |
moxivue export verify <folder> [--json] | export play <folder> <session> | check an audit export folder without keys, or play a recording from it | 0 1 2 |
Updates, services and housekeeping
Update or restart a machine, manage the machine's services, read notices, and clear 4.x files.
| Command | What it does | Exit |
|---|---|---|
moxivue update <machine> | restart <machine> [--json] | an owner's or admin's console asks the machine's root executor to update MoxiVue or restart the computer (restart is a kind root switches on); the executor's signed record comes back | 0 1 2 5 6 |
sudo moxivue service status [--json] | service enable|disable root | the machine agent, helper and root executor, and any 4.x unit left (0 all on, 1 not); disable keeps it off | 0 1 2 |
moxivue notices [--json] | joins, alarms and recovery notices of this user's consoles | 0 1 |
moxivue notices seen <id> [--json] | marks an alarm or alert seen for this console: every window stops showing it (a tamper alarm or recovery notice stays) | 0 1 2 |
moxivue legacy status|delete [--yes] [--json] | the 4.x files 5.0 never reads or changes: with sudo the machine's, without your own; delete asks first | 0 1 2 |