CLI reference

The yea command ships as @yea-protocol/cli: npx @yea-protocol/cli <command>, or yea <command> once it's installed globally (npm i -g @yea-protocol/cli). This is its own help text, generated from the source at build time:

yea — the protocol agents speak

get started
  yea install [--target claude-code,cursor,codex,gemini,vscode,windsurf,claude-desktop] [--local] [--with-principal]
                                           keys, a safe default policy, the MCP bridge and agent instructions (auto-detects tools)
  yea add <url>                         add a service for your AI tools (yea services · yea remove <url>)
  yea doctor                            check keys, grants, services and AI-tool registration
  yea uninstall [--target …]            remove YEA from your AI tools

identity
  yea init                              create your principal key and an agent key in ~/.yea
  yea whoami                            show public keys
  yea grant [caveats]                   principal → agent grant (saved; used automatically)
  yea grant-import <token>              save a grant issued to this machine's agent key (principal kept elsewhere)
  yea delegate <token> --to <key> [caveats]   attenuate a grant for a sub-agent
  yea inspect <token>                   decode a grant chain
  yea approve <pc1.code>                review and sign a one-time consent for one proposal

talk to a service  (url: yea://host:port · yeas://… · http(s)://…/yea · "stdio:cmd args")
  yea hello  <url>
  yea ask    <url> <capability> [key=value …]
  yea intent <url> <capability> [key=value …] [--goal "…"]
  yea commit <url> <proposal-id> <hash>
  yea undo   <url> <receipt-id>
  yea expand <url> <handle>
  yea do     <url> <capability> [key=value …]   intent → choose → commit, with consent prompts

try it
  yea test-drive [--model m] ["task"]  watch a real Claude model use YEA live (needs an Anthropic API key)
  yea demo                              narrated end-to-end demo (two services, consent, undo, sub-agents)
  yea examples [--port 7447] [--host]            serve the example calendar (7447), shop (7449) and billing (7451), trusting your principal

bridges
  yea mcp <url> [<url> …]               run an MCP server (stdio) exposing YEA services
  yea openapi <spec.json|url> [--base <url>] [--header "K: V"] [--port 7447] [--http 8080] [--preset github|petstore]
                                           serve any REST API as a YEA service (writes become proposals)

caveats: --svc <id> --can <pattern> --verbs ASK,INTENT --exp 24h --per 50USD --spend 200USD --risk low|medium|high
options: --budget <tokens> --json

Get started

yea install

Sets YEA up for your AI tools in one step (alias: setup):

1. creates an agent key in ~/.yea if there isn't one;
2. creates a principal key here only with --with-principal (or if you say yes at the prompt), warning that an agent with shell access could read it;
3. with a local principal and no grants yet, signs a starter policy: low-risk actions, up to 25.00 USD each and 100.00 USD in total, for 30 days, with anything else needing your approval;
4. registers the MCP bridge with each detected tool (or those in --target) and, for Claude Code, Codex, Gemini CLI and Cursor (--local), writes a marker-fenced YEA block of agent instructions.

Flag	Meaning
--target a,b	Only these tools: claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini
--local	Write project files (.mcp.json, .cursor/mcp.json, CLAUDE.md, AGENTS.md …) instead of user-level ones
--with-principal	Also create a principal key on this machine, for trying things out. For real use, issue the grant on another device and yea grant-import it

It never auto-approves YEA's tools in any client. Exactly what gets written where is on the integrations page.

yea uninstall

Removes the bridge and the YEA instruction blocks from each tool (or those in --target). Keys and grants in ~/.yea are left in place.

yea add, remove, services

yea add <url> sends HELLO to check the service, then adds it to ~/.yea/services.json. The bridge (yea mcp with no URLs) serves everything in that list. Restart your AI tool after adding.

yea doctor

Checks your node version, the agent key, whether the principal key is readable on this machine (a warning, since agents could read it too), each grant's scope, expiry and holder, each service's reachability, and which AI tools YEA is registered with. See Troubleshooting.

Identity and policy

yea grant signs a grant from the principal to the agent with these caveats:

Flag	Caveat	Example
--svc <id>	svc, repeatable	--svc cal.example.com
--can <pattern>	can, repeatable	--can "calendar.*"
--verbs A,B	verbs	--verbs ASK,INTENT
--exp <duration>	exp	--exp 24h (s, m, h, d)
--per <amount>	per, a per-action limit	--per 40USD
--spend <amount>	spend, a total limit	--spend 100USD
--risk <level>	risk, a ceiling	--risk low
--to <key>	the holder, if not your agent key	--to ed25519:…

yea grant-import <pg1.token> saves a grant that was issued to this machine's agent key on another device, so the principal key never touches the agent's machine.

yea delegate <token> --to <key> [caveats] narrows a grant for a sub-agent. yea approve <pc1.code> shows a proposal's real effects, re-checks its hash, asks for confirmation, and signs a one-time consent for it.

Environment

Variable	Meaning
YEA_HOME	Where keys, grants and services live (default ~/.yea)
YEA_PRINCIPAL_HOME	Where the principal key lives, if not YEA_HOME. Point it at another user's or device's storage
YEA_TRUST	Comma-separated principal keys that yea examples and yea openapi trust for writes (default: your own)
ANTHROPIC_API_KEY	For yea test-drive (or an ant auth login profile)

Try it

• yea test-drive ["task"] [--model <id>] runs a real Claude model (default claude-opus-5) against the example calendar and shop in your terminal, with a throwaway policy. Anything outside it asks you to approve. It fetches the Anthropic SDK on first use; the package itself has no runtime dependencies.
• yea demo is a narrated, scripted run with no API key needed.
• yea examples [--port 7447] [--host 0.0.0.0] serves the example calendar, shop and billing services (calendar on the port, shop on port + 2, billing on port + 4). Use --host 0.0.0.0 inside containers.

See the test drive walkthrough for more.

Bridges

• yea mcp [url …]: the MCP server your AI tools run. With no URLs it serves yea services.
• yea openapi <spec|url> [--base] [--header "K: V"] [--id] [--prefix] [--port] [--http] [--host] [--preset github|petstore]: serve a REST API as a YEA service. See Wrap any REST API.