Grimoire

Grimoire CLI Skill

This skill is the base operating playbook for Grimoire.

When To Use

Use this skill when the task includes:

• install/setup of Grimoire tooling
• creating or editing .spell files
• syntax questions about DSL capability
• advisory (advise) authoring, debugging, and replay workflows
• setup/compile/validate/simulate/cast/resume workflows
• debugging spell compile/runtime failures

Mandatory Loading Rules

All references/ and docs/ paths below are relative to this skill directory (skills/grimoire/). These rules are required — they solve syntax coverage gaps that cause authoring errors.

STOP — read this first: Do NOT search the codebase, grep for syntax patterns, or rely on memory for DSL syntax. The reference files bundled with this skill are the single source of truth. IMMEDIATELY use the Read tool on the files listed below before writing or editing any spell content.

1. For any .spell authoring/editing task — IMMEDIATELY read these files using the Read tool before doing anything else:

• references/syntax-capabilities.md
• references/authoring-workflow.md

2. For CLI flag details — IMMEDIATELY read using the Read tool:

• references/cli-quick-reference.md

3. For any advisory task (advise, advisors, replay) — IMMEDIATELY read using the Read tool:

• docs/how-to/use-advisory-decisions.md
• docs/explanation/advisory-decision-flow.md

4. For local fork preview workflows — IMMEDIATELY read using the Read tool:

• references/anvil-cheatsheet.md
• docs/how-to/simulate-on-anvil-fork.md

5. For wallet setup and execution key flows — IMMEDIATELY read using the Read tool:

• docs/how-to/use-wallet-commands-end-to-end.md

6. For RPC/signer/transaction diagnostics — IMMEDIATELY read using the Read tool:

• references/cast-cheatsheet.md

Installation Resolution

Select the first working invocation and reuse it for the session.

1. Global:

• npm i -g @grimoirelabs/cli
• command prefix: grimoire

2. No-install:

• command prefix: npx -y @grimoirelabs/cli

3. Repo-local:

• command prefix: bun run packages/cli/src/index.ts --

If one path fails, move to the next path automatically.

If grimoire venue doctor ... fails with Unknown venue adapter "doctor", prefer repo-local invocation (bun run packages/cli/src/index.ts) or upgrade global CLI.

When using repo-local Bun execution, always keep the trailing -- so Bun forwards flags to Grimoire instead of consuming them.

Fast Start (Immediate Success Path)

Use this sequence before writing custom spells:

1. <grimoire-cmd> --help 2. <grimoire-cmd> setup (guided interactive execute onboarding) 3. <grimoire-cmd> validate spells/compute-only.spell 4. <grimoire-cmd> simulate spells/compute-only.spell --chain 1

If all three pass, proceed to spell authoring.

Setup security/runtime expectations:

• setup prompts for hidden passwords and never echoes input
• blank RPC input falls back to chain default public RPC
• setup may write .grimoire/setup.env unless --no-save-password-env is used
• CLI auto-loads nearest .grimoire/setup.env at startup without overriding existing env vars

Authoring and Execution Policy

1. Read syntax references first (mandatory rule above). 2. Author/update spell. 3. Run format to canonicalize layout before validation. 4. Run validate (use --strict for advisory-heavy spells). 5. Fix errors/warnings and re-run until validation passes. 6. Run simulate. 7. Before venue metadata queries or value-moving runs, execute venue doctor for the target adapter/chain.

• Example: <grimoire-cmd> venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json

8. Before value-moving runs on EVM venues, verify endpoint and signer state with Foundry Cast quickchecks (chain-id, block-number, balance, nonce).

• Do not apply Anvil/Cast checks to offchain venues such as hyperliquid.

9. For advisory steps intended for deterministic execution, record and then use --advisory-replay <runId> in dry-run/live cast. 10. If spell includes irreversible actions, require cast --dry-run before any live cast. 11. Ask for explicit user confirmation before live value-moving cast. 12. For cross-chain mode, require explicit per-chain RPC mappings:

• --rpc-url <sourceChainId>=<url>
• --rpc-url <destinationChainId>=<url>

13. For cross-chain Morpho actions, require explicit market mapping via:

• --morpho-market-id <actionRef>=<marketId> (repeatable), or
• --morpho-market-map <path>

14. For Morpho supply-only strategies, prefer vault_deposit / vault_withdraw (explicit vault address).

• If vault address is missing, list candidate vaults and require user to pick one; never auto-select.

15. For Morpho market strategies (borrow/collateral/lend), require explicit market_id and use explicit actions:

• morpho_blue.supply_collateral(asset, amount, market_id)
• morpho_blue.withdraw_collateral(asset, amount, market_id)

