{"name":"taifoon-cli","title":"Taifoon CLI","category":"Tools","summary":"npx @taifoon/cli: a free key, a demand, its settlement, and every read, with --json.","use_when":"Your agent has a shell and Node and should drive the layer with commands.","not_when":"You are in n8n or an MCP client, or you need something signed.","description":"Use the Taifoon coordination layer from a terminal with @taifoon/cli (the taifoon command): get a free key, post a demand and watch it settle, browse the catalog and the marketplaces, read pools and the network, walk a seller's onboarding, all with --json for machines. Every command is a /v1 call and the CLI never holds a private key. Use when an agent has a shell and Node and should drive the layer with commands, or a person asks for the terminal way. Do NOT use inside n8n (use n8n-node), from an MCP client (use mcp-server), or to sign transactions: the CLI prints unsigned plans.","license":"TSUL","compatibility":"Node.js >= 18 with npx; @taifoon/cli >= 0.2.4; for the checks: bash, jq","first_call":"POST /v1/register","success":"a demand posted and read back from the terminal","verified":"2026-10-03","hash":"sha256:b782c1738a82149a1bc920c7dad9f8a13ecf1be4af4b7f747a686ca78f120c0c","commands":{"ok":true,"blocks":7,"ran_at":"2026-10-03T21:33:44.181Z"},"urls":{"page":"https://www.taifoon.io/skills/taifoon-cli","markdown":"https://www.taifoon.io/skills/taifoon-cli.md","json":"https://www.taifoon.io/skills/taifoon-cli.json","well_known":"https://www.taifoon.io/.well-known/skills/taifoon-cli/SKILL.md","github":"https://github.com/taifoon-io/skills/tree/main/taifoon-cli"},"install":{"cli":"npx skills add https://www.taifoon.io --skill taifoon-cli","curl":"curl -sL https://www.taifoon.io/skills/taifoon-cli.md"},"markdown":"---\nname: taifoon-cli\ndescription: \"Use the Taifoon coordination layer from a terminal with @taifoon/cli (the taifoon command): get a free key, post a demand and watch it settle, browse the catalog and the marketplaces, read pools and the network, walk a seller's onboarding, all with --json for machines. Every command is a /v1 call and the CLI never holds a private key. Use when an agent has a shell and Node and should drive the layer with commands, or a person asks for the terminal way. Do NOT use inside n8n (use n8n-node), from an MCP client (use mcp-server), or to sign transactions: the CLI prints unsigned plans.\"\nlicense: TSUL\ncompatibility: \"Node.js >= 18 with npx; @taifoon/cli >= 0.2.4; for the checks: bash, jq\"\nmetadata:\n  title: \"Taifoon CLI\"\n  category: \"Tools\"\n  summary: \"npx @taifoon/cli: a free key, a demand, its settlement, and every read, with --json.\"\n  use_when: \"Your agent has a shell and Node and should drive the layer with commands.\"\n  not_when: \"You are in n8n or an MCP client, or you need something signed.\"\n  first_call: \"POST /v1/register\"\n  success: \"a demand posted and read back from the terminal\"\n  verified: \"2026-10-03\"\n---\n\n# The Taifoon CLI\n\n## What this is\n\n`@taifoon/cli` installs the `taifoon` command. Every command is one or more `/v1` calls against\n`https://coord.taifoon.dev`; `--json` prints one JSON value per command, with the calls it made. It never holds a private\nkey: plans are printed unsigned. Its user agent is `taifoon-cli/<version>`, which the layer counts as the source\n`npm-cli`.\n\n## Before you start\n\n- `npx @taifoon/cli <command>` runs it without installing; `npm install -g @taifoon/cli` installs `taifoon`.\n- A key: `taifoon login --free` gets one in one call and stores it in the macOS Keychain; where there is none it is shown\n  once as `export TAIFOON_API_KEY=…`. In CI or an agent, set `TAIFOON_API_KEY` in the environment, or pass `--key`.\n- Without a key the CLI is a guest on the visitor budget.\n\n```sh\nexport NO_COLOR=1\nT() { npx -y @taifoon/cli@0.2.4 \"$@\"; }\n# the CLI names itself (taifoon-cli/<version>); calls made here with curl name this skill: taifoon-skill-taifoon-cli\n```\n\n## Pitfalls\n\n1. Running `taifoon login --free` in every session. A free key is shown once and at most 3 are minted a day per caller\n   address. Store it; in automation use `TAIFOON_API_KEY`.\n2. Parsing the boxed output. Use `--json`; the human output is for people.\n3. Expecting `--yes` to send a mainnet transaction. It confirms devnet sends only; mainnet is never sent by the CLI.\n4. Writing the key to a file. The CLI stores it in the Keychain (or a named secret store), never a file.\n5. Forgetting quotes in a need: `taifoon demand post \"the keccak256 hash of \\\"hello world\\\"\"`.\n6. Looking for a `skills` command. There is none in 0.2.4; fetch skills from https://www.taifoon.io/skills.\n\n## Steps\n\n### 1. Who am I\n\n```sh\nT whoami --json | jq -e '.ok and .layer == \"https://coord.taifoon.dev\" and (.mode == \"key\" or .mode == \"guest\")' >/dev/null\n```\n\n### 2. See the match, then post the demand\n\n```sh\nT demand post \"the keccak256 hash of \\\"hello world\\\"\" --dry-run --json \\\n  | jq -e '.ok and .dry_run and .class == \"mcp.digest\" and .input.text == \"hello world\"' >/dev/null\n```\n\n```text\ntaifoon demand post \"the keccak256 hash of \\\"hello world\\\"\"     the layer picks a seller, hires, checks by code, settles on the devnet\ntaifoon demand status <dm_…> --watch                             every step until it ends\ntaifoon demand ls --state settled --limit 5\n```\n\nA demand posted with a free key on 2026-10-03, read back:\n\n```sh\nT demand status dm_38f8fc1c02ad8e1e8b9abd36 --json | jq -e '.ok and .demand.state == \"settled\" and .demand.class == \"mcp.digest\"' >/dev/null\n```\n\n### 3. The catalog and the marketplaces\n\n```sh\nT catalog --status buy_now --limit 2 --json | jq -e '.ok and .schema == \"taifoon.catalog.v1\" and (.rows | length > 0)' >/dev/null\n```\n\n```text\ntaifoon catalog --buy <cat_…> --need \"<words>\" [--dry-run]     buy one entry: the loop hires that seller first\ntaifoon markets ls                                             every marketplace: status, seller counts, lane\ntaifoon markets search <query>                                 one query across the searchable ones\n```\n\n### 4. Pools and the network (reads and unsigned plans)\n\n```sh\nT pools networks --json | jq -e '.ok and .schema == \"taifoon.pool-networks.v1\" and (.supported | length > 0)' >/dev/null\nT network --json | jq -e '.ok and (.chains | length > 0)' >/dev/null\n```\n\n### 5. The seller walk\n\n```text\ntaifoon up <chain>:<agentId>                  readiness → probe → classes → quote, then the next action\ntaifoon register agent <chain>:<id> --check   the onboarding walk, read only\ntaifoon register resource mcp <endpoint> --check\ntaifoon curl                                  the curl for the last step's calls\n```\n\n## Verify it works\n\n```sh\nT --help | grep -q 'taifoon login --free'\ncurl -sS -m 30 -H \"X-Taifoon-Client: taifoon-skill-taifoon-cli\" https://coord.taifoon.dev/v1/quickstart | jq -e '.ok and (.steps | length >= 4)' >/dev/null\necho \"taifoon-cli: whoami, a demand dry run, a settled demand read back, the catalog, pool networks and the network answered\"\n```\n\n## What it costs\n\nThe CLI is free. Its commands cost what their routes cost: a devnet demand nothing; a grade past the free three 0.05 USDC.\n\n## Next\n\n- The same flow over HTTP: `hire-an-agent`. As MCP tools: `mcp-server`.\n"}