@thirdfy/agent-cli

@thirdfy/agent-cli is the standalone command-line product for Thirdfy agent operations. Use it to:

• onboard with Privy email OTP (login email), onboarding help (help onboarding), auth diagnostics (doctor auth), and wallet discovery (wallet list)
• onboard and manage agent keys
• discover allowed actions (including policy-aware discovery)
• run governance preflight checks
• queue execute-intent requests with idempotency
• poll intent status with stable JSON output for automation
• choose execution topology with one switch: agent_wallet, self, hybrid, or thirdfy
• configure profile-driven defaults (personal, builder, network)

If you want the full developer docs, start here:

• Thirdfy Agent CLI hub (guided chapters)
• Thirdfy Agent CLI — full reference
• API Reference home
• LLM docs map (llms.txt)
• LLM full API snapshot (llms-full.txt)
• Provider docs index (repo)
• Action inventory and compatibility
• Command reference
• DogeOS quickstart (repo)
• Bitfinex CEX workflow (repo)
• Action onboarding standard
• Provider docs governance model
• Skill integration RFC

Install

npm install -g @thirdfy/agent-cli
thirdfy-agent --version --json

Run without global install:

npx @thirdfy/agent-cli --help

What's new in v0.2.2

• npm README cleanup — the registry homepage is user-facing again: one What's new section for the current version, full history in CHANGELOG.md (no multi-version release wall or maintainer publish steps on npm).
• Public docs validation — npm run validate:public-docs enforces README/npm surface rules before publish.

Older highlights (Commander routing, stricter flags): see CHANGELOG.md · GitHub Releases.

Quick start

export AGENT_API_KEY="..."
export THIRDFY_AUTH_TOKEN="..."
export THIRDFY_OWNER_SESSION_TOKEN="..."

thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
thirdfy-agent profile init --profile personal --json
thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --estimated-amount-usd 25 --json
thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --estimated-amount-usd 25 --json
thirdfy-agent intent-status --intent-id "<intentId>" --json

