grimoire

Original：🇺🇸 English

Translated

Core Grimoire CLI for compiling, validating, simulating, and executing .spell files. Use when you need to run any grimoire command.

3installs

Sourcefranalgaba/grimoire

Added on2026-02-08

NPX Install

npx skill4agent add franalgaba/grimoire grimoire

SKILL.md Content

View Translation Comparison →

Grimoire CLI Skill

The Grimoire CLI compiles, validates, simulates, and executes

.spell

strategy files.

When to use

You want deterministic execution with adapters (
```
simulate
```
,
```
cast
```
).
You need CLI-only workflows (compile, validate, history, logs, wallet).

VM vs deterministic

VM mode runs inside an agent session and is best-effort. Use the
```
grimoire-vm
```
skill for in-agent execution.
Deterministic runtime runs via the CLI. This skill covers that runtime.

For VM prototyping with snapshots, use the venue skills (

grimoire-aave

,

grimoire-uniswap

,

grimoire-morpho-blue

,

grimoire-hyperliquid

) with

--format spell

.

Commands

grimoire init

Initialize a new

.grimoire

directory with config and examples.

bash

grimoire init [--force] [--vm]

Use

--vm

to scaffold a VM quickstart spell and README.

grimoire compile

Compile a

.spell

file to IR (intermediate representation).

bash

grimoire compile <spell> [-o <file>] [--pretty]

grimoire compile-all

Compile every

.spell

file in a directory (default:

spells/

).

bash

grimoire compile-all [dir] [--fail-fast] [--json]

grimoire validate

Validate a

.spell

file without compiling.

bash

grimoire validate <spell> [--strict]

grimoire simulate

Simulate spell execution (dry run). State is loaded/saved between runs.

bash

grimoire simulate <spell> [-p <json>] [--vault <address>] [--chain <id>] [--state-dir <dir>] [--no-state]
  [--advisor-skills-dir <dir>...]
  [--advisory-pi] [--advisory-replay <runId>] [--advisory-provider <name>] [--advisory-model <id>]
  [--advisory-thinking <level>] [--advisory-tools <mode>] [--pi-agent-dir <dir>]

grimoire cast

Execute a spell onchain. Supports dry-run and live modes.

bash

grimoire cast <spell> [-p <json>] [--vault <address>] [--chain <id>] \
  [--dry-run] [--key-env <name>] [--keystore <path>] [--password-env <name>] \
  [--rpc-url <url>] [--gas-multiplier <n>] [--skip-confirm] [-v] [--json] \
  [--advisor-skills-dir <dir>...] [--state-dir <dir>] [--no-state] \
  [--advisory-pi] [--advisory-replay <runId>] [--advisory-provider <name>] [--advisory-model <id>] \
  [--advisory-thinking <level>] [--advisory-tools <mode>] [--pi-agent-dir <dir>]

grimoire venues

List available venue adapters and supported chains.

bash

grimoire venues [--json]

grimoire venue

Proxy to venue metadata CLIs bundled in

@grimoirelabs/venues

.

bash

grimoire venue <adapter> [args...]

grimoire history

View execution history for spells.

bash

grimoire history              # list all spells with state
grimoire history <spellId>    # runs for a specific spell
grimoire history <spellId> --limit 5 --json

grimoire log

View ledger events for a specific spell run.

bash

grimoire log <spellId> <runId> [--json] [--state-dir <dir>]

grimoire wallet

Manage wallet operations.

bash

grimoire wallet generate                          # create new keystore
grimoire wallet address --keystore <path> --password-env <name>
grimoire wallet balance --keystore <path> --password-env <name> --chain <id> --rpc-url <url>
grimoire wallet import --private-key <hex>
grimoire wallet wrap --amount <n> --chain <id> --keystore <path> --password-env <name>
grimoire wallet unwrap --amount <n> --chain <id> --keystore <path> --password-env <name>

Running Locally

All CLI commands can be invoked via:

bash

bun run packages/cli/src/index.ts <command> [args]

Environment Variables

```
PRIVATE_KEY
```
- Wallet private key (default for
```
--key-env
```
)
```
KEYSTORE_PASSWORD
```
- Keystore password (default for
```
--password-env
```
)
```
RPC_URL
```
- JSON-RPC endpoint (fallback for
```
--rpc-url
```
)

State Persistence

Simulate and cast automatically load/save spell state to

.grimoire/grimoire.db

(SQLite). Use

--no-state

to disable or

--state-dir

to change the directory.

Advisor Skills

Use

--advisor-skills-dir <dir>

with

simulate

or

cast

to resolve advisor skills from directories containing

SKILL.md

files. The runtime emits

skills

/

allowedTools

metadata in advisory events for external orchestrators.

Advisory (Pi OAuth)

Advisory steps (

**...**

and

advise

) call Pi when a model is configured (spell model, CLI model/provider, or Pi defaults). If no model is available, the runtime uses the spell fallback. Use

--advisory-pi

to force Pi even if no model is configured.

OAuth (OpenAI Codex) setup:

bash

pi
/login
# select OpenAI Codex

If the

pi

CLI is not installed globally, you can run

npx @mariozechner/pi-coding-agent

instead. Credentials live under

~/.pi/agent

unless you pass

--pi-agent-dir

.

Example:

bash

grimoire simulate spells/my-spell.spell \
  --advisory-pi \
  --advisory-provider openai-codex \
  --advisory-model gpt-5.2 \
  --advisory-tools none

Record → replay (deterministic advisory outputs):

bash

grimoire simulate spells/my-spell.spell --advisory-pi
grimoire simulate spells/my-spell.spell --advisory-replay <runId>

grimoire

NPX Install

Tags

SKILL.md Content

Grimoire CLI Skill

When to use

VM vs deterministic

Commands

grimoire init

grimoire compile

grimoire compile-all

grimoire validate

grimoire simulate

grimoire cast

grimoire venues

grimoire venue

grimoire history

grimoire log

grimoire wallet

Running Locally

Environment Variables

State Persistence

Advisor Skills

Advisory (Pi OAuth)