CLI reference
The reeg command drives the whole loop from a terminal: create an environment, run work in it, snapshot it, restore it, share it, and prove what it did.
Every important thing in computing became portable (files, code, containers, data) but not environments. Reeg is the layer over the sandbox: you run the work, Reeg versions and proves what it did. The CLI is how you operate that layer by hand or from a script.
Install
There is no npm package. The CLI is built from the monorepo and exposes one binary, reeg.
pnpm install
pnpm --filter @reeg/cli build # produces packages/cli/dist/index.js (bin: reeg)
# or run it straight from source during development:
pnpm --filter @reeg/cli dev -- <command> [args]
The snapshot and restore verbs also need the local engine, reeg-engine. Build it and point REEG_ENGINE at the binary:
cargo build --manifest-path engine/Cargo.toml
export REEG_ENGINE=/path/to/reeg-engine
Quick start
export REEG_PACKAGE_ID=0x8f2faf0b89e248f498cb0bc4b0ef98511613c4d7884e8ce41f0bc255246ca1d2 # testnet
export REEG_OPERATOR=0xyour_sui_address
reeg create
reeg run <machineId> -- python train.py
reeg checkpoint <machineId>
reeg verify <machineId>
create, checkpoint, restore, fork, retire, grant, revoke, and enclave register sign transactions, so they require both REEG_PACKAGE_ID and REEG_OPERATOR (or the matching --package / --operator flags). run is purely local; verify, evidence, and audit read only public data and need just a package id.
Commands
| Verb | What it does | Touches chain |
|---|---|---|
create | Mint a new environment you own, with a shareable access policy | yes |
run | Run a command inside an environment, appending to its command log | no |
checkpoint | Pack, encrypt, store on Walrus, anchor on Sui | yes |
restore | Read the latest checkpoint, decrypt, unpack into a workdir | yes |
fork | Create a child with provable lineage to the parent | yes |
retire | Append a permanent end-of-life marker | yes |
grant | Let another address decrypt and restore | yes |
revoke | Stop an address from unlocking future restores | yes |
verify | Confirm provenance from public Sui data, backend offline | read-only |
evidence | Export a portable evidence file for an auditor | read-only |
audit | Verify an exported evidence file, offline or anchored | read-only |
enclave register | Register a measured Nitro enclave on chain | yes |
create
reeg create
Mints a new environment under your operator address with a shared access policy, then records its local working directory. Prints the environment id, the policy id, the local workdir, and the tx digest.
run
reeg run <machineId> -- <command...>
Runs a command in the environment's working directory and appends it to the command log. Local only: no signer or chain access. Put -- before your command so the CLI passes its own flags through untouched. Exposes a memory directory (REEG_MEMORY_DIR) that the next checkpoint captures. The command's own exit code is surfaced as the CLI's exit code.
checkpoint
reeg checkpoint <machineId> [--epochs <n>] [--threshold <t>] \
[--attest --enclave-config <id>] [--enclave-cid <n>] [--enclave-port <n>]
Packs the working directory, encrypts it, stores it on Walrus, and anchors the blob and manifest hash on Sui in one transaction.
| Flag | Default | Meaning |
|---|---|---|
--epochs <n> | 1 | Walrus storage epochs to keep the snapshot paid for. Roughly 2 weeks per epoch on testnet. EU AI Act Art. 12 wants ~6 months (--epochs 13). |
--threshold <t> | configured (1 on testnet) | Seal committee threshold (t-of-n key servers). Fixed at encryption time; a later grant cannot change it. Validated against the configured key-server set. |
--attest | off | After anchoring, record a Nautilus enclave attestation of this checkpoint. Additive: a run without it is identical. |
--enclave-config <id> | REEG_ENCLAVE_CONFIG | The EnclaveConfig id from reeg enclave register. Required with --attest. |
--enclave-cid <n> | 16 | Enclave vsock CID. |
--enclave-port <n> | 5005 | Enclave vsock port. |
Prints the manifest hash, optional memory pointer, Walrus blob id, byte size, tx digest, the retention window, the cost line, and the t-of-n decryption requirement. A disaster-recovery backup key is produced in memory and never logged. A retired environment declines further checkpoints.
Typical cost per create plus an encrypted checkpoint (1 epoch): ~0.0099 SUI + ~0.0119 WAL.
restore
reeg restore <machineId> [--dest <dir>]
Reads the latest checkpoint from Walrus, decrypts it through a Seal session the caller authorizes, and unpacks it into a working directory. The owner restores into the machine's workdir; a grantee who never created the machine locally passes --dest. Prints the destination, manifest hash, workdir root hash, and memory pointer.
The decrypted plaintext is staged in an owner-only temp dir (mode 0700, file 0600, O_EXCL) and deleted afterward. Seal reads can briefly lag a just-changed policy, so a legitimate restore retries; a definitive access denial fails fast.
fork
reeg fork <machineId>
Creates a child that records provable lineage to the parent. The child starts with an empty workdir; restore the parent's state into it when needed. Prints the child id, its (empty) workdir, and the tx digest.
retire
reeg retire <machineId>
Appends a permanent, verifiable end-of-life marker to the provenance chain. The record stays on chain and verifiable offline; you may then stop paying for the run's Walrus storage once your retention window elapses. The client declines further checkpoints on a retired environment.
grant
reeg grant <machineId> <grantee> [--role viewer|restore] [--until <when>]
Lets another address decrypt and restore the environment. <grantee> is a 0x... address.
--role:viewerorrestore(defaultrestore). A typo'd role is rejected at parse time.--until: an expiry, as an ISO 8601 time or a short duration (7d,24h,30m,45s). Absent means no expiry.
The policy id is read from the Machine on chain, so grant works without local state.
revoke
reeg revoke <machineId> <grantee>
Stops an address from unlocking future restores. Note the honest limit it prints: revocation stops new key fetches, but every snapshot of a Machine shares one key, so anyone who already fetched it keeps access to past and future snapshots.
verify
reeg verify <machineId> [-n <network>] [--rpc <url>] [--package <id>]
Confirms a Machine's provenance from public Sui data, with the Reeg backend offline: it reads only Sui. Prints Verified or NOT verified, then one ok/FAIL line per check. Exits non-zero if any check fails.
evidence
reeg evidence <machineId> [--out <file>] [-n <network>] [--rpc <url>] [--package <id>]
Exports a portable evidence file an auditor can keep and verify offline. Read-only, no signer. --out sets the output path (defaults to ./evidence-<id>.json). Prints the machine id, checkpoint count, provenance head, and the two audit commands to run.
audit
reeg audit <file> [--anchor] [-n <network>] [--rpc <url>] [--package <id>]
Verifies an exported evidence file. Offline by default: it replays the file to its own recorded head, proving internal consistency. --anchor additionally confirms the file matches the live on-chain Machine, the real authenticity check. Prints one ok/FAIL line per check and exits non-zero on failure.
enclave register
reeg enclave register [--cid <n>] [--port <n>]
The optional Nautilus tier: "prove which code ran." Fetches the local Nitro enclave's attestation document over vsock, verifies it on chain via 0x2::nitro_attestation, and pins its PCRs and ed25519 key into a shared EnclaveConfig. Run once per enclave build. Defaults: --cid 16, --port 5005. Prints the new EnclaveConfig id and the exact reeg checkpoint --attest line to use it.
Environment variables
Flags win over env vars, which win over verified testnet defaults.
| Variable | Used by | Meaning |
|---|---|---|
REEG_PACKAGE_ID | all on-chain verbs | Reeg Move package id. Required for on-chain verbs (or --package). |
REEG_OPERATOR | signing verbs | Sui address that signs. Required for signing verbs (or --operator). |
REEG_NETWORK | all | mainnet, testnet, devnet, or localnet. Default testnet. |
REEG_RPC_URL | chain reads/writes | Override the Sui RPC URL (default is the network's public fullnode). |
REEG_ENGINE | run, checkpoint, restore | Path to the reeg-engine binary. Default reeg-engine on PATH. |
REEG_HOME | local state | Root for local state and workdirs. Default ~/.reeg. |
SUI_KEYSTORE | signing verbs | Path to the Sui keystore. Default ~/.sui/sui_config/sui.keystore. The key is loaded in memory only and never logged. |
REEG_SEAL_KEY_SERVERS | encryption | Comma-separated Seal key-server object ids. |
REEG_SEAL_THRESHOLD | encryption | Default committee threshold. Default 1. |
REEG_WALRUS_UPLOAD_RELAY | checkpoint | Walrus upload-relay host. |
REEG_DEBUG | all | 1 prints full stack traces instead of one clean error line. |
The mainnet package id is 0xfaa6b4af63a639c06e5d02c969c28111db5f01caea1067132c789fa7ebdb241e; testnet is 0x8f2faf0b89e248f498cb0bc4b0ef98511613c4d7884e8ce41f0bc255246ca1d2.
What works where
On mainnet today, encryption, Walrus storage, on-chain anchoring, and offline verification all work: create, checkpoint, verify, evidence, and audit run against live mainnet. The restore decrypt of an encrypted checkpoint currently waits on a provider Seal key server. The full encrypted checkpoint → restore → verify loop is proven end to end on testnet.