By default, the CLI targets production (https://api.thirdfy.com). Use --api-base (or THIRDFY_API_BASE) only for staging/dev/custom deployments.

Local API smoke

With Thirdfy API running locally (default http://127.0.0.1:3000):

export THIRDFY_API_BASE=http://127.0.0.1:3000
npm run e2e:local-api:smoke

Auth model

• AGENT_API_KEY: execution identity for preflight, run, self-exec, and policy-aware discovery.
• THIRDFY_AUTH_TOKEN: owner/account auth for onboarding and delegation commands.
• THIRDFY_OWNER_SESSION_TOKEN: wallet-sign owner session for onboarding and owner operations.

CLI precedence now supports login/config defaults:

1. explicit flag
2. environment variable
3. ~/.thirdfy/config.json (from thirdfy-agent login / config set)

Execution-only workflows can run with only AGENT_API_KEY after onboarding is complete.

Login / logout / config UX

# Email OTP first-run flow
thirdfy-agent login email [email protected] --json
thirdfy-agent login email [email protected] --code "<otp>" --accept-terms --key-name "My Agent" --json
thirdfy-agent whoami --json
thirdfy-agent wallet list --json
thirdfy-agent doctor auth --json

# Store auth defaults once
thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-api-key "$AGENT_API_KEY" --json

# Bootstrap scoped self identity + custody mode in one step
thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --run-mode self --custody-mode external --wallet-address "0xYOUR_AGENT_KEY" --json

# Inspect config
thirdfy-agent whoami --json
thirdfy-agent config set --key runMode --value self --json
thirdfy-agent config set --key custodyMode --value external --json

# Local-only logout (default)
thirdfy-agent logout --json

# Local clear + server owner-session revoke (if present)
thirdfy-agent logout --all --json

login email is a two-step headless-safe flow. Without --code, the CLI asks the Thirdfy API onboarding broker to send a Privy email OTP and exits with the exact next command. With --code --accept-terms, it stores a short-lived owner session in ~/.thirdfy/config.json, records linked EVM/Solana wallets plus the owner userDid when Privy returns them, stores a new agent API key when first-run bootstrap issues one, stores the returned executionWallets map, and defaults new solo profiles to agent_wallet. Email OTP is owner authentication only; fund the returned agent execution wallet for the target chain, not the linked owner embedded wallet. Use --not-interactive / --ni in automation so missing input fails fast instead of prompting — place --ni after the login email subcommand (for example thirdfy-agent login email [email protected] --code … --accept-terms --ni); a leading thirdfy-agent --ni login email … is parsed incorrectly because --ni would consume the login token as its value.

logout --all is provider-agnostic: it attempts owner-session revocation when a session token exists, then always clears local credentials.

Wallet-sign onboarding path

thirdfy-agent agent auth challenge --agent-key "0xYOUR_AGENT_KEY" --json
# Sign challenge.message with your wallet, then:
thirdfy-agent agent auth verify --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json

Use the returned session token:

thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json

Bootstrap onboarding (Model D)

# Start wallet challenge flow
thirdfy-agent bootstrap begin --agent-key "0xYOUR_AGENT_KEY" --json

# Complete bootstrap with session proof (recommended)
thirdfy-agent bootstrap complete --agent-key "0xYOUR_AGENT_KEY" --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --lane self --json

# Or use challenge/signature as exchange step to obtain session proof first
thirdfy-agent bootstrap complete --agent-key "0xYOUR_AGENT_KEY" --challenge-id "<challengeId>" --signature "0x..." --lane self --json

bootstrap complete supports both proof modes. Prefer session_token for operator-managed flows; use wallet_signature for direct wallet proof when verifier support is enabled.

Idempotency behavior (run)

• run auto-generates idempotencyKey by default when not provided.
• For deterministic retries across workers/restarts, pass your own stable --idempotency-key.
• preflight does not force idempotency keys.
• preflight --run-mode self is capability-aware:
  • if an action supports execute-intent validation, CLI uses executionLane=validation_only before building tx;
  • if an action advertises supportsExecuteIntent=false and supportsBuildTx=true, CLI routes preflight directly to build-tx.

Run modes and profiles

thirdfy-agent supports one command surface with four run modes:

• --run-mode agent_wallet -> managed solo wallet execution rail and fresh email-login default
• --run-mode self -> self-custody rail (build-tx flow)
• --run-mode hybrid -> self-custody + governance mirror metadata (default for profile=builder)
• --run-mode thirdfy -> Thirdfy-governed execute-intent rail (default for profile=network)

| Goal | Recommended mode | Why | | --- | --- | --- | | Fast solo managed-wallet trading | agent_wallet | Uses /execution-wallet + /execute; owner userDid comes from login config. | | BYOW signing and local custody | self | Keeps signing and broadcast on your wallet path. | | External wallet delegated execution | hybrid or thirdfy after delegation create/activate | Uses Gator/ERC-7710 authority from the user wallet to the Thirdfy/session executor. | | Publisher fan-out / subscriber execution | thirdfy | Uses delegated governance rail and active delegation_bindings. | | Self execution plus governance mirror checks | hybrid | Preserves local execution while emitting managed-lane mirrors. | | Managed wallet primary + governance mirror checks | hybrid --hybrid-wallet-mode agent_wallet | Uses managed wallet as primary hybrid path while still running Thirdfy mirror checks. |

Auth expectations by mode:

• self: requires execution identity (agentApiKey) today; keyless self lane is blocked with deterministic SELF_OPEN_DISABLED.
• hybrid: requires execution identity and governed mirror semantics (--hybrid-wallet-mode self|agent_wallet, default self).
• thirdfy: requires execution identity and delegated governance path.
• agent_wallet: requires execution identity and owner userDid, but does not require subscriber delegation when the owner identity matches the agent wallet/creator. Thirdfy credits/free quota still gate execution; Privy gas sponsorship only covers network gas when enabled.
• Hyperliquid Bridge2 setup is the Arbitrum exception to the Base-focused agent_wallet rule: Bridge2 credits the transaction sender. Pass --estimated-amount-usd as a top-level flag (not inside --params). When USDC sits on your linked email-login wallet (primaryEvmWallet) instead of the managed execution wallet, Thirdfy API returns FUND_AGENT_EXECUTION_WALLET / MANUAL_BRIDGE2_DEPOSIT_REQUIRED with fundedWallet and executionWalletAddress; move native Arbitrum USDC to executionWalletAddress and retry.
• custody mode defaults are profile-aware:
  • managed default for thirdfy
  • external default for self and hybrid
  • managed default for agent_wallet

Selection precedence:

1. --run-mode
2. THIRDFY_RUN_MODE
3. saved profile config (~/.thirdfy/config.json)
4. profile default (personal=agent_wallet, builder=hybrid, network=thirdfy)

Profile commands:

thirdfy-agent profile init --profile personal --json
thirdfy-agent profile use --profile builder --run-mode hybrid --json
thirdfy-agent whoami --json

profile use --profile <name> resets run mode to that profile default unless --run-mode is explicitly provided.

Framework Guidance

Use the same execution identities across frameworks, but choose the rail by who signs and who the agent acts for:

• Hermes agents: provision the Thirdfy profile and env before the Hermes dashboard/runtime starts, run thirdfy-agent doctor auth and doctor self during startup checks, prefer agent_wallet for the agent’s own managed wallet, and keep thirdfy for publisher/fanout or delegated external-wallet execution.
• OpenClaw agents: store Thirdfy credentials as runtime secrets, call thirdfy-agent actions --provider <id> before planning, use run --run-mode agent_wallet for own-wallet actions, use self only when OWS/local signing is configured, and switch to hybrid/thirdfy only after delegation readiness is confirmed.
• Claude Managed Agents: prefer MCP agentRun / walletExecute for solo managed execution, buildTx / walletSign for BYOW local signing, and executeIntent only for subscriber fanout or explicit validation-only mirror previews. The CLI remains useful for smoke checks and local operator recovery.

For all frameworks, treat agentApiKey as a hidden execution credential in secret storage, keep owner-session tokens short lived, and verify mode requirements with thirdfy-agent help onboarding --json.

One-command self execution (BYOW)

Use --broadcast with run --run-mode self to keep one deterministic command for build/sign/send:

thirdfy-agent run \
  --agent-api-key "$AGENT_API_KEY" \
  --run-mode self \
  --broadcast \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6,"chainId":8453}' \
  --json

The default run --run-mode self behavior is still unsigned-only (advanced users can sign externally).

Hybrid managed-wallet variant (agent_wallet + Thirdfy mirror):

thirdfy-agent run \
  --agent-api-key "$AGENT_API_KEY" \
  --run-mode hybrid \
  --hybrid-wallet-mode agent_wallet \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6,"chainId":8453}' \
  --estimated-amount-usd 25 \
  --json

