@taifoon/cli

Taifoon is a coordination layer for AI agents: one API that proves what happened on the chains it reads and settles the work agents buy and sell across marketplaces.

taifoon is the Taifoon coordination layer in your terminal. Use it to register agents and resources, work with collaborators on scoped keys, onboard coverage pools on every chain the layer maintains, and reach every marketplace the layer connects to. Every command is a call to the public API at coord.taifoon.dev/v1, so the layer meters it, and every command takes --json.

START HERE (no payment)

npm i -g @taifoon/cli
taifoon login --free                                   # a free key (tfr_free_…) in one call, no wallet; stored in your Keychain (no Keychain, e.g. Linux: shown once as export TAIFOON_API_KEY=…)
taifoon demand post "the keccak256 hash of \"hello world\""  # runs as written: a seller is hired, graded by code, settled on the devnet
taifoon demand status <dm_…> --watch                   # every step until it settles

The same three steps are the first tools of the MCP server at https://coord.taifoon.dev/mcp: taifoon_register, taifoon_post_demand, taifoon_demand_status.

The CLI never holds a private key. Anything that needs a signature is printed as an unsigned plan. You sign it in your own wallet or hardware wallet. On the Taifoon devnet (36927) you can also sign through kms-access, after you confirm. The CLI never sends anything on mainnet.

taifoon                                  # the interactive shell: tab completion and a status bar (network · session · key)
taifoon markets ls                       # every marketplace: live / devnet / discover-only / blocked, seller counts, lane
taifoon markets search "json normalize"  # one query across every marketplace at once
taifoon register agent 8453:95902 --check
taifoon pools ls                         # the 28 Moonbeam V3 pools on Base (not open yet) and the layer's pools
taifoon pools create devnet dUSDC 0x…    # an unsigned createPool plan on the devnet
taifoon collaborate invite my-team 0x…   # a scoped relayer key for a collaborator, stored in your Keychain
taifoon keys                             # your key and your tenant's keys: a menu on a terminal (standing, scopes, roll, revoke, seats)
taifoon stream --all                     # the live view: every sale as its agreement line + ⚖ legs, a format gap flagged inline
taifoon status                           # one screen: network, session, marketplaces, plans waiting for a signature

Facts, proofs and the MCP server

taifoon facts chain gnosis               # a chain: its registry entry, our contracts on it, its leaf in the superroot (JSON)
taifoon facts contracts [<chain>]        # contract addresses from the address registry, and the same-address set across chains
taifoon facts superroot                  # the superroot now, the verifier, and what "proven" means today
taifoon prove tx <chain> <tx>            # proven (with its v5 reference) · held awaiting_proof · failed · unproven; exit 0 only when proven
taifoon prove sale <sale_key>            # every settled and paid step of one sale, each proof asked of the layer again
taifoon act plan.json                    # an unsigned plan → the kms-access command a human runs with an MFA session (nothing runs)
taifoon mcp                              # the same reads and plans as a local MCP server on stdio

One capability table (src/capabilities.mjs) drives both the commands and the MCP server: every read and plan is a command and an MCP tool; everything that signs, sends, spends or mints a key is a command only. test/capabilities.alignment.test.mjs fails when the two drift. Add the server to Claude Code with claude mcp add taifoon -- npx -y @taifoon/cli mcp; tools that need a key read TAIFOON_API_KEY from the server's environment.

"Proven" today means consistent with the superroot the layer's producer served: the block folds into its chain's tree and the chain into the superroot. No superroot anchor is posted on any chain yet; taifoon facts superroot says so with every answer.

The agent session, your role, your energy

taifoon is one product: the shell, the commands, the MCP server and an agent session share one capability table, and your role decides what each of them offers you.

taifoon role                          # your role (admin, owner, delegate, member, viewer, public), scopes, outlets, what you own
taifoon usage                         # your energy in GRID: IN (reads, streams) and WRITE (sends), costs, earnings
taifoon resource list                 # your hosted resources; logs, metrics, stream, start | stop | restart | redeploy <id>
taifoon debug rpc 8453                # one verdict with findings: also protocol, order, envelope, project, resource
taifoon protocol stuck layerzero_v2   # any protocol leaf: order, stuck, paths, quote
taifoon stream                        # the live view: whole ids, a genome line per row, the master of every component, a live footer
taifoon stream --all --headers --stats --masters          # every lane + block headers per chain + the measures panel + the owners table
taifoon stream --chain base --protocol across_v3 --json   # filtered; NDJSON off a terminal; --short cuts hashes; --seal-key-file opens sealed bodies
taifoon owners                        # per key holder: the chains, protocols and products it masters, the seats it can claim
taifoon docs search "stream my contract events"   # the knowledge this release ships (the coord language, the skills)
taifoon workflow check <block,block,…> --grant devnet
taifoon ask "why is my solver not filling"        # one question to the agent
taifoon studio                        # the session: a line that is not a command goes to the agent

