CLI Reference

The modal command-line tool is your interface to Modality.

Installation

# First-contract onboarding wrapper
cd rust
cargo build --release -p modal --no-default-features --features contract-onboarding

# Language/model CLI used by the first-contract guide
cargo build --release -p modality

The lean onboarding wrapper exposes the contract and identity surfaces needed by the first-contract guide: modal contract, modal c, modal id, modal passfile, modal ai, modal status, modal pull, modal commit, modal diff, modal set, modal repost, modal add-rule, and modal download. It omits the runtime-heavy hub, node, network, predicate, program, chain, local, run, killall, and upgrade surfaces.

Build the full wrapper with cargo build --release -p modal when you need those broader command groups. Use modality for model and rule authoring tasks such as modality model lint, modality model synthesize, modality model validate, modality model mermaid, and modality model view.

Command Groups

Command	Alias	Description
modal contract	modal c	Contract management (create, commit, push, pull)
modal ai	—	AI provider configuration and modal ai suggest-rule
modal id	modal identity	Identity management (create, derive, get)
modal passfile	—	Passfile encryption/decryption
modal hub	—	Contract hub server and collaboration; full wrapper only
modal predicate	—	Predicate listing and testing; full wrapper only
modal program	—	Program management; full wrapper only
modal node	—	Network node operations; full wrapper only. With no subcommand, opens an action-picker TUI. Public testnet: join-testnet.md
modal net	modal network	Network information; full wrapper only
modal local	—	Local development utilities; full wrapper only
modal run	—	Quick node runners; full wrapper only
modal chain	—	Chain validation; full wrapper only
modal wallet	—	Hold, receive and send assets with one key; full wrapper only. See wallet-commands.md
modal release	—	Verify that a release is one the release contract accepts; publish releases (CI). Full wrapper only. See release-commands.md

Global Commands

# Show version
modal --version
modal -v

# Show help
modal --help
modal <command> --help

# Show status (in contract directory)
modal status

# Pull commits (shortcut for modal contract pull)
modal pull http://hub.example.com/contracts/my-contract

# Show uncommitted changes (shortcut for modal contract diff)
modal diff

# Repost a snapshot from another contract (then modal commit --all)
modal repost source-contract-id /source/path
modal repost source-contract-id /source/path /local/path

# Add a rule to the current contract
modal add-rule --name authorized \
  'always([-signed_by(/parties/alice.id) -signed_by(/parties/bob.id)] false)'

# Configure an AI provider, then suggest a rule formula
modal ai set --provider openai
modal ai suggest-rule "after this commit either alice or bob must sign"

# Download a packed contract file
modal download http://hub.example.com/contracts/my-contract.pack

# Kill all local nodes (full wrapper only)
modal killall

# Upgrade to latest version (full wrapper only)
modal upgrade

Quick Reference

# Identity
modal id create --name example/alice
modal id get --name example/alice

# Contract workflow
modal c create
modal c set-named-id /parties/alice.id example/alice
modal c commit --all --sign example/alice -m "Initial setup"
modal c status
modal c log

# Push/Pull
modal c push http://hub.example.com/contracts/my-contract
modal c pull http://hub.example.com/contracts/my-contract

# Predicates
modal predicate list
modal predicate info signed_by
modal predicate test signed_by --data '{"path":"/alice.id","signature":"..."}'

Shortcuts

Full Command	Shortcut
modal contract	modal c
modal contract status	modal status
modal contract pull	modal pull
modal contract commit	modal commit
modal contract diff	modal diff
modal contract set	modal set
modal contract repost	modal repost
modal contract add-rule	modal add-rule
modal contract download	modal download
modal identity	modal id
modal network	modal net
modal local killall-nodes	modal killall

Environment Variables

Variable	Description	Default
MODAL_NODE_PATH	Default node directory	./node
MODAL_NETWORK	Network (mainnet/testnet)	mainnet
MODAL_HUB_URL	Default hub URL	—
MODAL_PASSFILE	Default passfile path	—
MODAL_AI_API_KEY	API key for modal ai suggest-rule	—
OPENAI_API_KEY	OpenAI API key	—
ANTHROPIC_API_KEY	Anthropic API key	—
XAI_API_KEY	xAI / Grok API key	—
CURSOR_API_KEY	Cursor Agent API key	—
MODAL_AI_CURSOR_AGENT	Path to the Cursor agent CLI	agent or cursor-agent on PATH