16. Use bare 0x... address literals in action token fields; quoted address-like strings trigger QUOTED_ADDRESS_LITERAL. 17. For Morpho doctor readiness checks, set wallet env explicitly (GRIMOIRE_WALLET_ADDRESS preferred, fallback WALLET_ADDRESS). 18. If a cross-chain run is left waiting, continue with resume <runId> (use --watch to poll settlement). 19. Never place passwords/private keys in agent prompts or inline command assignments. 20. Prefer keystore + --password-env over --private-key for dry-run/live casts. 21. Treat .grimoire/setup.env as plaintext secret material: keep local-only and rotate/remove when no longer needed. 22. For commands run outside the project tree, set GRIMOIRE_SETUP_ENV_FILE=/abs/path/to/.grimoire/setup.env when needed.

Command Surface (Core)

• init
• setup
• format
• compile
• compile-all
• validate
• triggers
• simulate
• cast
• venues
• venue
• venue doctor
• history
• log
• resume
• wallet (generate, address, balance, import, wrap, unwrap)

Use references/cli-quick-reference.md for concise command signatures and safety-critical flags.

Runtime Behavior Model

• One runtime semantics: preview first, commit only for execute paths.
• simulate and cast --dry-run are preview-only flows.
• Live cast can commit irreversible actions when policy and runtime checks pass.
• simulate supports explicit --rpc-url, with precedence: --rpc-url -> RPC_URL_<chainId> -> RPC_URL.
• Phase 1 cross-chain execution uses two-spell orchestration (--destination-spell) with one logical run id and resume support.
• Use triggers <spell> to discover stable handler ids natively before targeted execution.
• simulate and cast support selected-trigger execution via --trigger-id, --trigger-index, and legacy --trigger.
• For multi-handler spells, prefer --trigger-id; --trigger is label-based and can be ambiguous.
• Cross-chain simulate / cast must forward the same selected trigger into per-chain execution.
• In --json mode, parse stdout only; progress and spinner output can still appear on stderr.

Query Functions (price / balance / apy / metric)

Always prefer query functions over advisory for structured data fetching. These are deterministic, fast, and don't require LLM calls.

• price(BASE, QUOTE[, SOURCE]) — live token price via query provider (requires Alchemy RPC URL)
• balance(ASSET[, ADDRESS]) — on-chain token balance via RPC (any RPC URL)
• apy(VENUE, ASSET[, SELECTOR]) — venue-backed APY surface (for example Aave and Morpho)
• metric(SURFACE, VENUE[, ASSET[, SELECTOR]]) — generic protocol metric surface
• Selector guidance:
• market/vault id selector: apy(morpho, USDC, "wbtc-usdc-86")
• vault selector (Morpho): metric("vault_net_apy", morpho, USDC, "vault=0xVaultAddress")
• Morpho vault_apy / vault_net_apy require explicit selector; do not rely on implicit defaults.
• key/value selector: metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000")
• Never use an advisory (advise) just to fetch prices, balances, APYs, or other structured metrics

Use advisory only when the task requires LLM judgment, reasoning, or interpretation.

Advisory Operating Rules

• Advisory must be explicit statement form: x = advise advisor: "prompt" { ... }.
• Treat advisory outputs as typed contracts; enforce schema with output.
• Require timeout and fallback in every advisory block.
• Prefer validate --strict when advisory logic gates value-moving actions.
• Use replay for determinism when moving from preview/dry-run to live execution.
• For runtime debugging, use --advisory-trace-verbose (non-JSON mode) to stream detailed advisory traces.

Venue Metadata and Snapshots

Use venue skills for snapshot parameters and market metadata:

• grimoire-aave
• grimoire-uniswap
• grimoire-morpho-blue
• grimoire-hyperliquid
• grimoire-pendle
• grimoire-polymarket

Formatting policy for venue CLI output:

• prefer --format json for automation or nested payloads
• use --format table for human-readable summaries

References

• references/syntax-capabilities.md
• references/authoring-workflow.md
• references/anvil-cheatsheet.md
• references/cast-cheatsheet.md
• references/cli-quick-reference.md
• docs/how-to/simulate-on-anvil-fork.md
• docs/how-to/use-wallet-commands-end-to-end.md
• docs/how-to/use-advisory-decisions.md
• docs/how-to/compare-protocol-metrics.md
• docs/explanation/advisory-decision-flow.md
• docs/reference/cli.md
• docs/reference/spell-syntax.md
• docs/reference/grimoire-dsl-spec.md
• docs/reference/compiler-runtime.md

Anvil Cheat Sheet (Grimoire)

Use this when running Grimoire preview/dry-run workflows against local forked state.

Scope:

• Anvil is EVM-only.
• Do not use Anvil workflows for offchain venues (for example hyperliquid).
• For Hyperliquid checks, use venue commands such as grimoire venue hyperliquid meta --format json.

0) Install Foundry (Anvil + Cast)

curl -L https://foundry.paradigm.xyz | bash && foundryup
anvil --version
cast --version

If your shell does not find the commands immediately, start a new shell session.

1) Start a Forked Anvil Node

Baseline:

