Grimoire CLI 使用指南：区块链法术编写、验证与执行全流程

grimoire by franalgaba/grimoire

940 周安装量

1 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/franalgaba/grimoire --skill grimoire

开发自动化区块链

🇨🇳中文介绍

Grimoire CLI 技能

此技能是 Grimoire 的基础操作手册。

使用时机

当任务涉及以下内容时，请使用此技能：

安装/设置 Grimoire 工具
创建或编辑 .spell 文件
关于 DSL 功能的语法问题
咨询（advise）的编写、调试和重放工作流
设置/编译/验证/模拟/施放/恢复工作流
调试法术编译/运行时故障

强制加载规则

以下所有 references/ 和 docs/ 路径均相对于此技能目录（skills/grimoire/）。这些规则是必需的——它们解决了导致编写错误的语法覆盖缺口。

立即停止——首先阅读此部分： 请不要搜索代码库、使用 grep 查找语法模式或依赖记忆来获取 DSL 语法。与此技能捆绑的参考文件是唯一可信来源。在编写或编辑任何法术内容之前，请立即使用 Read 工具阅读下面列出的文件。

对于任何 .spell 编写/编辑任务——在开始其他操作之前，使用 Read 工具阅读这些文件：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

快速开始（立即成功路径）

在编写自定义法术之前，请使用此序列：

<grimoire-cmd> --help
<grimoire-cmd> setup（引导式交互执行入门）
<grimoire-cmd> validate spells/compute-only.spell
<grimoire-cmd> simulate spells/compute-only.spell --chain 1

如果以上三步全部通过，则可以继续法术编写。

设置安全/运行时预期：

设置过程会提示输入隐藏密码，且从不回显输入内容
空白的 RPC 输入会回退到链的默认公共 RPC
除非使用 --no-save-password-env，否则设置过程可能会写入 .grimoire/setup.env
CLI 在启动时会自动加载最近的 .grimoire/setup.env，且不会覆盖现有的环境变量

编写与执行策略

首先阅读语法参考（见上方强制规则）。
编写/更新法术。
运行 validate（对于咨询密集的法术，使用 --strict）。
修复错误/警告并重新运行，直到验证通过。
运行 simulate。
在进行场所元数据查询或涉及价值转移的运行之前，为目标适配器/链执行 venue doctor。
- 示例：<grimoire-cmd> venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json
在 EVM 场所进行涉及价值转移的运行之前，使用 Foundry Cast 快速检查验证端点和签名者状态（chain-id、block-number、balance、nonce）。
- 不要将 Anvil/Cast 检查应用于链下场所，例如 hyperliquid。
对于旨在确定性执行的咨询步骤，请先记录，然后在试运行/实际施放中使用 --advisory-replay <runId>。
如果法术包含不可逆操作，在任何实际施放之前，必须要求进行 cast --dry-run。
在实际进行涉及价值转移的 cast 之前，要求明确的用户确认。
对于跨链模式，要求明确的每链 RPC 映射：

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

对于跨链 Morpho 操作，要求通过以下方式明确市场映射：

--morpho-market-id <actionRef>=<marketId>（可重复），或
--morpho-market-map <path>

对于 Morpho 抵押品生命周期，优先使用明确的操作：

morpho_blue.supply_collateral(asset, amount[, market_id])
morpho_blue.withdraw_collateral(asset, amount[, market_id])

在操作令牌字段中使用裸 0x... 地址字面量；带引号的类似地址的字符串会触发 QUOTED_ADDRESS_LITERAL。
对于 Morpho doctor 就绪性检查，请明确设置钱包环境变量（优先使用 GRIMOIRE_WALLET_ADDRESS，回退使用 WALLET_ADDRESS）。
如果跨链运行处于等待状态，请使用 resume <runId> 继续（使用 --watch 轮询结算状态）。
切勿将密码/私钥放入智能体提示或内联命令赋值中。
对于试运行/实际施放，优先使用 keystore + --password-env 而不是 --private-key。
将 .grimoire/setup.env 视为明文秘密材料：仅保留在本地，不再需要时进行轮换/删除。
对于在项目树外部运行的命令，需要时设置 GRIMOIRE_SETUP_ENV_FILE=/abs/path/to/.grimoire/setup.env。

命令界面（核心）

init
setup
compile
compile-all
validate
simulate
cast
venues
venue
venue doctor
history
log
resume
wallet（generate、address、balance、import、wrap、unwrap）

