ドキュメント/はじめに/CLI とスキル

この文書は英語のみです。サイトの他の部分は翻訳されています。

CLI and agent skill

Fiangshi has a command line built for AI agents and scripts, and an agent skill that teaches an agent when and how to use it. The commands talk to a running Fiangshi server, print plain text or JSON, and return the verdict as the exit code, so an agent can decide without parsing anything. Nothing here pays, signs or holds money.

Install the CLI

You need Node 20 or newer and a copy of this repository.

npm ci
npm run build
npm link

npm link puts a fiangshi command on your PATH. Without it, run node <repo>/dist/src/cli/index.js instead, or npx tsx src/cli/index.ts inside the repository.

The commands ask the Fiangshi server at FIANGSHI_URL (default http://127.0.0.1:8787). Start one with npm run dev, or point FIANGSHI_URL at a hosted copy.

Commands

Add --json to any command for machine output.

The older local-pipeline commands are still there: fiangshi check <url> [--json] [--explain] runs the whole check in-process (it needs the model keys, or fixture mode), and verify, index and lab work on local files.

Exit codes

Only an exact ALLOW gives 0. Anything Fiangshi does not recognise falls to 10.

Examples

fiangshi preview "https://api.cleave.fi/x402/gas"

BLOCK  api.cleave.fi/x402/gas
  source    null_payee rule at probe time
  rule      null_payee
  reason    zero_address: payTo 0x0000000000000000000000000000000000000000 is the zero address: funds sent there are unrecoverable
  pay to    0x0000000000000000000000000000000000000000
  receipt   <64-character receipt id>
  next      do not pay

The exit code is 20. In a shell script:

fiangshi preview "$URL" --json > verdict.json
case $? in
  0)  echo "ALLOW: paying" ;;
  20) echo "BLOCK: not paying"; exit 1 ;;
  *)  echo "REVIEW: asking a human"; exit 1 ;;
esac

The agent skill

The skill is one folder, skills/fiangshi/, with a SKILL.md in the open Agent Skills format: a name, a description that tells the agent when to use it, and instructions. It teaches the agent to check before every x402 payment, to treat REVIEW and no record as "ask", to quote the reason of a BLOCK, and to keep the receipt id. It works with the MCP tools, the CLI or plain HTTP, whichever the agent has.

Install it with the CLI. Each command copies the folder and nothing else, and refuses to overwrite an existing copy unless you add --force.

The folders above are the ones these tools use on the machine where this guide was written. If your tool keeps skills somewhere else, copy skills/fiangshi/ there by hand. Any agent that reads Agent Skills can use it.

Start a new session after installing. In Claude Code you can call it by name with /fiangshi, but you do not need to: the description makes the agent load it whenever a payment comes up. In Hermes, hermes skills list shows it.

For the best result, give the agent the skill and the tools: the skill says what to do, and the MCP server or the CLI does it. See Connect for the MCP setup in each tool.

Python client

For agents written in Python (LangChain, CrewAI, AutoGen, or the OpenAI, xAI and DeepSeek SDKs), there is a one-file client with no dependencies: clients/python/fiangshi_client.py, Python 3.9 or newer. Copy the file next to your code, or add clients/python to your path.

from fiangshi_client import Fiangshi

fs = Fiangshi()  # FIANGSHI_URL, default http://127.0.0.1:8787
v = fs.preview("https://api.cleave.fi/x402/gas")
if v.allowed:
    ...  # pay with your x402 client
elif v.blocked:
    print("do not pay:", v.rule, v.reason)
else:
    ...  # REVIEW or no record: ask a human

v.allowed is true only for an exact ALLOW; anything else is REVIEW. An unreachable server raises FiangshiError, which you should treat as "do not pay". The other calls are fs.payee(address), fs.verify_receipt(id) and fs.quote(url), which never pays.

For function calling with an OpenAI-compatible API, pass the ready-made tool definitions and hand each tool call back to the client:

reply = client.chat.completions.create(model=MODEL, messages=messages, tools=Fiangshi.tools())
for call in reply.choices[0].message.tool_calls or []:
    messages.append({"role": "tool", "tool_call_id": call.id, "content": fs.call_tool(call.function.name, call.function.arguments)})

The client also works as a command line, with the same exit codes as the Node CLI:

python clients/python/fiangshi_client.py preview "https://api.cleave.fi/x402/gas" --json

Its tests run with python -m unittest discover -s clients/python (set FIANGSHI_URL to include the ones that need a server), and npm test runs them against a real server whenever Python is installed.