anvil \
  --fork-url "$FORK_RPC_URL" \
  --chain-id "$CHAIN_ID" \
  --host 127.0.0.1 \
  --port 8545

Reproducible (pinned block + persisted state):

anvil \
  --fork-url "$FORK_RPC_URL" \
  --chain-id "$CHAIN_ID" \
  --fork-block-number "$FORK_BLOCK" \
  --state .grimoire/anvil/state.json \
  --state-interval 60 \
  --host 127.0.0.1 \
  --port 8545

Notes:

• --fork-url is the same as --rpc-url in Anvil.
• Keep Grimoire --chain equal to Anvil --chain-id.

2) Run Grimoire Against Anvil

Preview only:

<grimoire-cmd> simulate <spell-path> \
  --chain "$CHAIN_ID" \
  --rpc-url "http://127.0.0.1:8545"

Dry-run with wallet path (preview-only, wallet wiring included):

<grimoire-cmd> cast <spell-path> \
  --dry-run \
  --chain "$CHAIN_ID" \
  --rpc-url "http://127.0.0.1:8545" \
  --key-env PRIVATE_KEY

3) Preflight and Sanity Checks

Check that Grimoire is using the endpoint you expect:

<grimoire-cmd> venue doctor \
  --adapter uniswap \
  --chain "$CHAIN_ID" \
  --rpc-url "http://127.0.0.1:8545" \
  --json

Quick RPC checks:

cast chain-id --rpc-url http://127.0.0.1:8545
cast block-number --rpc-url http://127.0.0.1:8545

4) High-Value Anvil Flags

• --fork-block-number <n>: pin fork for repeatability.
• --state <path>: load and dump state automatically.
• --dump-state <path> / --load-state <path>: explicit state lifecycle.
• --auto-impersonate: enables impersonation workflows.
• --compute-units-per-second <n>: tune upstream provider throughput.
• --retries <n>: retry transient upstream errors.
• --no-rate-limit: disable local provider rate limiting.
• --fork-header "Key: Value": pass authenticated headers to upstream RPC.

5) Useful RPC Controls During Debugging

cast rpc evm_increaseTime 3600 --rpc-url http://127.0.0.1:8545
cast rpc evm_mine --rpc-url http://127.0.0.1:8545

SNAP=$(cast rpc evm_snapshot --rpc-url http://127.0.0.1:8545)
cast rpc evm_revert "$SNAP" --rpc-url http://127.0.0.1:8545

cast rpc anvil_impersonateAccount 0x... --rpc-url http://127.0.0.1:8545
cast rpc anvil_stopImpersonatingAccount 0x... --rpc-url http://127.0.0.1:8545

6) Common Failure Patterns

• Chain mismatch:
• align Anvil --chain-id and Grimoire --chain.
• Wrong RPC endpoint used:
• pass --rpc-url explicitly and verify rpcUrl in venue doctor --json.
• Upstream fork instability:
• set --fork-block-number, raise --retries, tune --compute-units-per-second.

Authoring Workflow (Agent Procedure)

Use this procedure whenever creating or editing .spell files.

1. Load Context

1. Read references/syntax-capabilities.md. 2. Identify the target spell path and trigger intent (manual, hourly, etc.). 3. Identify whether the spell has value-moving actions. 4. If using EVM custom RPC/fork or signing transactions, run Foundry Cast quickchecks from references/cast-cheatsheet.md. 5. For offchain venues (for example hyperliquid), skip Cast/Anvil checks and validate via venue API commands.

2. Author With Minimal Safe Skeleton

Start from:

spell Hello {
  params: {
    amount: 42
  }

  on manual: {
    doubled = params.amount * 2
    emit hello(amount=params.amount, doubled=doubled)
  }
}

Then incrementally add venues/actions/guards/advisory blocks.

Decision guide — query functions vs advisory:

• Need a price? Use price(BASE, QUOTE). Do NOT use an advisory to fetch prices.
• Need a balance? Use balance(ASSET) or balance(ASSET, address). Do NOT use an advisory.
• Need lending APY from a venue? Use apy(VENUE, ASSET[, selector]).
• Need cross-venue protocol comparison (quotes/mids/custom surfaces)? Use metric(SURFACE, VENUE[, ASSET[, selector]]).
• Need LLM judgment, reasoning, or interpretation? Use advise.

Query functions are deterministic, fast, and free. Advisory calls invoke an LLM and should only be used when human-like reasoning is required.

3. Compile/Validate Loop

Run:

<grimoire-cmd> validate <spell-path>

If validation fails:

1. fix the highest-impact error first 2. re-run validate 3. repeat until success

For advisory-heavy spells:

<grimoire-cmd> validate <spell-path> --strict

Use strict mode to force explicit advisory hygiene (context, within, explicit on_violation).

4. Preview Loop

Run:

<grimoire-cmd> simulate <spell-path> --chain <id>

Recommended RPC preflight:

