CLI Reference (dregg)

The dregg command-line tool is a full-citizen interface to the runtime. Every operation available through the SDK or browser extension is also available via the CLI. It is the primary tool for operators, developers, and power users.

Installation

# From source (requires Rust 1.79+)
cargo install --path cli/

# Or from a release binary
curl -sSf https://dregg.io/install.sh | sh

# Verify installation
dregg --version

Subcommands Overview

Cipherclerk Management

# Create a new identity (generates 24-word mnemonic)
dregg cclerk create --mnemonic
# Output: writes mnemonic to stdout, saves encrypted key to ~/.dregg/keys/

# Restore from mnemonic
dregg cclerk restore --mnemonic "word1 word2 ... word24"

# Check balance
dregg cclerk balance
# Output: 45000 computrons (available), 5000 (locked in deposits)

# Export public key
dregg cclerk pubkey
# Output: ed25519:a1b2c3d4...

Cell Operations

# Create a sovereign cell (federation stores only your 32-byte commitment)
dregg cell create --sovereign --federation devnet.dregg.io:8420

# Create a hosted cell (federation stores full state)
dregg cell create --hosted --federation devnet.dregg.io:8420

# Inspect a cell
dregg cell inspect $CELL_ID
# Output: state slots, c-list entries, sovereignty mode, last turn, balance

# Migrate (teleport) to another federation
dregg cell migrate --cell $CELL_ID --to other-fed.io:8420

# Split a cell into children
dregg cell split --cell $CELL_ID --partitions 3

# Merge children back
dregg cell merge --cells $CHILD1,$CHILD2,$CHILD3

Capability Operations

# Mint a root capability token
dregg cap mint --service my-service --root-key ./keys/root.key

# Attenuate (restrict) a token
dregg cap attenuate --token $TOKEN_ID \
  --restrict service=my-service,action=read \
  --ttl 1h --budget 500

# Delegate to another agent
dregg cap delegate --token $TOKEN_ID --to $BOB_PUBKEY \
  --restrict action=read --ttl 24h

# Revoke a delegation
dregg cap revoke --token $TOKEN_ID --delegation $DELEG_HASH

# Generate a ZK presentation proof
dregg cap present --token $TOKEN_ID --request '{"service":"dns","action":"read"}' \
  --mode private

# Verify a received proof
dregg cap verify --proof ./proof.bin --federation-root $ROOT_HEX

Turn Operations

# Build and submit a turn
dregg turn build --target $CELL_ID --effect set-field:counter=42
dregg turn submit --signed

# Verify receipt chain integrity
dregg turn verify-chain --cell $CELL_ID

# Inspect a specific receipt
dregg turn receipt --hash $TURN_HASH
# Output: pre_state, post_state, effects, computron_cost, timestamp

# Export IVC-compressed state proof
dregg turn export-ivc --cell $CELL_ID --output ./state-proof.bin

Federation Operations

# Check federation status
dregg federation status
# Output: connected peers, current epoch, attested root, block height

# Join a federation
dregg federation join --url devnet.dregg.io:8420 --stake 100000

# Leave a federation (keeps your IVC proof)
dregg federation leave

# List peers
dregg federation peers
# Output: node_id, address, last_seen, blocks_produced

Namespace and Service Mesh

# Mount a service at a namespace path
dregg namespace mount --path /services/inference --descriptor ./service.json

# Resolve a service path
dregg namespace resolve /services/inference
# Output: cell_id, descriptor, ACL policy

# List services under a prefix
dregg namespace list /services/

# Register a petname (local alias)
dregg directory petname set bob ed25519:a1b2c3d4...
dregg directory petname get bob
# Output: ed25519:a1b2c3d4...

# Manage name rental
dregg namespace rent --path /public/myname --epochs 12
dregg namespace status --path /public/myname

Storage Operations

# Check storage quota and usage
dregg storage status
# Output: used 45 KiB / 10 MiB quota, rent: 45 computrons/epoch

# Check space bank allocation
dregg storage bank
# Output: bank_id, total allocation, used, available

# Enable erasure coding for a cell
dregg storage erasure enable --cell $CELL_ID --shards 7 --threshold 4

# Check erasure shard health
dregg storage erasure status --cell $CELL_ID

# Inspect inbox (MerkleQueue)
dregg storage inbox
# Output: 3 pending messages, total deposit held: 1500 computrons

Proof Operations

# Generate a proof using a specific backend
dregg proof generate --backend plonky3 --turn $TURN_HASH
dregg proof generate --backend kimchi --turn $TURN_HASH

# Compose multiple proofs
dregg proof compose --mode chain --inputs proof1.bin,proof2.bin,proof3.bin

# Wrap for Mina (STARK-in-Pickles)
dregg proof wrap-pickles --input $STARK_PROOF --output mina-proof.bin

# Wrap for EVM (SP1 Groth16)
dregg proof wrap-sp1 --input $STARK_PROOF --output evm-proof.bin

# Benchmark a proof backend
dregg proof bench --backend plonky3 --circuit effect-vm --turns 100

Route Classification

# Test a path against the DFA classifier
dregg route classify /services/inference/gpt4
# Output: ACCEPT (policy: compute-tier-1, ACL: [cell_id_1, cell_id_2])

# Inspect the DFA state machine
dregg route inspect --states
# Output: 47 states, 312 transitions, 23 accept states

# Propose a constitutional amendment (new route)
dregg route propose --add /services/new-category --acl open
# Output: proposal_id (requires h-rule acceptance)

Diagnostics

# Full health check
dregg doctor --full
# Checks: node connectivity, chain integrity, peer count,
#          disk usage, proof generation, key accessibility

# Quick connectivity test
dregg doctor --connectivity

# Verify your receipt chain from genesis
dregg doctor --verify-chain

Configuration

The CLI reads configuration from ~/.dregg/config.toml:

[federation]
default = "devnet.dregg.io:8420"

[cclerk]
keyfile = "~/.dregg/keys/default.key"

[proof]
default_backend = "plonky3"

[storage]
data_dir = "~/.dregg/data"

All settings can be overridden with environment variables (DREGG_FEDERATION_DEFAULT, etc.) or command-line flags.

Next Steps

• Quickstart -- Set up your first identity
• Node Setup -- Run your own federation node
• SDK Quickstart -- Integrate programmatically