grimoire

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Grimoire CLI Skill

Grimoire CLI 技能

The Grimoire CLI compiles, validates, simulates, and executes

.spell

strategy files.

Grimoire CLI 可编译、验证、模拟并执行

.spell

策略文件。

When to use

使用场景

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

你希望通过适配器实现确定性执行（
```
simulate
```
、
```
cast
```
命令）。
你需要纯CLI工作流（编译、验证、历史记录、日志、钱包操作）。

VM vs deterministic

VM模式 vs 确定性模式

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

VM模式在Agent会话中运行，为尽力而为型执行。如需在Agent内执行，请使用
```
grimoire-vm
```
技能。
确定性运行时通过CLI运行。本技能覆盖该运行时场景。

如需使用快照进行VM原型开发，请结合

--format spell

参数使用场景适配器技能（

grimoire-aave

、

grimoire-uniswap

、

grimoire-morpho-blue

、

grimoire-hyperliquid

）。

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

目录。

bash

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

使用

--vm

参数可快速搭建VM入门级spell文件和README文档。

grimoire compile

Compile a

.spell

file to IR (intermediate representation).

bash

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

将

.spell

文件编译为IR（中间表示）。

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]

编译指定目录下所有

.spell

文件（默认目录：

spells/

）。

bash

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

grimoire validate

Validate a

.spell

file without compiling.

bash

grimoire validate <spell> [--strict]

无需编译即可验证

.spell

文件的合法性。

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>]

模拟spell执行（试运行）。运行过程中会自动加载/保存状态。

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>]

在链上执行spell。支持试运行和正式运行模式。

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]

列出可用的场景适配器及支持的链。

bash

grimoire venues [--json]

grimoire venue

Proxy to venue metadata CLIs bundled in

@grimoirelabs/venues

bash

grimoire venue <adapter> [args...]

代理调用

@grimoirelabs/venues

中捆绑的场景元数据CLI。

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

查看spell的执行历史记录。

bash

grimoire history              # 列出所有带状态的spell
grimoire history <spellId>    # 查看指定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>]

查看特定spell运行的账本事件日志。

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>

管理钱包操作。

bash

grimoire wallet generate                          # 创建新的密钥库
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]

所有CLI命令均可通过以下方式调用：

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
```
)

```
PRIVATE_KEY
```
- 钱包私钥（
```
--key-env
```
参数的默认值）
```
KEYSTORE_PASSWORD
```
- 密钥库密码（
```
--password-env
```
参数的默认值）
```
RPC_URL
```
- JSON-RPC端点（
```
--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.

Simulate和Cast命令会自动将spell状态加载/保存到

.grimoire/grimoire.db

（SQLite数据库）。可使用

--no-state

参数禁用该功能，或通过

--state-dir

参数修改存储目录。

Advisor Skills

顾问技能

Use

--advisor-skills-dir <dir>

with

simulate

cast

to resolve advisor skills from directories containing

SKILL.md

files. The runtime emits

skills

allowedTools

metadata in advisory events for external orchestrators.

在使用simulate或cast命令时，可通过

--advisor-skills-dir <dir>

参数从包含

SKILL.md

文件的目录中加载顾问技能。运行时会在顾问事件中输出

skills

allowedTools

元数据，供外部编排器使用。

Advisory (Pi OAuth)

顾问功能（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

当配置了模型（spell模型、CLI模型/提供商或Pi默认值）时，顾问步骤（

**...**

和

advise

）会调用Pi。若未配置任何模型，运行时会使用spell的 fallback 方案。使用

--advisory-pi

参数可强制调用Pi，即使未配置模型。

OAuth（OpenAI Codex）设置：

bash

pi
/login

select OpenAI Codex

选择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>


若未全局安装`pi` CLI，可使用`npx @mariozechner/pi-coding-agent`替代。凭据默认存储在`~/.pi/agent`目录下，可通过`--pi-agent-dir`参数修改存储路径。

示例：

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

记录→重放（确定性顾问输出）：

bash

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