cast chain-id --rpc-url <rpc>
cast block-number --rpc-url <rpc>

Skip this preflight for offchain venues such as hyperliquid.

For local forked preview (Anvil):

<grimoire-cmd> simulate <spell-path> --chain <id> --rpc-url http://127.0.0.1:8545

If simulate fails:

1. identify phase (compile, preview policy, adapter/data, etc.) 2. patch spell/params/config 3. re-run simulate

For advisory flows, inspect whether failure is:

1. model/tooling resolution (advisory_failed) 2. output schema mismatch (Advisory output violated schema) 3. replay data mismatch (missing advisory output for step id)

5. Value-Moving Safety Path

For spells with irreversible actions:

1. verify signer state:

cast balance <address> --rpc-url <rpc>
cast nonce <address> --rpc-url <rpc>

For offchain venues, replace signer-RPC checks with venue-specific health/meta checks.

2. require dry-run first:

<grimoire-cmd> cast <spell-path> --dry-run --chain <id> --key-env PRIVATE_KEY --rpc-url <rpc>

3. summarize risks and expected behavior 4. request explicit user confirmation before live cast

If advisory gates execution policy, prefer deterministic path:

1. preview and capture run id 2. dry-run cast with --advisory-replay <runId> 3. live cast with --advisory-replay <runId> after confirmation

6. Snapshot/Data Inputs

If spell depends on venue snapshots:

1. use matching venue skill command with --format spell 2. paste/merge params carefully 3. enforce freshness policy where needed (--data-max-age, --on-stale)

7. Done Criteria

A spell task is done only when:

1. syntax matches supported capabilities 2. validate passes 3. simulate passes or failure is explicitly documented 4. dry-run is performed for value-moving flows 5. live-cast confirmation gate is respected

For advisory-driven spells, also require:

1. advisory output schema is explicit and validated 2. fallback behavior is acceptable under failure 3. replay policy is documented when deterministic behavior is required

Cast Cheat Sheet (Grimoire)

Use Cast for fast RPC and transaction diagnostics before or during Grimoire runs. For networked commands, always pass --rpc-url "$RPC_URL" explicitly.

Scope:

• Cast diagnostics here are for EVM RPC workflows.
• Do not use Cast/Anvil diagnostics for offchain venues (for example hyperliquid).
• For Hyperliquid validation, use venue endpoints (grimoire venue hyperliquid mids|l2-book|open-orders|meta --format json).

0) Install Foundry (Anvil + Cast)

curl -L https://foundry.paradigm.xyz | bash && foundryup
cast --version
anvil --version

If your shell does not find the commands immediately, start a new shell session.

1) Endpoint and Chain Sanity

cast client --rpc-url "$RPC_URL"
cast chain-id --rpc-url "$RPC_URL"
cast block-number --rpc-url "$RPC_URL"
cast gas-price --rpc-url "$RPC_URL"

Use this before simulate/cast to verify endpoint health and chain alignment.

2) Account and Balance Checks

cast balance "$ADDRESS" --rpc-url "$RPC_URL"
cast nonce "$ADDRESS" --rpc-url "$RPC_URL"

Use when troubleshooting signer state, insufficient funds, or nonce drift.

3) Read Contract State

# Generic view call
cast call "$CONTRACT" "symbol()(string)" --rpc-url "$RPC_URL"

# ERC20 balance check
cast call "$TOKEN" "balanceOf(address)(uint256)" "$ADDRESS" --rpc-url "$RPC_URL"

# Raw storage slot read
cast storage "$CONTRACT" 0 --rpc-url "$RPC_URL"

Decode calldata selectors/signatures:

cast 4byte-calldata 0xa9059cbb000000000000000000000000...

4) Inspect Transactions and Receipts

cast tx "$TX_HASH" --rpc-url "$RPC_URL"
cast receipt "$TX_HASH" --rpc-url "$RPC_URL"
cast run "$TX_HASH" --rpc-url "$RPC_URL"
cast decode-error "$REVERT_DATA"

Use cast run for replay-style debugging of a published tx in local context.

5) Build/Estimate Before Sending

cast calldata "transfer(address,uint256)" "$TO" "$AMOUNT"
cast estimate "$TO" "transfer(address,uint256)" "$RECIPIENT" "$AMOUNT" --rpc-url "$RPC_URL" --from "$FROM"

Use this to verify calldata and approximate gas cost before committing.

6) Controlled Send (Stateful)

Only run after explicit confirmation for value-moving actions.

Preferred signer path (keystore + password env):

cast send "$TO" "transfer(address,uint256)" "$RECIPIENT" "$AMOUNT" \
  --rpc-url "$RPC_URL" \
  --keystore "$KEYSTORE_PATH" \
  --password-env KEYSTORE_PASSWORD

Raw key path (only when needed):

cast send "$TO" "transfer(address,uint256)" "$RECIPIENT" "$AMOUNT" \
  --rpc-url "$RPC_URL" \
  --private-key "$PRIVATE_KEY"