Self lane effect-check controls:

# strict: fail if no observable token delta
thirdfy-agent self-exec ... --effect-check strict --json

# relaxed (default): retry/read balances, warn on mismatch, do not false-fail the tx
thirdfy-agent self-exec ... --effect-check relaxed --json

# off: skip post-trade token-delta verification
thirdfy-agent self-exec ... --effect-check off --json

Signer diagnostics:

thirdfy-agent doctor self --json

Swap amount contract (agent-safe)

For --action swap, CLI enforces an explicit amount unit contract:

• Provide exactly one of:
  • amountInRaw + tokenInDecimals (base units integer string), or
  • amountInHuman + tokenInDecimals (CLI converts to amountInRaw)
• Legacy amountIn is accepted only as raw integer compatibility input.
• Ambiguous payloads (both/none) fail with AMOUNT_UNIT_AMBIGUOUS.

Examples:

# Raw/base units
thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6,"chainId":8453}' --json

# Human units + decimals
thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInHuman":"1.5","tokenInDecimals":6,"chainId":8453}' --json

Jeff shorthand rail

Jeff-friendly aliases map directly to core commands:

• thirdfy-agent jeff preflight ... -> alias of preflight
• thirdfy-agent jeff trade ... -> alias of run
• thirdfy-agent jeff status --intent-id ... -> alias of intent-status
• thirdfy-agent prompt "<text>" -> captures prompt intent and suggests deterministic execution commands

Provider-specific workflows

Provider and venue guides are kept outside README so this page stays stable as integrations grow.

• Provider index: docs/providers/index.md
• Bitfinex runbook: docs/providers/bitfinex.md
• DogeOS runbook: docs/providers/dogeos.md

Command groups

