CLI Reference

Core commands for the Grimoire CLI.

Command Summary

Command	Description
`grimoire setup`	Configure chain and RPC settings
`grimoire compile`	Compile a spell to IR
`grimoire validate`	Compile + validate structural rules
`grimoire simulate`	Run full preview against live data
`grimoire cast`	Preview + commit (execute onchain)
`grimoire venues`	List registered venue adapters
`grimoire venue`	Fetch live data from a specific venue
`grimoire venue doctor`	Check adapter/RPC readiness
`grimoire history`	List past runs
`grimoire log`	Show event ledger for a run
`grimoire wallet`	Wallet management commands
`grimoire init`	Initialize .grimoire scaffolding
`grimoire setup`	Interactive execute-mode onboarding
`grimoire compile-all`	Compile all spells in a directory
`grimoire resume`	Resume a waiting cross-chain run

compile

Compile a spell file to its intermediate representation.

Terminal

grimoire compile <spell-file> [options]

Option	Description
`--pretty`	Pretty-print the IR output
`--output <path>`	Write IR to file instead of stdout

compile-all

Compile all .spell files in a directory.

Terminal

grimoire compile-all [dir] [options]

Option	Description
`--fail-fast`	Stop on first compilation error
`--json`	Output results as JSON

init

Initialize the .grimoire scaffolding for the current directory.

Terminal

grimoire init [options]

Option	Description
`--force`	Overwrite existing scaffolding
`--runtime-quickstart`	Include quickstart spell examples

validate

Compile and run structural validation on a spell.

Terminal

grimoire validate <spell-file> [options]

Option	Description
`--strict`	Enable strict validation mode

simulate

Run a full preview without committing any actions.

Terminal

grimoire simulate <spell-file> [options]

Option	Description
`--chain <id>`	Target chain ID
`--rpc-url <url>`	RPC endpoint
`--params '<json>'`	Override spell parameters
`--advisory-replay <path>`	Replay advisory decisions from a prior run
`--destination-chain <id>`	Destination chain ID for cross-chain spells
`--destination-spell <path>`	Spell to hand off to on the destination chain
`--handoff-timeout-sec <n>`	Seconds to wait for cross-chain handoff

cast

Run preview and optionally commit actions onchain.

Terminal

grimoire cast <spell-file> [options]

Option	Description
`--dry-run`	Preview + sign only, do not submit
`--key-env <var>`	Environment variable containing private key
`--chain <id>`	Target chain ID
`--rpc-url <url>`	RPC endpoint
`--params '<json>'`	Override spell parameters
`--advisory-replay <path>`	Replay advisory decisions from a prior run
`--destination-chain <id>`	Destination chain ID for cross-chain spells
`--destination-spell <path>`	Spell to hand off to on the destination chain
`--handoff-timeout-sec <n>`	Seconds to wait for cross-chain handoff

venue

Fetch live data from a specific venue adapter.

Terminal

grimoire venue <adapter> <command> [options]

Option	Description
`--chain <id>`	Target chain ID
`--format <fmt>`	Output format: `json`, `table`, `spell`
`--rpc-url <url>`	RPC endpoint

venue doctor

Check that a venue adapter is properly configured:

Terminal

grimoire venue doctor --chain 1 --adapter uniswap --rpc-url <url> [--json]

history

List past spell runs.

Terminal

grimoire history [options]

Option	Description
`--limit <n>`	Number of runs to show
`--json`	Output as JSON

log

Show the event ledger for a specific run.

Terminal

grimoire log <spell-file> <runId> [options]

Option	Description
`--last`	Show the most recent run
`--run-id <id>`	Show a specific run
`--json`	Output as JSON

resume

Resume a cross-chain run that is waiting for its destination spell to complete.

Terminal

grimoire resume <runId> [options]

Option	Description
`--watch`	Poll until the run completes
`--json`	Output as JSON

wallet

Manage wallets for onchain execution.

Terminal

grimoire wallet <command> [options]

Command	Description
`generate`	Create a new wallet keystore
`import`	Import an existing private key
`address`	Show wallet address
`balance`	Check wallet balance
`wrap`	Wrap ETH to WETH
`unwrap`	Unwrap WETH to ETH

Common options:

Option	Description
`--key-env <var>`	Environment variable with private key
`--chain <id>`	Target chain ID
`--rpc-url <url>`	RPC endpoint
`--amount <n>`	Amount for wrap/unwrap
`--json`	Output as JSON

setup

Interactive onboarding wizard for execute mode — configures wallet, RPC, and runs readiness checks.

Terminal

grimoire setup [options]

Option	Description
`--chain <id>`	Target chain ID
`--rpc-url <url>`	RPC endpoint
`--adapter <name>`	Adapter for venue doctor check (default: `uniswap`)
`--keystore <path>`	Path to keystore file (default: `~/.grimoire/keystore.json`)
`--key-env <var>`	Environment variable containing private key to import
`--no-doctor`	Skip venue doctor checks
`--non-interactive`	Disable interactive prompts (for CI)
`--json`	Machine-readable output

Creates .grimoire/setup.env with configuration for subsequent commands.

RPC Resolution

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Validation/compilation failure
`3`	Preview rejected (constraint violation)
`4`	Commit rejected (drift/safety check)