关于简洁的命令签名和安全关键标志，请使用 references/cli-quick-reference.md。

运行时行为模型

一个运行时语义：先预览，仅对执行路径进行提交。
simulate 和 cast --dry-run 是仅预览流程。
当策略和运行时检查通过时，实际的 cast 可以提交不可逆操作。
simulate 支持显式的 --rpc-url，优先级为：--rpc-url -> RPC_URL_<chainId> -> RPC_URL。
第一阶段跨链执行使用双法术编排（--destination-spell），具有一个逻辑运行 ID 并支持恢复。

查询函数（价格 / 余额）

在获取数据时，始终优先使用 price() 和 balance() 而非咨询。 它们是确定性的、快速的，并且不需要 LLM 调用。

price(BASE, QUOTE) — 通过查询提供商获取实时代币价格（需要 Alchemy RPC URL）
balance(ASSET) — 通过 RPC 获取链上代币余额（任何 RPC URL）
切勿仅为了获取价格、余额或其他结构化数据而使用咨询（advise）

仅当任务需要 LLM 判断、推理或解释时才使用咨询。

咨询必须是明确的语句形式：x = advise advisor: "prompt" { ... }。
将咨询输出视为类型化合约；使用 output 强制执行模式。
每个咨询块都必须包含 timeout 和 fallback。
当咨询逻辑控制涉及价值转移的操作时，优先使用 validate --strict。
当从预览/试运行转向实际执行时，使用重放以确保确定性。
对于运行时调试，使用 --advisory-trace-verbose（非 JSON 模式）来流式传输详细的咨询跟踪信息。

场所元数据和快照

使用场所技能获取快照参数和市场元数据：

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

场所 CLI 输出的格式化策略：

对于自动化或嵌套负载，优先使用 --format json
对于人类可读的摘要，使用 --format table

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

🇺🇸English

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.

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
For CLI flag details — IMMEDIATELY read using the Read tool:
- references/cli-quick-reference.md
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

Installation Resolution

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

Global:
- npm i -g @grimoirelabs/cli
- command prefix: grimoire
No-install:
- command prefix: npx -y @grimoirelabs/cli
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.

Fast Start (Immediate Success Path)

Use this sequence before writing custom spells:

<grimoire-cmd> --help
<grimoire-cmd> setup (guided interactive execute onboarding)
<grimoire-cmd> validate spells/compute-only.spell
<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

Read syntax references first (mandatory rule above).
Author/update spell.
Run validate (use --strict for advisory-heavy spells).
Fix errors/warnings and re-run until validation passes.
Run simulate.
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
Before value-moving runs on EVM venues, verify endpoint and signer state with Foundry Cast quickchecks (chain-id, block-number, balance, nonce).

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

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

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

For Morpho collateral lifecycle, prefer explicit actions:

morpho_blue.supply_collateral(asset, amount[, market_id])
morpho_blue.withdraw_collateral(asset, amount[, market_id])

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

Command Surface (Core)

init
setup
compile
compile-all
validate
simulate
cast
venues
venue
venue doctor
history

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.

Query Functions (price / balance)

Always preferprice() and balance() over advisory for data fetching. These are deterministic, fast, and don't require LLM calls.

price(BASE, QUOTE) — live token price via query provider (requires Alchemy RPC URL)
balance(ASSET) — on-chain token balance via RPC (any RPC URL)
Never use an advisory (advise) just to fetch a price, balance, or other structured data

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/explanation/advisory-decision-flow.md

Weekly Installs

936

Repository

franalgaba/grimoire

GitHub Stars

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykWarn

Installed on

opencode936

gemini-cli936

github-copilot936

codex936

amp936

kimi-cli936

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

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

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

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

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

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

references/cast-cheatsheet.md

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

For advisory steps intended for deterministic execution, record and then use --advisory-replay <runId> in dry-run/live cast.

If spell includes irreversible actions, require cast --dry-run before any live cast.

Ask for explicit user confirmation before live value-moving cast.

For cross-chain mode, require explicit per-chain RPC mappings:

For commands run outside the project tree, set GRIMOIRE_SETUP_ENV_FILE=/abs/path/to/.grimoire/setup.env when needed.

wallet (generate, address, balance, import, wrap, unwrap)

docs/reference/cli.md

docs/reference/spell-syntax.md

docs/reference/grimoire-dsl-spec.md

docs/reference/compiler-runtime.md