The agent's tools are the read, plan and debug rows your role allows; it never signs, sends or restarts: it proposes a taifoon command and you confirm it. Its model is yours to pick: taifoon model set anthropic with your own key (taifoon model key, kept in the Keychain; default model claude-opus-5-5), or taifoon model set taifoon for our metered lanes, billed to your key in GRID. --readonly keeps a session to reads. The online studio and cockpit run the same agent core.

Use Taifoon from your agent (skills + MCP)

One catalog of skills (skills/<name>/SKILL.md, start with skills/taifoon) and the MCP server at https://coord.taifoon.dev/mcp, packaged for each harness from this repository:

| Harness | Install | |---|---| | Claude Code | /plugin marketplace add taifoon-io/cli then /plugin install taifoon@taifoon (skills + the MCP server) | | Gemini CLI | gemini extensions install https://github.com/taifoon-io/cli (GEMINI.md + the MCP server) | | Cursor | copy .cursor/rules/taifoon.mdc into your project's .cursor/rules/; add the server to .cursor/mcp.json | | Codex and other Agent Skills harnesses | copy skills/taifoon (and the task skills you want) into the harness's skills folder; AGENTS.md is read as is | | Any MCP client | add https://coord.taifoon.dev/mcp (Streamable HTTP); the first tool, taifoon_register, returns a free key |

Reads work without a key; a free key (one per caller per day) covers repeat use; paid operations answer 402 with an x402 quote.

Install

With npm (Node.js 20 or later):

npm i -g @taifoon/cli        # installs the `taifoon` command
taifoon --version
npx @taifoon/cli network     # or run one command without installing

A standalone binary for macOS or Linux (arm64 or x64), no Node.js needed. The script picks the build for your machine, refuses it unless its SHA-256 matches the release's SHA256SUMS, and installs it into ~/.taifoon/bin without sudo:

curl -fsSL https://www.taifoon.io/install.sh | sh

With Homebrew:

brew install taifoon-io/tap/taifoon

The binaries are on this repository's releases. Each release's SHA256SUMS is signed with sigstore by the release workflow (.github/workflows/release.yml), with no stored key. To check a download yourself:

cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity https://github.com/taifoon-io/cli/.github/workflows/release.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS
grep taifoon-cli-<version>-<os>-<arch>.tar.gz SHA256SUMS | shasum -a 256 -c -

From a checkout of the repository, scripts/install.sh installs the packed package instead, and scripts/install.sh --link links it for development.

The shell

Running taifoon with no arguments opens a shell, the way mamba opens its console:

• The banner shows the layer, your session and your owner wallet.

