@thirdfy/agent-cli

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

• 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: thirdfy, self, or hybrid
• configure profile-driven defaults (personal, builder, network)

If you want the full developer docs, start here:

• Thirdfy Agent CLI docs
• API Reference home
• LLM docs map (llms.txt)
• LLM full API snapshot (llms-full.txt)
• DogeOS quickstart (repo)
• Action onboarding standard
• Skill integration RFC

Install

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

Run without global install:

npx @thirdfy/agent-cli --help

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"}' --estimated-amount-usd 25 --json
thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --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.

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

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

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

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

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

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

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.

Run modes and profiles

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

• --run-mode thirdfy -> Thirdfy-governed execute-intent rail (default for profile=network)
• --run-mode self -> self-custody rail (build-tx flow; default for profile=personal)
• --run-mode hybrid -> self-custody + governance mirror metadata (default for profile=builder)

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.
• thirdfy: requires execution identity and delegated governance path.

Selection precedence:

1. --run-mode
2. THIRDFY_RUN_MODE
3. saved profile config (~/.thirdfy/config.json)
4. profile default

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.

Swap amount contract (agent-safe)

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

• Provide exactly one of:
  • amountInRaw (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","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

Command groups

• Discovery: catalogs list, actions
• Execution: preflight, run, intent-status, jeff preflight, jeff trade, jeff status
• Profiles: profile init, profile use, profile show, whoami
• Onboarding: agent auth challenge, agent auth verify, agent register, agent key rotate, agent key revoke
• 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

Delegation lifecycle (canonical)

Use create + activate as the default delegated execution lifecycle:

thirdfy-agent delegation create \
  --auth-token "$THIRDFY_AUTH_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 \
  --auth-token "$THIRDFY_AUTH_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 \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --verify \
  --json

thirdfy-agent delegation inspect \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --verify \
  --json

thirdfy-agent delegation revoke \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --reason "user_revoked" \
  --json

thirdfy-agent delegation balance \
  --auth-token "$THIRDFY_AUTH_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"}' \
  --estimated-amount-usd 5 \
  --json

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.

More docs

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

Development

npm run validate:cli-contract-schemas
npm test
npm run smoke:cli

Release

npm version patch
npm publish --access public