Prefer keystore or env vars over inline raw private keys in shared shells. For local Anvil only, use funded dev keys and never production secrets. If setup generated .grimoire/setup.env, Grimoire CLI auto-loads it, but Foundry cast does not; export/source env vars explicitly before Cast commands.

7) Anvil-Fork Debug Helpers

cast rpc evm_snapshot --rpc-url http://127.0.0.1:8545
cast rpc evm_revert "$SNAP" --rpc-url http://127.0.0.1:8545
cast rpc evm_increaseTime 3600 --rpc-url http://127.0.0.1:8545
cast rpc evm_mine --rpc-url http://127.0.0.1:8545

8) High-Value Failure Patterns

• chain-id unexpected:
• wrong RPC endpoint or misconfigured env var.
• balance/nonce not as expected:
• wrong signer address or stale fork state.
• estimate fails but call works:
• state-changing path reverts under current sender/value.
• receipt status 0x0:
• decode error data: cast decode-error "$REVERT_DATA".

9) JSON Output for Automation

Use JSON mode for scripting and stable machine-readable parsing:

cast tx "$TX_HASH" --rpc-url "$RPC_URL" --json
cast receipt "$TX_HASH" --rpc-url "$RPC_URL" --json
cast block "$BLOCK_NUMBER" --rpc-url "$RPC_URL" --json

CLI Quick Reference

Use this page for concise command signatures and high-signal options.

Assume <grimoire-cmd> is one of:

• grimoire
• npx -y @grimoirelabs/cli
• bun run packages/cli/src/index.ts --

When using the repo-local Bun entrypoint, keep the trailing -- so command flags are passed through to Grimoire.

Core Commands

<grimoire-cmd> init [--force] [--runtime-quickstart]
<grimoire-cmd> setup [--chain <id>] [--rpc-url <url>] [--adapter <name>] [--keystore <path>] [--password-env <name>] [--key-env <name>] [--import-key] [--no-save-password-env] [--no-doctor] [--non-interactive] [--json]
<grimoire-cmd> format <paths...> [--write|--check] [--diff] [--json]
<grimoire-cmd> format --stdin --stdin-filepath <virtual-path> [--json]
<grimoire-cmd> compile <spell> [-o <file>] [--pretty]
<grimoire-cmd> compile-all [dir] [--fail-fast] [--json]
<grimoire-cmd> validate <spell> [--strict] [--json]
<grimoire-cmd> triggers <spell> [--json]
<grimoire-cmd> simulate <spell> [options]
<grimoire-cmd> cast <spell> [options]
<grimoire-cmd> venues [--json]
<grimoire-cmd> venue <adapter> [args...]
<grimoire-cmd> venue doctor [--chain <id>] [--adapter <name>] [--rpc-url <url>] [--json]
<grimoire-cmd> resume <runId> [--watch] [--poll-interval-sec <seconds>] [--json] [--state-dir <dir>]
<grimoire-cmd> history [spell] [--limit <n>] [--json] [--state-dir <dir>]
<grimoire-cmd> log <spell> <runId> [--json] [--state-dir <dir>]

Setup (Execute Onboarding)

Use before first live or dry-run casts in a new local environment:

<grimoire-cmd> setup

Behavior:

1. Creates local .grimoire/ directory when missing. 2. Runs built-in smoke compile + preview checks. 3. Verifies RPC reachability. 4. Provisions wallet keystore (existing, env import, or generated). 5. Runs venue doctor by adapter (default uniswap) unless --no-doctor. 6. Prompts for missing required values in interactive mode. 7. Blank RPC input falls back to chain default public RPC. 8. Writes .grimoire/setup.env after interactive password entry (unless --no-save-password-env). 9. Shows password safety guidance to avoid leaking secrets in agent-run sessions. 10. CLI auto-loads nearest .grimoire/setup.env on startup unless env vars are already set. 11. GRIMOIRE_SETUP_ENV_FILE can point to an explicit setup env file path.

Password safety:

1. Do not paste passwords/private keys into Codex/Claude prompts. 2. Prefer hidden interactive prompts over inline secret values. 3. For automation, preload secret env values outside the agent and pass only env var names. 4. .grimoire/setup.env is plaintext secret material; keep local-only and rotate/delete when done.

Venue Doctor (Preflight)

Use before venue metadata calls or strategy execution:

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

Checks:

• adapter registration
• required env vars
• chain support
• RPC reachability

Tip:

• In --json output, confirm rpcUrl is the endpoint actually used.
• If grimoire venue doctor ... fails with Unknown venue adapter "doctor", your installed global CLI is old; use npx -y @grimoirelabs/cli@latest ... or repo-local invocation.

Simulate (Preview)

Native trigger discovery:

<grimoire-cmd> triggers <spell> --json

