Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Quick Start

Get from zero to running your first spell in under 5 minutes.

1. Install and Set Up

Terminal
npm i -g @grimoirelabs/cli
grimoire setup

The setup wizard configures your chain, RPC endpoint, and wallet. Use --non-interactive --chain <id> --rpc-url <url> for CI environments.

2. Run a Known Spell

Grimoire ships with example spells. Start with a compute-only spell that doesn't move any funds:

Terminal
grimoire validate spells/compute-only.spell
grimoire simulate spells/compute-only.spell --chain 1

validate checks the spell compiles correctly. simulate runs a full preview against live chain data.

3. Check the Results

After simulation, review what happened:

Terminal
grimoire history

history shows all past runs with run IDs. Use grimoire log <spell-file> <runId> to view the detailed event ledger for a specific run.

4. Try a Spell with Actions

When you're ready to try a spell that interacts with a protocol:

Terminal
# Validate first
grimoire validate spells/uniswap-swap-execute.spell
 
# Dry-run: preview + sign, but don't submit onchain
grimoire cast spells/uniswap-swap-execute.spell \
  --dry-run \
  --key-env PRIVATE_KEY \
  --rpc-url YOUR_RPC_URL

The --dry-run flag runs the full preview and signing pipeline without actually submitting the transaction. This is the safest way to test before going live.

5. Execute Live

When you're confident in the preview results:

Terminal
grimoire cast spells/uniswap-swap-execute.spell \
  --key-env PRIVATE_KEY \
  --rpc-url YOUR_RPC_URL

Without --dry-run, this runs preview and then commits the actions onchain.

Safe Execution Path

Always follow this progression:

validate → simulate → cast --dry-run → cast
  1. validate — check syntax and structure
  2. simulate — preview against live data (no wallet needed)
  3. cast --dry-run — full pipeline including signing (no submission)
  4. cast — preview + commit (live execution)

Next Steps