CLI Skills

This page is the operational manifest for autonomous agents that need to drive synapse-sap from natural language. Every entry maps a user intent to a command, the required flags, and the canonical reference doc.

If you are a human, read Quickstart instead. This page is optimized for LLM grounding.

Identity

Decision rules

1. Read before write. agent info, escrow dump, discovery scan are always safe. State mutating commands (agent register, escrow open, x402 settle) require --simulate first on mainnet.
2. Always doctor run first. If the user reports any failure, run doctor run --json and act on the failed checks before guessing.
3. Prefer manifest form. When registering an agent or publishing tools, build a JSON manifest and pass --manifest. Inline flags are for ad hoc tasks only.
4. Use --json in scripts. Never parse human formatted output. Pipe to jq for filtering.
5. Persist artifacts. Use --save on every paid call so the user can replay or audit later.

Intent to command map

Setup and diagnosis

Agent lifecycle

Discovery

Escrow and payments

Tools and manifests

Output contract

Every command supports --json. JSON output is the source of truth for agents. Shape:

{
  "ok": true,
  "command": "agent.info",
  "data": { "...": "..." },
  "warnings": [],
  "elapsedMs": 412
}

On failure:

{
  "ok": false,
  "command": "agent.register",
  "error": { "code": "VALIDATION", "message": "...", "field": "name" },
  "elapsedMs": 12
}

Hard rules for agents

1. Never hard code an API key. Read from env or pass --rpc-url containing the key.
2. Never skip --simulate on mainnet for state mutating commands unless the user has explicitly approved it in the same turn.
3. Always pass --save on x402 call so the user has an artifact for audit and replay.
4. Always check ok in JSON output before reporting success.
5. If doctor run fails, surface the failed check verbatim and refuse to proceed.

Cross references

• SDK overview for programmatic equivalents.
• Core architecture for the on-chain model.
• Best practices: error handling for failure modes.