Use this before simulate --trigger-id or cast --trigger-id. It returns each compiled handler's { id, index, label, source } plus trigger payload and owned step ids.

Common options:

• -p, --params <json>
• --chain <id>
• --rpc-url <url>
• --trigger-id <id>
• --trigger-index <n>
• --trigger <label> (legacy label selector)
• --destination-spell <spell>
• --destination-chain <id>
• --handoff-timeout-sec <seconds>
• --poll-interval-sec <seconds>
• --watch
• --morpho-market-id <actionRef>=<marketId> (repeatable)
• --morpho-market-map <path>
• --state-dir <dir>
• --no-state
• --advisor-skills-dir <dir...>
• --advisory-pi
• --advisory-replay <runId>
• --advisory-provider <name>
• --advisory-model <id>
• --advisory-thinking <off|low|medium|high>
• --advisory-tools <none|read|coding>
• --advisory-trace-verbose
• --pi-agent-dir <dir>
• --data-replay <off|auto|runId|snapshotId>
• --data-max-age <sec>
• --on-stale <fail|warn>

Important:

1. simulate supports --rpc-url for explicit per-run RPC selection. 2. RPC resolution order is --rpc-url, then RPC_URL_<chainId>, then RPC_URL. 3. Cross-chain mode is enabled by --destination-spell and requires explicit mapped RPCs for both chains: --rpc-url <chainId>=<url>. 4. Cross-chain Morpho actions require explicit market mapping (--morpho-market-id or --morpho-market-map). 5. When --rpc-url is an Alchemy URL (e.g. https://eth-mainnet.g.alchemy.com/v2/<key>), the API key is auto-extracted and used to enable price() queries via the Alchemy query provider. 6. balance() works with any RPC, and adapter-backed apy() / metric() do not require Alchemy. 7. --trigger-id is the canonical handler selector; use it for automation and event-only multi-handler spells. 8. Cross-chain simulate mode also honors selected-trigger flags. 9. In --json mode, parse stdout only; progress lines may still appear on stderr.

Anvil Quickstart

Use only for EVM venues. Do not use for hyperliquid (offchain).

Start forked local node:

anvil \
  --fork-url "$FORK_RPC_URL" \
  --chain-id "$CHAIN_ID" \
  --fork-block-number "$FORK_BLOCK" \
  --state .grimoire/anvil/state.json \
  --host 127.0.0.1 \
  --port 8545

Run preview against Anvil:

<grimoire-cmd> simulate <spell> --chain "$CHAIN_ID" --rpc-url http://127.0.0.1:8545

Preflight endpoint and env:

<grimoire-cmd> venue doctor --adapter uniswap --chain "$CHAIN_ID" --rpc-url http://127.0.0.1:8545 --json

Optional Foundry Cast preflight against Anvil:

cast chain-id --rpc-url http://127.0.0.1:8545
cast block-number --rpc-url http://127.0.0.1:8545

Venue Output Formats

Use --format json for scripts and nested payloads (for example hyperliquid meta).

• auto: table only for flat TTY-friendly outputs, otherwise JSON
• table: compact summary for nested arrays/objects
• json: full payload, stable for automation

Cast (Dry-Run / Live)

Common options:

• --dry-run
• --chain <id>
• --trigger-id <id>
• --trigger-index <n>
• --trigger <label> (legacy label selector)
• --key-env <name>
• --keystore <path>
• --password-env <name>
• --rpc-url <url>
• --destination-spell <spell>
• --destination-chain <id>
• --handoff-timeout-sec <seconds>
• --poll-interval-sec <seconds>
• --watch
• --morpho-market-id <actionRef>=<marketId> (repeatable)
• --morpho-market-map <path>
• --skip-confirm
• --state-dir <dir>
• --no-state
• --advisor-skills-dir <dir...>
• --advisory-pi
• --advisory-replay <runId>
• --advisory-provider <name>
• --advisory-model <id>
• --advisory-thinking <off|low|medium|high>
• --advisory-tools <none|read|coding>
• --advisory-trace-verbose
• --pi-agent-dir <dir>

Safety rule:

1. run cast --dry-run before live cast for value-moving spells 2. require explicit user confirmation before live cast

Replay rule for advisory-gated execution:

1. use --advisory-replay <runId> for dry-run/live consistency 2. do not combine replay with --no-state

Cross-chain continuation:

1. if run status is waiting, continue with resume <runId> 2. use resume --watch to poll handoff settlement and execute destination track 3. selected-trigger flags also apply in cross-chain cast mode

JSON output guidance:

1. simulate --json and cast --json emit a single machine-readable payload on stdout 2. parse stdout only; human progress and spinner output may be written to stderr 3. selected-trigger runs include selectedTrigger, events, and finalState in the JSON payload

Foundry Cast (RPC/Tx Diagnostics)

Use Foundry cast for endpoint/signer/transaction debugging around Grimoire runs. Prefer explicit --rpc-url and JSON mode (--json) for automation. These checks are EVM-only and are not applicable to offchain venues such as hyperliquid.

High-value quickchecks:

cast chain-id --rpc-url "$RPC_URL"
cast block-number --rpc-url "$RPC_URL"
cast balance "$ADDRESS" --rpc-url "$RPC_URL"
cast nonce "$ADDRESS" --rpc-url "$RPC_URL"
cast receipt "$TX_HASH" --rpc-url "$RPC_URL"
cast decode-error "$REVERT_DATA"

Signer hygiene:

• prefer --keystore + --password-env over raw --private-key
• if using --private-key, keep it in env vars and avoid shell history leaks

For expanded patterns and Anvil debug RPC calls, use references/cast-cheatsheet.md.

Wallet Subcommands

<grimoire-cmd> wallet generate [--keystore <path>] [--password-env <name>] [--print-key] [--json]
<grimoire-cmd> wallet address [--keystore <path>] [--password-env <name>] [--key-env <name>] [--mnemonic <phrase>] [--json]
<grimoire-cmd> wallet balance [--keystore <path>] [--password-env <name>] [--key-env <name>] [--mnemonic <phrase>] [--chain <id>] [--rpc-url <url>] [--json]
<grimoire-cmd> wallet import [--keystore <path>] [--password-env <name>] [--key-env <name>] [--json]
<grimoire-cmd> wallet wrap --amount <eth> [--chain <id>] [--keystore <path>] [--password-env <name>] [--rpc-url <url>] [--json]
<grimoire-cmd> wallet unwrap --amount <eth> [--chain <id>] [--keystore <path>] [--password-env <name>] [--rpc-url <url>] [--json]

High-Use Environment Variables

• PRIVATE_KEY
• KEYSTORE_PASSWORD
• RPC_URL
• ENS_RPC_URL
• GRIMOIRE_SETUP_ENV_FILE

Syntax Capabilities (Authoritative Authoring Reference)

Use this file before creating or modifying any .spell file.

Top-Level Shape

Required form:

spell MySpell {
  on manual: {
    emit started()
  }
}

Supported top-level sections:

• version
• description
• assets
• params
• limits
• venues
• state
• skills
• advisors
• guards
• import
• block
• one or more on ...: { ... } handlers

Section Capabilities

assets

Array form:

assets: [USDC, WETH,]

Object form:

assets: {
  USDC: {
    chain: 8453
    address: "0x..."
    decimals: 6
  }
}

params

Simple values:

params: {
  amount: 1000000
  enabled: true
}

Amounts must be in raw token units (smallest denomination). This applies to all venue actions — swaps, lending, bridging, etc.

Formula: raw_amount = human_amount × 10^decimals

Common mistake: writing amount: 1000 for "1000 USDC" — this is actually 0.001 USDC (1000 / 10^6). Use amount: 1000000000 instead.

Typed/extended values:

params: {
  amount: {
    type: amount
    asset: USDC
    default: 1.5 USDC
    min: 0
    max: 1000000
  }
}

limits

limits: {
  max_single_move: 500000
  approval_required_above: 100000
}

venues

venues: {
  uniswap_v3: @uniswap_v3
  lending: [@aave_v3, @morpho_blue,]
}

state

state: {
  persistent: {
    counter: 0
  }
  ephemeral: {
    temp: 0
  }
}

skills

skills: {
  dex: {
    type: swap
    adapters: [uniswap_v3]
    default_constraints: {
      max_slippage: 50
    }
  }
}

advisors

advisors: {
  risk: {
    model: anthropic:sonnet
    system_prompt: "Return strict JSON"
    skills: [grimoire]
    allowed_tools: [read_file]
    mcp: [docs]
    timeout: 30
    fallback: true
    rate_limit: {
      max_per_run: 10
      max_per_hour: 100
    }
  }
}

guards

guards: {
  enough_balance: balance(USDC) > 1000 with (
    severity="halt",
    message="Insufficient balance",
  )
}

Guard metadata keys accepted in with (...):

• severity (warn | revert | halt)
• message
• fallback

Trigger Capabilities

Trigger form:

on <trigger>: {
  ...
}

Supported trigger kinds:

• manual
• hourly
• daily
• schedule string: on "0 * * * *": { ... }
• condition: on condition <expr> every <seconds>: { ... }
• event: on event "EventName" where <expr>: { ... }

Statement Capabilities

Supported statement forms inside blocks:

• assignment: x = expr
• action/method call: venue.swap(...)
• if / elif / else
• for x in expr { ... }
• repeat N { ... }
• loop until cond max N { ... }
• try { ... } catch ... { ... } finally { ... }
• parallel ... { branch: { ... } }
• pipeline: source | map: { ... } | ...
• do blockName(args)
• atomic { ... }
• atomic skip|halt|revert { ... }
• emit event(k=v, ...)
• halt "reason"
• wait 60
• pass
• advisory assignment: x = advise advisor: "prompt" { ... }

Action Routing Capabilities

Method calls on venue-like identifiers compile into action steps.

All amounts are in raw token units (see params section above).

Examples:

# Swap 1000 USDC (6 decimals) to WETH
uniswap_v3.swap(USDC, WETH, params.amount)

# Lend 1000 USDC to Aave
aave_v3.lend(USDC, params.amount)

# Borrow 1000 USDC with ETH collateral
aave_v3.borrow(USDC, params.amount, WETH)

# Bridge 1000 USDC to Arbitrum
across.bridge(USDC, params.amount, 42161)

Optional action clauses:

• using <skill>
• with key=value, ...
• multiline with (...)

Constraint alias normalization:

• slippage -> max_slippage
• min_out -> min_output
• max_in -> max_input

Advisory Capabilities

Inline advisory markers (**...**) are unsupported for authoring.

Supported advisory form:

decision = advise risk: "Should we rebalance?" {
  context: {
    current_rate: rate
    gas: gas_cost
  }
  within: "execution"
  output: {
    type: object
    fields: {
      allow: boolean
      reason: string
    }
  }
  on_violation: reject
  clamp_constraints: [max_slippage]
  timeout: 20
  fallback: { allow: false, reason: "timeout" }
}

Required fields inside advise block:

• output
• timeout
• fallback

Advisory field semantics:

• context: optional object of named expressions to pass into advisory input
• within: optional policy scope label
• output: required output schema contract
• on_violation: optional, reject or clamp (default behavior is reject)
• clamp_constraints: required when on_violation: clamp
• timeout: required positive number
• fallback: required expression used if advisory resolution fails

Output schema types:

• boolean
• number (min, max)
• enum (values)
• string (min_length, max_length, pattern)
• object (fields)
• array (items)

Expression Capabilities

Operator precedence (high to low):

1. postfix (., [], call) 2. unary (not, unary -) 3. multiplicative (* / %) 4. additive (+ -) 5. comparison (< > <= >=) 6. equality (== !=) 7. logical and 8. logical or 9. ternary ? :

Expression forms:

• literals: numbers, booleans, strings, addresses
• percentages: 50%
• unit literals: 1.5 USDC, 25 bps, 5m, 1h, 1d
• arrays: [a, b,]
• objects: { key: value, ... }
• identifiers
• property access and indexing
• function calls (min, max, sum, avg, to_number, to_bigint, etc.)
• query functions: price(base, quote, source?), balance(asset, address?), apy(venue, asset, selector?), metric(surface, venue, asset?, selector?)

Query Functions vs Advisory

Always prefer query functions over advisory calls for structured data fetching.

• price(WBTC, USDC) — returns a live price from the query provider (Alchemy API). Deterministic, fast, no LLM cost.
• balance(USDC) — returns on-chain token balance via RPC. No LLM needed.
• balance(USDC, 0xaddr) — balance of a specific address.
• price(ETH, USDC, "chainlink") — with explicit source hint.
• apy(aave, USDC) — venue-backed APY query for lending comparison.
• apy(morpho, USDC, "wbtc-usdc-86") — APY query with explicit market selector.
• metric("quote_out", uni_v3, USDC, "asset_out=WETH,amount=1000000,fee_tier=3000") — DEX quote comparison.
• metric("mid_price", polymarket, USDC, "token_id=<clobTokenId>") — offchain midpoint comparison.

Use advisory (advise) only when the task requires LLM judgment, reasoning, or interpretation — not for fetching prices, balances, APYs, or other structured metrics that query functions handle natively.

Anti-pattern (do NOT do this):

# BAD: Using an LLM call just to fetch a price
price_data = advise oracle: "Fetch BTC/USD price from API" { ... }

Correct pattern:

# GOOD: Direct query function
btc_price = price(WBTC, USDC)

Requires --rpc-url with an Alchemy URL for price(); any RPC works for balance(). apy() and metric() are adapter-backed and do not require Alchemy.

Constraint Clause Capabilities

Inline:

... with max_slippage=50, deadline=300

Multiline:

... with (
  max_slippage=50,
  deadline=300,
  min_output=1000,
)

Trailing commas are accepted.

Commas are required inside with (...) — parentheses suppress newlines, so newlines alone do not separate entries. This applies to all parenthesized contexts: with (...), emit foo(k=v, ...), function calls, and array literals [...].

Grammar/Formatting Behaviors

• # begins a comment.
• Delimiter rule: {} blocks use newlines as separators. () and [] suppress newlines, so commas are required.
• Braces {} are required for block structure.
• Trailing commas are accepted in list-like contexts.
• Multiline objects are supported.

Authoring Guardrails

Before finalizing any authored spell:

1. Run validate. 2. Run simulate. 3. Confirm no unsupported syntax is used. 4. Confirm advisory blocks include required fields. 5. Confirm value-moving spells include appropriate constraints (max_slippage and min_output for swaps).