• A status bar above each prompt shows the network (the layer's root, read every minute), whether you are a guest or which key you are using, your owner wallet, and how many plans are waiting.

• A leading / is optional, so /pools ls and pools ls are the same command.

• Tab completes commands, subcommands and marketplace ids.

• Piped stdin runs the same commands line by line, through the same dispatch:

  printf 'markets ls --status blocked\npools pilot\nexit\n' | taifoon --no-banner

• History is kept in ~/.taifoon/history. A line that contains a key (tfr_…) is never written to it.

Commands

51 commands, 154 usage lines. taifoon <command> --help prints one command's lines.

| command | what it does | |---|---| | login | store your /v1 relayer key in the Keychain or kms-access SSM (never a file), or be a guest; set your owner wallet | | taifoon login | paste your relayer key (hidden), checked with /v1/relayer/whoami, stored in the macOS Keychain | | taifoon login --key-stdin \| --from-keychain <svc[:acct]> \| --from-ssm <project/name> | other ways in; --store ssm:<project/name> keeps it in SSM | | taifoon login --guest | no key: the visitor budget | | taifoon login --free | get a free key in one call (POST /v1/register: no payment, nothing signed, no wallet) and store it: its own budget on demands and the gateways; --free 0x… labels it with a wallet | | taifoon login --owner 0x… | the wallet you sign owner steps with (the CLI prints the message; it never holds the key) | | logout | forget this profile’s key (Keychain entry deleted) | | taifoon logout | back to guest | | whoami | the session: layer, key prefix, validity, owner | | taifoon whoami | GET /v1/relayer/whoami with your key | | balance | what your key holds: its balance, its plan and the days left, the rate it is held to | | taifoon balance [--json] | GET /v1/access/key with your key | | buy | a balance (Buy GRID) or a monthly plan for your key, on Base, Arbitrum One, Arc, Monad or Robinhood Chain; nothing is sent from here | | taifoon buy <dollars> [--chain <id \| name>] | the quote for a balance: the transfer to send from your wallet and the message it signs | | taifoon buy <builder-99 \| team-199 \| protocol-299> [--chain <id \| name>] | the quote for a monthly plan: 30 days, paid up front, nothing renews by itself | | taifoon buy claim [<saved id>] --tx 0x… --signature 0x… [--chain <id>] | credit the payment to your key; the same claim again adds nothing | | taifoon buy plans | the three plans, what each includes and where they are paid | | taifoon buy products [--resource <access id>] | what is for sale as resource access: access id, seller, price, term | | taifoon buy access <product \| access id> [--recipient <identity>] | buy access once (also: taifoon buy ); your stream then carries what you bought | | taifoon buy grants [--resource <access id>] | your grants and entitlements; a seller’s roster with --resource | | keys | your key and your tenant's keys: standing, entitlements, grants, create, scopes, roll, revoke, team and seats (a menu on a terminal) | | taifoon keys | on a terminal: the menu; in a pipe: the standing and the keys | | taifoon keys show | your key's standing: tier, plan, scopes, caps, balance, entitlement, grants (GET /v1/access/key) | | taifoon keys ls | every key of your tenant and the recent changes (GET /v1/tenant/keys) | | taifoon keys create --label <text> [--scopes a,b] [--cap-day-grid n] [--cap-month-grid n] | a new key, straight into your Keychain, never printed | | taifoon keys update <prefix> [--label L] [--scopes a,b] [--cap-day-grid n] [--cap-month-grid n] [--per-minute n] | change what a key may call and spend | | taifoon keys roll [<prefix>] [--grace-hours h] | a new key in its place; the old one stops now or after the grace hours | | taifoon keys revoke <prefix> | stop a key at its next call | | taifoon keys seats | your Jev seat and the components you master | | stream | the live view: the pipe (and --all: every lane), aligned and coloured on a terminal, NDJSON in a pipe; stats; one envelope | | taifoon stream stats | the pipe now: envelopes by state and venue, acks, batches, dead and lost (GET /v1/pipe/stats) | | taifoon stream status <id> | one envelope: its state, attempts, carrier, ack and history (GET /v1/pipe/status/:id) | | taifoon stream live | the live view: the pipe (keyless: the public kinds), --all adds every coord lane, --headers the block headers per chain, --stats the measures panel, --masters the owner column and table; --chain --venue --kind --protocol --actor; --json NDJSON; what you see is your key's entitlement (a bought package opens whole ids and sealed bodies with --seal-key-file) (GET /v1/pipe/stream (SSE) + GET /v1/stream with --all) | | taifoon stream subscribe | stream.subscribe (GET /v1/pipe/stream (SSE)) | | match | the offers under a capability tag (translate, gpu-inference, …), cheapest first, each with its twig head and legs; claim one; the coverage | | taifoon match <tag> [--venue v] [--chain c] [--unit u] [--price-cap micro] [--limit n] [--json] | GET /v1/match/search: ranked within one canonical unit (--unit for the others it lists) | | taifoon match offers [--venue v] [--json] | GET /v1/match/offers: every venue, matching or missing: | | taifoon match demands <tag> [--json] | GET /v1/match/demands with your key | | taifoon match claim <venue> <index> [--units n] [--send] [--json] | POST /v1/match/claim with your key: the proof and the bundle | | taifoon match gpu-inference --model <id> [--json] | the inference listings of a model across providers: provider price + our reseller cut, cheapest first | | rpc | our RPC per chain: the gateway, WebSocket, proved reads and the price per 1M, with the rotation’s health now; your key in one curl | | taifoon rpc [--json] | every chain: healthy now, plain and proved price per 1M (USDC), WebSocket, the cheapest market price we know | | taifoon rpc <chain> [--json] | one chain (id, name or eip155:id): its card, endpoints and the best endpoints of the rotation now | | taifoon rpc key | how to read with your key: the gateway URL, the header and one curl (the key is never printed) | | taifoon rpc test <chain> | eth_blockNumber through the gateway with your key: block, latency and the λ step header | | demand | say what you need: the layer matches a seller, hires it, grades by code and settles it (devnet 36927) | | taifoon demand post "<need>" [--dry-run] [--label name] [--price-units n] | POST /v1/demands: the words map to a class by the layer’s rules; --dry-run keeps nothing and shows which pool would cover it and at what premium (quote only) | | taifoon demand post --class <id> --input '{…}' | a class and its input instead of words | | taifoon demand status <dm_…> [--watch [seconds]] [--timeout s] | every step the auto-match loop wrote; --watch re-reads until it ends | | taifoon demand ls [--state open\|settled\|…] [--limit n] | demands, newest first, and the classes a demand may name | | register | register an ERC-8004 agent (calldata → card → layer → enrich → probe → verdict) or a resource (λ: register → probe → list → gateway) | | taifoon register agent <chain>:<id> [--check] [--card url] [--enrich '{…}' --signature 0x…] | the onboarding walk; --check reads only | | taifoon register agent --uri <agentURI> --chain <id> | UNSIGNED register(agentURI) for a new ERC-8004 identity | | taifoon register resource <mcp\|a2a\|x402\|rpc\|gpu\|mech> <endpoint> [--check] | the λ resource walk and its gateway terms | | collaborate | teams: invite collaborators with their own scoped keys and budgets, see who did what, revoke | | taifoon collaborate invite <project> <member> [--scope read\|write] [--per-minute n] [--per-day n] | mint a scoped key (Keychain, never printed) | | taifoon collaborate ls | your projects and their keys, with today’s use | | taifoon collaborate activity <project> | who did what: calls per day + gateway steps | | taifoon collaborate revoke <key_prefix> [--project p] | stop a key at the next call | | taifoon collaborate handoff <project> <key_prefix> | put a collaborator key on the clipboard to hand over | | pools | Moonbeam protocol pools (read, quote, pilot) and generic pools on every chain we maintain (unsigned plans) | | taifoon pools ls [--chain base\|arc\|devnet] [--tenant moonbeam\|layer] | every pool and its state (/v1/pools/state) | | taifoon pools ls --live | every registry pool on Base, Arc and the devnet, read live: TVL, cover capacity, encumbered, premium, deposits, last covered job | | taifoon pools quote <seller> [--price-usdc n \| --tenant moonbeam --price-glmr n] [--chain] | the terms one job would settle on | | taifoon pools pilot | Moonbeam pools: not open yet on Base; pilot partners; the devnet | | taifoon pools factories [--chain] | every pool factory in the address registry | | taifoon pools networks | where a pool opens: every supported chain and line, read live (/v1/pools/networks) | | taifoon pools open --chain <c> --seller <0x\|agent id> [--asset] [--line] [--from] [--override] | UNSIGNED, simulated createPool from /v1/pools/open, with the pool it creates | | taifoon pools status --chain <c> --tx 0x… \| --seller 0x… | confirm an opened pool on the factory and in /v1/pools | | taifoon pools create <chain> <asset> <seller> [--line layer\|moonbeam\|v4\|v4-glmr] | UNSIGNED createPool plan | | taifoon pools deposit <pool> <amount> --receiver 0x… [--chain] | UNSIGNED approve + deposit plan (devnet default) | | taifoon pools redeem <pool> <shares> --owner 0x… [--chain] | UNSIGNED redeem plan (devnet default) | | taifoon pools plans [rm <id>] | the plans kept in ~/.taifoon/plans | | taifoon pools sign <plan> --via kms:<project> \| wallet | send a DEVNET plan after your yes (mainnet: never) | | markets | every marketplace and ecosystem: status, search across all, connect, hire | | taifoon markets ls [--status live\|devnet\|discover-only\|blocked] | status, seller counts and lane of every marketplace | | taifoon markets search <query> [--market id] [--limit n] | one query across every searchable marketplace | | taifoon markets connect <market> | what activates it (keys, MFA, decisions) + its zero-cost discovery | | taifoon markets hire <market> <ref> --task "…" [--send] [--grade] [--buyer 0x…] [--chain devnet\|base --cap-usdc n] | handshake → delivery → facts → your grade → settle plan | | metrics | what went through the layer: today vs yesterday vs 7 days (customers · ours), routes, customers (hashed), fees, funnel, network | | taifoon metrics [--day YYYY-MM-DD] [--watch [seconds]] [--json] | GET /v1/metrics + /v1/network; --watch re-reads on its period (≥ 5 s, default 30) | | act | hand an unsigned plan to kms-access: prints the command a human runs with an MFA session; never signs | | taifoon act <plan.json \| -> [--project <kms-access project>] | check the plan and print the kms-access send line (nothing is run) | | agents | search · readiness (the coordination layer, as JSON) | | taifoon agents search [--q \| --chain \| --skill \| --class \| --protocol \| --verdict \| --limit \| --offset] | the hireable sellers, filtered by words, chain, skill, class, protocol (GET /v1/agents/hireable) | | taifoon agents readiness <chain> <id> | one ERC-8004 agent: the readiness steps, the next one (GET /v1/agents/:chain/:id/readiness) | | ask | one question to the agent: it reads, measures and debugs through the layer’s own operations, and proposes any change for you to confirm | | taifoon ask "<question>" [--provider anthropic\|taifoon\|claude-cli] [--model id] [--readonly] [--max-turns n] | e.g. taifoon ask "why is my solver not filling" | | assurance | an unsigned assurance market plan | | taifoon assurance plan [--network \| --action \| --from \| --job] | an unsigned assurance market plan (POST /v1/assurance/plan) | | blocks | get · proof (the coordination layer, as JSON) | | taifoon blocks get <chain> <id> | one block as the proof plane holds it (latest | finalized | a number | a hash), with its proof (GET /v1/chain/:chain/block/:id) | | taifoon blocks proof <chain> <block> | the sibling path from one block to the superroot (GET /v1/root/proof/:chain/:block) | | catalog | every hireable agent the layer resells: seller price + our fee, cover, and one call to buy | | taifoon catalog [--status buy_now\|priced\|quote_on_request\|covered\|openable\|ready] [--class c] [--protocol p] [--q words] [--limit n] [--offset n] | GET /v1/catalog, paged | | taifoon catalog <cat_…> | one entry: price, cover, readiness, the buy call | | taifoon catalog --buy <cat_…> --input '{…}' \| --need "<words>" [--price-units n] [--label name] [--dry-run] | POST /v1/demands { catalog_id }: the loop hires that seller first, grades by code and settles (devnet 36927) | | cover | cover a job you bought elsewhere (Virtuals ACP, BitAgent, ERC-8183, x402, Olas): quote, buy (your wallet sends), policy status and claim | | taifoon cover quote --venue erc8183\|bitagent\|memo-acp --job <id> --buyer 0x… [--chain id] [--cap units] [--network devnet] | a signed quote on a job you funded | | taifoon cover quote --venue x402 --pay_to 0x… --amount units --nonce 0x… --sla s --buyer 0x… | before an x402 payment (the quote names its nonce) | | taifoon cover quote --venue olas-mech --mech 0x… --fee units --data_hash 0x… --sla s --buyer 0x… | before an Olas request (the quote names its data hash) | | taifoon cover buy <saved id> | the exact transactions to send from your wallet | | taifoon cover policy <policy id> [--network devnet] | status, claim window, the signed ending, the settle transaction | | taifoon cover ls --buyer 0x… [--network devnet] | your policies | | debug | rpc · protocol · order · envelope · project · resource (the coordination layer, as JSON) | | taifoon debug rpc <chain> | is a chain reachable: the RPC rotation for it and its header collector’s freshness, as one verdict with findings (GET /v1/rpc/:chain + GET /v1/root/chains) | | taifoon debug protocol <protocol> | is a protocol leaf healthy: how far its watcher lags, what is stuck and why (GET /v1/protocol/:protocol/stuck + /paths) | | taifoon debug order <protocol> <key> | why an order is where it is: its stages, its proof state, its stuck reason (GET /v1/protocol/:protocol/order/:key) | | taifoon debug envelope <id> | why an envelope was or was not delivered and acked: state, attempts, reasons, deadline (GET /v1/pipe/status/:id) | | taifoon debug project <id> | is a project wired: its webhook, its lane, its open and stuck orders (GET /v1/projects/:id) | | taifoon debug resource <id> | why one of your hosted resources misbehaves: its status, metrics and the error lines of its recent logs (GET /v1/hosting/resources (+ /metrics, /logs)) | | demo | the n8n flow, phase by phase, with each phase’s node operation, example workflow and link (demo n8n) | | taifoon demo n8n | replay the last tested run of the n8n buyer example: every phase read again from the live layer, the settlement re-checked on chain; no key, nothing written | | taifoon demo n8n --live [--need "<words>"] [--wallet 0x…] | run the flow on a new demand with your key, or a free key minted for this run (prefix shown only); devnet 36927, about 5 minutes | | deploy | deploy your own contract (plan · rehearse on a fork · your wallet sends · verify); never a Taifoon key | | taifoon deploy member-contract <plan\|rehearse\|send\|verify> --chain <id> --member <0x…> --artifact <file.json> [--ctor "constructor(address)" --args a,b] [--label name] [--rpc url] [--account keystore] [--own-signer] | your own contract, with your key's outlet grants | | docs | docs · search · get (the coordination layer, as JSON) | | taifoon docs | what this release knows: the coord language, the studio blocks, the skills (and, for an admin, the operator skills) (the knowledge shipped with this release) | | taifoon docs search <query> [--limit] | search the knowledge by words; the best documents with their best lines (the knowledge shipped with this release) | | taifoon docs get <topic> | one document by its topic (the knowledge shipped with this release) | | facts | chain and contract addresses from the address registry, and the superroot now, as JSON | | taifoon facts chain [<id \| name \| alias>] | one chain: its registry entry, our contracts on it, its leaf in the superroot (no chain: every chain) | | taifoon facts contracts [<chain>] [--system s] [--kind k] [--status live] | contract addresses, and the same-address set across chains | | taifoon facts superroot | the superroot: root, chains included, leaf count, the feed’s age, the verifier, what “proven” means today | | jobs | get · trail (the coordination layer, as JSON) | | taifoon jobs get [--ids] | up to 50 jobs by id, comma separated (GET /v1/jobs) | | taifoon jobs trail <id> | the lifecycle of one hire (GET /v1/hire/lifecycle/:id) | | judge | compose a grade; a 402 is returned as it is, never paid from here | | taifoon judge compose [--subject] | compose a grade; a 402 is returned as it is, never paid from here (POST /v1/judge/compose) | | mcp | the coordination layer as a local MCP server on stdio: the read and plan tools your role allows, the kms-access hand-off; nothing signs | | taifoon mcp [--tools] | serve MCP on stdin/stdout (TAIFOON_API_KEY in the environment for the tools that need a key); --tools lists them | | model | the agent’s model: show it, pick the provider (your Anthropic key or our metered lanes), store your key, run mamba locally | | taifoon model [set anthropic\|taifoon\|claude-cli] [--model id] | show or set the provider (default model claude-opus-5-5; taifoon lanes: nemotron; claude-cli: your local Claude Code) | | taifoon model key | store your Anthropic API key in the Keychain (asked hidden, never printed) | | taifoon model local up\|status\|logs\|down | mamba, the local agent runtime (open-mamba), when it is installed | | network | the network, live: sellers, chains, routes, gateway steps today; --pools: every registry pool read live | | taifoon network | GET /v1/network: sellers online, chains healthy, routes, gateway steps today | | taifoon network --pools | the pools section: every registry pool, TVL, cover capacity, encumbered, premium, deposits, last covered job | | new | scaffold a product card's starter (taifoon new [dir]) or the coord app (taifoon new --app ) | | taifoon new <card> [dir] | a product card's starter: keyless reads on the live host | | taifoon new --app <dir> | the coord app: fund · demo · deploy · verify | | taifoon new --contracts <dir> | a forge project on taifoon-contracts: the agent-job example, wired to the chain | | taifoon new --list | the cards on the shelf | | owners | who masters each chain, protocol and product (per key holder: what it masters, the seats it can claim), and claim the seat of what is yours | | taifoon owners [--kind \| --q] | who owns each protocol, chain, product and connector, and the seats their original owners can claim (GET /v1/owners) | | taifoon owners masters | every component (chain, protocol, product) with its master, the seat's claim state and the shares (GET /v1/owners) | | taifoon owners get <id> | one owner record: who holds it, its delegable seat, its claim state (GET /v1/owners/:id) | | taifoon owners claim | claim the seat of something you own (your protocol, your chain) with a proof; held until it is reviewed (POST /v1/owners/:id/claim) | | partners | the partner-bond lane on the devnet: the lane, a namespace or member read live, and the unsigned calls of an action (never sent) | | taifoon partners [--json] | GET /v1/partners: the contracts, the asset, the notice, the lane's states, transitions and payout order | | taifoon partners <ns> [--json] | one namespace (a label, hashed keccak256(utf8), or 0x… 32 bytes), live: owner, bond, caps, free, pending, members | | taifoon partners <ns> <member> [--json] | one member, live: cap, reserved, headroom, active, payout | | taifoon partners plan <action> --ns … [--json] | the unsigned calls and the cast lines to send them (actions: enrol, top_up, mint, set_cap, retire, request_withdraw, cancel_withdraw, withdraw, open_job, accept, submit, complete); amounts in dUSDC | | path | where a seller stands on the standard path (discovered … settled; readiness; the TEE rail) and the one next transition | | taifoon path [--json] | GET /v1/listings?view=path: sellers per stage by kind, ours apart from outside, and where they stop | | taifoon path <ls_…> [--json] | one listing: its stages, where it stops, who makes the next transition and the call | | taifoon path <chain>:<agentId> [--json] | one ERC-8004 agent: the readiness steps, the next one, and its TEE rail when it claims one | | phases | the five phases of the agreement as live metrics: the Phase 0 gate, the record, x402 capture, the n8n onramp, the pools, enterprise, reach by venue | | taifoon phases [--phase 0..5\|money\|reach\|board] [--venue <id>] [--json] | GET /v1/landscape/phases: one line per metric (phase, metric, value, outside, by, src, note) | | taifoon phases --fixture <dir> · --served | in a checkout of the layer’s source: the fold over pinned reads (offline) · read the served board only, never compute | | probe | talk to an outside agent now: MCP initialize + tools/list, A2A message/send, x402 — the harvester’s probe, run by the layer | | taifoon probe <https url> [--json] | one endpoint: does it answer, in which protocol, with which tools (nothing paid, no tool called) | | taifoon probe <chain>:<agentId> [--json] | an ERC-8004 agent: re-check the endpoints it published; its row is updated | | projects | projects · get (the coordination layer, as JSON) | | taifoon projects | the project boards: a project, its protocols, its orders as the standard steps, its webhook and lane (GET /v1/projects) | | taifoon projects get <id> [--limit] | one project board: orders with their steps, stuck orders, measured paths, counts (GET /v1/projects/:id) | | protocol | order · stuck · paths · quote (the coordination layer, as JSON) | | taifoon protocol order <protocol> <key> | one order of a protocol (a LayerZero message by guid, an Across deposit, an ERC-8183 job): every stage with its proof (GET /v1/protocol/:protocol/order/:key) | | taifoon protocol stuck <protocol> [--src \| --dst \| --since \| --limit] | the orders of a protocol past their expected next stage, each with its reason (GET /v1/protocol/:protocol/stuck) | | taifoon protocol paths <protocol> [--src \| --dst] | measured stage-to-stage times per chain pair (GET /v1/protocol/:protocol/paths) | | taifoon protocol quote <protocol> [--src \| --dst] | how long a delivery takes on a chain pair (median and p90 of measured orders) (GET /v1/protocol/:protocol/quote) | | protocols | every protocol the layer reads: its family, chains and contracts | | taifoon protocols | every protocol the layer reads: its family, chains and contracts (GET /v1/protocols) | | prove | the proof of a transaction or of a sale, read through coord and checked: proven, held awaiting_proof, failed | | taifoon prove tx <chain> <tx> | GET /v1/proof/tx/:chain/:tx: proven with its v5 reference, awaiting_proof, failed (reverted) or unproven | | taifoon prove sale <sale_key> [--summary <url \| file>] | every settled and paid step the sale run records for that key, each proof asked of coord again | | reach | the hireability gap by platform: the few hosts that carry most of it, the one fix each, and a draft message to its operator | | taifoon reach [--json] | the hosts that carry the gap, the check most of their agents fail, who clears it, the running share | | taifoon reach <host> [--json] | one host: its agents, the fix, a sample agent and a draft message to its operator (never sent) | | resource | your resources: add one (the onboarding walk, by connector type); your hosted ones: list, logs, metrics, a live stream, start / stop / restart / redeploy (role-scoped, metered, never a shell) | | taifoon resource add | add a resource by connector type (rpc-list, compute, agent:mcp, pay:x402 …): the same walk as register resource; collect, stream, workflow, contracts and vault point where they go (POST /v1/agents/probe + the gateway terms) | | taifoon resource list | your hosted resources (cells and agents on Taifoon hosting): status, URL, usage; an admin sees all (GET /v1/hosting/resources) | | taifoon resource logs <id> [--since \| --tail] | the recent logs of one of your resources (the layer checks your role on it and meters the read) (GET /v1/hosting/resources/:id/logs) | | taifoon resource metrics <id> | cpu, memory, restarts and GRID usage of one of your resources (GET /v1/hosting/resources/:id/metrics) | | taifoon resource stream | resource.stream (GET /v1/hosting/resources/:id/stream (SSE)) | | taifoon resource start | start one of your resources (held to its prepaid balance) (POST /v1/hosting/resources/:id/start) | | taifoon resource stop | stop one of your resources (POST /v1/hosting/resources/:id/stop) | | taifoon resource restart | restart one of your resources (never a shell: the layer checks your role on it and meters the call) (POST /v1/hosting/resources/:id/restart) | | taifoon resource redeploy | redeploy one of your resources from its current image (POST /v1/hosting/resources/:id/redeploy) | | role | your role (admin, owner, delegate, member, viewer or public), its scopes and outlets, what your key is bound to, and what you may do on a resource | | taifoon role [--resource] | your role (admin, owner, delegate, member, viewer or public), its scopes and outlets, what your key is bound to, and what you may do on a resource (GET /v1/access/role) | | send | send a record into the stream as an envelope of a kind (type → envelope, the lambda catalogue); --dry builds without sending | | taifoon send <record.json\|'{…}'\|-> --kind <kind> --to coord://<chain>/<venue>[/<agent>] [--entity e] [--order-key k] [--reply-to id] [--dry] | a write on your key (POST /v1/pipe/send): type → envelope → the stream; --dry builds and prints the envelope, sends nothing | | settle | an unsigned openJob / postVerdict plan | | taifoon settle plan [--chain_id \| --job \| --action] | an unsigned openJob / postVerdict plan (POST /v1/settle) | | studio | the agent session: the taifoon shell where a line that is not a command goes to the agent (the online studio runs the same) | | taifoon studio [--provider anthropic\|taifoon\|claude-cli] [--model id] [--readonly] | open the session; commands still work as commands; /reset forgets the conversation | | usage | your energy in GRID: IN (reads, streams) and WRITE (sends) per key and per project, agent or workflow it is bound to; what serving it cost; your earnings and vault | | taifoon usage [--window \| --scope] | your energy in GRID: IN (reads, streams) and WRITE (sends) per key and per project, agent or workflow it is bound to; what serving it cost; your earnings and vault (GET /v1/access/usage) | | venues | every venue the harvesters read: 7-day volume, buyers, failure rate, and which of our products answers what its buyers pay for | | taifoon venues [--json] | one line per venue: 7-day USD, payments, buyers, failure rate, the offers we hold there | | taifoon venues <id> [--json] | one venue: classes, paid-via, failure, and each target (class → our offer, or the gap) | | taifoon venues --targets [--json] | every target where one of our products fits, largest first | | workflow | check a studio workflow against the language: every step exists, steps connect, writes stay on outlets the grant holds | | taifoon workflow check <steps> [--grant \| --outlet \| --ends_at] | check a studio workflow against the language: every step exists, steps connect, writes stay on outlets the grant holds (the language’s workflow check) |

On a terminal every command prints its answer as aligned rows, tables and agreement lines; --json, or a pipe, prints the JSON exactly as the layer answered.

One command set. taifoon-sdk (the SDK's command line) runs these same commands: it is a thin entry over this package that adds only the verbs needing the SDK's own code (taifoon-sdk coord economies | workflow | vacuum | keygen | decode, taifoon-sdk demo).

taifoon markets ls prints the marketplace matrix: each marketplace's status, what the statuses mean, and what unblocks a blocked one. The list lives in src/markets.mjs.

Open a pool

A coverage pool stands behind one seller. Opening one is permissionless, deposits nothing and costs gas only. The layer builds and simulates the transaction; you sign it with your own wallet.

taifoon pools networks                                   # where pools open: Base 8453, Arc 5042, the devnet 36927
taifoon pools open --chain devnet --seller 0x…           # unsigned createPool, simulated, with the pool address it creates
taifoon pools sign <plan> --via wallet                   # devnet: the cast line to sign it with your wallet
taifoon pools status --chain devnet --tx 0x…             # the pool, confirmed on the factory and listed in /v1/pools

The same calls over HTTP: GET /v1/pools/networks, POST /v1/pools/open { chain_id, seller }, GET /v1/pools/open/{chain}/{tx}; over MCP: taifoon_pools_networks, taifoon_pool_open_plan, taifoon_pool_status. On Base and Arc the seller must meet the pool rule, or pass --override; the CLI prints a mainnet plan and never sends it. Moonbeam pools are not open: the layer answers closed_by_policy, and the CLI exits 3.

Keys and secrets

• A key is never stored in a plain file. ~/.taifoon/config.json (mode 0600) holds only where the key lives, its 10-character prefix and its label.
• Keys are written to the Keychain through security -i on stdin, and to SSM through kms-access's stdin, so a key never appears in a process list.
• TAIFOON_API_KEY in the environment overrides the stored key for one run.
• Collaborator keys come back from /v1 once. The CLI puts them in the Keychain and prints only the prefix.

Adding a command

Put one file in src/commands/ that exports { name, summary, usage, subs?, valued?, complete?, run(ctx, args) }. The command table, taifoon help, and the shell's completion pick it up with no other change. That is how taifoon metrics joins. ctx provides get and post against /v1 (each call is timed and listed under calls in --json output), json, emit, the palette p, the step renderer t, confirm, and the resolved key.

Tests

npm test                                         # recorded /v1 answers (test/fixtures), fakes for the Keychain and kms-access
TAIFOON_WEB=<the site's checkout> node --test test/parity.test.mjs   # the site's wizard engine and op table
node test/record-cli-fixtures.mjs                # re-record the /v1 answers

Licence

MIT. Jev and TypeSafe are products of TypeSafe AI, Inc., which does not endorse this package.