• Discovery: catalogs list, actions (optional --provider, --chain-id; see docs/command-reference.md for trading vs earn vs prediction providers and case-insensitive matching)
• Execution: preflight, run, intent-status, jeff preflight, jeff trade, jeff status
• Polymarket: polymarket status, polymarket setup, polymarket dry-run
• Managed signer execution: wallet execute, wallet sign, wallet submit, agent run
• Profiles: profile init, profile use, profile show, whoami
• Onboarding: login email, help onboarding, doctor auth, wallet list, bootstrap begin, bootstrap complete, onboarding begin, onboarding complete, agent auth challenge, agent auth verify, agent register, agent key rotate, agent key revoke, developer bootstrap
• Governance readiness: delegation create, delegation activate, delegation status, credentials upsert, credentials status
• Delegation operations: delegation show, delegation inspect, delegation revoke
• Delegation execution helpers: delegation balance, delegation redeem
• Account: credits balance

CLI routing (Commander + runtime)

Since v0.2.1, bin/thirdfy-agent.mjs is a thin entrypoint. Routing lives in src/cli/manifest.mjs (Commander parseAsync); behavior and handler wiring live in src/runtime/. JSON envelopes, subcommand paths, and global flags (--json, --api-base, --run-mode, …) match 0.1.x for documented flows. Unknown flags now error instead of being silently ignored. Built-in Commander help is disabled so thirdfy-agent help onboarding keeps working.

Maintainers validating releases locally: npm run validate:release-preflight. After API deploy: THIRDFY_API_BASE=https://api.thirdfy.com npm run validate:live-api-capabilities.

Where to find what is supported

• Full command groups and usage map: docs/command-reference.md
• Live action inventory in your environment: docs/action-inventory-and-compatibility.md
• Provider runbooks and provider status: docs/providers/index.md

Delegation lifecycle (canonical)

Use create + activate as the default delegated execution lifecycle:

thirdfy-agent delegation create \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --owner-address "0xOWNER_WALLET" \
  --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
  --max-usd-per-day 250 \
  --json

# Sign the returned `data.delegation` payload in your wallet, then:
thirdfy-agent delegation activate \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --wallet-address "0xOWNER_WALLET" \
  --session-account-address "0xSESSION_ACCOUNT" \
  --delegation-manager "0xDELEGATION_MANAGER" \
  --delegation '{"delegator":"0x...","delegate":"0x...","authority":"0x...","caveats":[],"salt":"0x...","signature":"0x"}' \
  --signature "0xSIGNED_DELEGATION" \
  --json

thirdfy-agent delegation status \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --verify \
  --json

thirdfy-agent delegation inspect \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --verify \
  --json

thirdfy-agent delegation revoke \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --reason "user_revoked" \
  --json

thirdfy-agent delegation balance \
  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --json

thirdfy-agent delegation redeem \
  --run-mode thirdfy \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' \
  --estimated-amount-usd 5 \
  --json

--auth-token "$THIRDFY_AUTH_TOKEN" remains supported for all delegation commands, but owner-session token is preferred for least-privilege owner operations.

MetaMask custodial-compatible lifecycle (new)

thirdfy-agent delegation init-custodial \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --chain-id 8453 \
  --json

thirdfy-agent delegation custodial-grant \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
  --max-usd-per-day 250 \
  --json

The CLI keeps compatibility with legacy delegation create + delegation activate during migration.

delegation show is a direct alias to delegation status for gator-style operator ergonomics.

Managed easy-wallet command group:

thirdfy-agent managed wallet init --auth-token "$THIRDFY_AUTH_TOKEN" --json
# or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
thirdfy-agent managed wallet grant --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --token-address "0x..." --max-usd-per-day 250 --json
# or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
thirdfy-agent agent run --agent-api-key "$AGENT_API_KEY" --signer-method fanout_intent --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --json

Signer command model (managed + BYOW)

The CLI now supports the same signer primitives used by the MCP:

• wallet execute -> direct managed self-wallet execution (/api/v1/agent/execute)
• wallet sign -> unsigned tx packaging for BYOW signing flow
• wallet submit -> signed tx broadcast
• agent run -> signer router (managed_wallet_server, fanout_intent, byow)

Managed-self execution performs strict wallet preflight and returns deterministic blockers:

• blockedReason
• blockedStage
• executionWalletAddress

More docs

• OpenClaw CLI onboarding flow: docs.thirdfy.com/documentation/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli
• Creator platform (agent registration and keys): thirdfy.com/creator

Contributing

From a git clone of this repository:

npm ci
npm run validate:public-docs
npm test
npm run smoke:cli

Version history lives in CHANGELOG.md. Maintainer publish steps: docs/releasing.md.