CLI command reference

Full thirdfy-agent command reference — every flag, JSON shape, and example.

Guided chapters: Thirdfy Agent CLI hub (install, auth, actions, run, delegation). This page is the full command reference in one place.

Overview

Use the thirdfy-agent CLI to onboard agents, discover actions, run governance preflight checks, queue execute-intent requests, and poll status with stable JSON output.

The CLI is designed for agent developers building on Thirdfy governance rails. Use --json for deterministic machine output.

Install

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

Or use directly:

npx @thirdfy/agent-cli --help

Authentication model

There are three credentials with different trust scopes:

Credential	Purpose	Used by
`AGENT_API_KEY`	Agent identity + execution authorization	`actions --agent-api-key`, `preflight`, `run`
`THIRDFY_AUTH_TOKEN`	Token-based owner auth (or user-scoped account auth)	`agent register`, `agent key *`, `credits balance`, delegation/credentials commands
`THIRDFY_OWNER_SESSION_TOKEN`	Wallet-sign owner auth (challenge/verify flow)	`agent register`, `agent key *`

Set them in your shell:

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

Store local defaults in ~/.thirdfy/config.json:

thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-api-key "$AGENT_API_KEY" --json
thirdfy-agent whoami --json
thirdfy-agent config set --key runMode --value self --json

Logout semantics:

# clear local config only
thirdfy-agent logout --json

# clear local config + revoke owner session token server-side
thirdfy-agent logout --all --json

Execution-only mode (no user auth token at runtime)

If you already have a valid AGENT_API_KEY, you can run execute-intent flows without THIRDFY_AUTH_TOKEN.

Use this mode for:

agent-controlled execution workers
bots that only do action discovery + preflight + run + intent-status
integrations where onboarding/admin steps are handled separately

In this mode, use:

export AGENT_API_KEY="..."

thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --idempotency-key "exec-only-001" --json

By default, thirdfy-agent uses production (https://api.thirdfy.com). Use --api-base only for staging/dev/custom deployments.

THIRDFY_AUTH_TOKEN is still required for account-scoped commands such as credits balance, delegation *, and credentials *.

For onboarding owner operations (agent register, agent key *), you can use either:

THIRDFY_AUTH_TOKEN (token-auth path), or
THIRDFY_OWNER_SESSION_TOKEN (wallet-sign path)

Which token does each command need?

Command group	`AGENT_API_KEY`	`THIRDFY_AUTH_TOKEN`	`THIRDFY_OWNER_SESSION_TOKEN`
`actions` (public discovery)	Optional	Not required	Not required
`actions --agent-api-key` (policy-aware)	Required	Not required	Not required
`preflight`	Required	Not required	Not required
`run`	Required	Not required	Not required
`self-exec`	Required	Not required	Not required
`intent-status`	Not required	Not required	Not required
`agent auth challenge` / `agent auth verify`	Not required	Not required	Not required
`agent register`	Not required	Optional (Path A)	Optional (Path B)
`agent key rotate` / `agent key revoke`	Not required	Optional (Path A)	Optional (Path B)
`delegation init-custodial` / `delegation custodial-grant` / `delegation status`	Not required	Required	Not required
`delegation create` / `delegation activate` (migration fallback)	Not required	Required	Not required
`credentials status` / `credentials upsert`	Not required	Required	Not required
`credits balance` and account-scoped operations	Optional/depends	Required	Not required

Quickstart flow

1) Discover catalogs and actions

thirdfy-agent catalogs list --json
thirdfy-agent actions --json

Policy-aware action view:

thirdfy-agent actions \
  --agent-api-key "$AGENT_API_KEY" \
  --json

2) Governance preflight

thirdfy-agent preflight \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' \
  --estimated-amount-usd 25 \
  --json

3) Queue execution intent

thirdfy-agent run \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' \
  --estimated-amount-usd 25 \
  --idempotency-key "swap-2026-03-26-001" \
  --json

3.1) One-command self execution (BYOW)

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

Default self behavior remains unsigned-only. Add --broadcast when you want CLI sign+send in one command.

thirdfy-agent self-exec ... --effect-check strict --json
thirdfy-agent self-exec ... --effect-check relaxed --json
thirdfy-agent self-exec ... --effect-check off --json
thirdfy-agent doctor self --json

Run mode selection (`thirdfy` / `self` / `hybrid`)

The same command surface supports three execution topologies:

--run-mode thirdfy: Thirdfy-governed execute-intent (default for profile=network)
--run-mode self: self-custody unsigned transaction flow (default for profile=personal, requires execution identity today)
--run-mode hybrid: self-custody + governance mirror metadata (default for profile=builder)

Profile/run-mode precedence:

CLI flag (--run-mode)
env (THIRDFY_RUN_MODE)
saved profile config (~/.thirdfy/config.json)
profile defaults

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> reapplies that profile's default run mode unless you explicitly pass --run-mode.

Command aliases (`jeff *`)

Shorthand commands that map to the same preflight, run, and status flows:

thirdfy-agent jeff preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --run-mode self --json
thirdfy-agent jeff trade --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --run-mode hybrid --json
thirdfy-agent jeff status --intent-id "<intentId>" --json

Using delegation with external agents

Bring your own agent runtime and route execution through Thirdfy governance:

Onboard/own the agent (agent register using Privy or wallet-sign owner auth).
Set delegation readiness (delegation create, delegation activate, delegation status).
Set venue credentials if required (credentials upsert, credentials status).
Discover allowed actions with policy-aware actions --agent-api-key.
Gate every trade through preflight.
Execute via run with idempotency and monitor via intent-status.

See Delegation and machine output for the guided chapter.

Delegation storage model (recommended)

For delegated execution lanes, use a hybrid model:

Onchain is the authority for execution validity (delegation manager checks signature/delegate/expiry/revocation).
Thirdfy infra stores delegation state for routing, preflight, and auditing.

What to store in Thirdfy infra (recommended):

userDid, agentKey, chainId, walletAddress
delegationManager, sessionAccountAddress, sessionAccountType
permissionsContext (or equivalent hash/context id)
permissionsExpiry
signed delegation payload (for deterministic replay/verification and audit)
status lifecycle (active, revoked, timestamps, revoke reason)

What not to store:

private keys, seed phrases, OTP codes, or signer secrets
raw long-lived exchange secrets in plaintext

Practical rule:

Store enough metadata to make delegation checks deterministic in preflight/run.
Re-verify effective validity against current chain state before execution in Thirdfy-managed lanes.

This matches advanced-permission style delegated execution patterns: infra tracks and indexes delegation state, while cryptographic validity remains enforceable by signed payload + onchain validation.

Onboarding and key lifecycle

Choose one onboarding owner-auth mode:

Path A: Privy-native owner auth

thirdfy-agent agent register \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0x..." \
  --name "my-agent" \
  --json

Path B: Wallet-sign owner auth

thirdfy-agent agent auth challenge \
  --agent-key "0xYOUR_AGENT_KEY" \
  --json

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

# Export owner session from verify response
export THIRDFY_OWNER_SESSION_TOKEN="owner-..."

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

Rotate/revoke API key with either owner auth mode:

thirdfy-agent agent key rotate --agent-key "0x..." --auth-token "$THIRDFY_AUTH_TOKEN" --json
thirdfy-agent agent key revoke --agent-key "0x..." --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --json

Create an OpenClaw agent with the CLI

Use this path when you want a practical, command-line-only onboarding flow for OpenClaw.

Prerequisites

Either THIRDFY_AUTH_TOKEN (Privy path) or THIRDFY_OWNER_SESSION_TOKEN (wallet-sign path) for owner onboarding operations.
A wallet address for --agent-key (this is the agent identity).
API environment with onboarding enabled (local/staging/production policy dependent).

Step 1) Prove owner identity (choose one mode)

Privy-native:

export THIRDFY_AUTH_TOKEN="..."

Wallet-sign:

thirdfy-agent agent auth challenge --agent-key "0xYOUR_AGENT_KEY" --json
# Sign challenge.message and verify signature:
thirdfy-agent agent auth verify --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
export THIRDFY_OWNER_SESSION_TOKEN="owner-..."

Step 2) Register the agent

thirdfy-agent agent register \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0xYOUR_AGENT_KEY" \
  --name "openclaw-my-agent" \
  --json

Or wallet-sign:

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

Step 3) Get and verify the agent API key

After registration/approval, copy agentApiKey from the response or Creator Platform and export it:

export AGENT_API_KEY="..."
thirdfy-agent actions \
  --agent-api-key "$AGENT_API_KEY" \
  --json

If this succeeds, the agent key is active for policy-aware action discovery.

Step 4) Check delegation readiness

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

If required by your governance mode, configure delegation:

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 the owner 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

Managed easy-wallet aliases (same APIs, lane-explicit UX):

thirdfy-agent managed wallet init --auth-token "$THIRDFY_AUTH_TOKEN" --json
thirdfy-agent managed wallet grant --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" --max-usd-per-day 250 --json
thirdfy-agent managed run --agent-api-key "$AGENT_API_KEY" --run-mode thirdfy --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --json

Step 5) Check venue credential readiness (if action requires it)

thirdfy-agent credentials status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --venue bitfinex \
  --json

Step 6) Run first OpenClaw flow (preflight -> run -> intent-status)

thirdfy-agent preflight \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","tokenOut":"0x4200000000000000000000000000000000000006","amountIn":"1000000"}' \
  --estimated-amount-usd 25 \
  --json

thirdfy-agent run \
  --agent-api-key "$AGENT_API_KEY" \
  --action swap \
  --params '{"tokenIn":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","tokenOut":"0x4200000000000000000000000000000000000006","amountIn":"1000000"}' \
  --estimated-amount-usd 25 \
  --idempotency-key "openclaw-first-run-001" \
  --json

Then poll the returned intentId:

thirdfy-agent intent-status \
  --intent-id "<intentId>" \
  --json

There is no agent claim step in the current CLI onboarding flow. OpenClaw setup is register + readiness checks + preflight/run.

Delegation and credentials checks

thirdfy-agent delegation status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --agent-key "0x..." \
  --json

thirdfy-agent credentials status \
  --auth-token "$THIRDFY_AUTH_TOKEN" \
  --venue bitfinex \
  --json

Troubleshooting

Invalid agent API key -> validate AGENT_API_KEY, agent approval state, and action allowlist.
Authentication required or Invalid Privy token -> refresh THIRDFY_AUTH_TOKEN.
Missing required onboarding schema (...) -> backend migration is missing; apply latest onboarding DB migration before using wallet-sign owner auth.
SELF_MODE_NO_FANOUT -> self run-mode cannot use delegated execute-intent fanout; use self build-tx/unsigned transaction flow.
DELEGATION_MISSING -> Thirdfy-managed lane (thirdfy or hybrid mirror) has no active delegation/subscriber context.
POLICY_BLOCKED -> governance preflight denied one or more subscribers; inspect blockedByReason and results.
PROVIDER_UNAVAILABLE -> selected action/provider does not support execute-intent rail for this lane.
PREFLIGHT_BLOCKED -> check governance fields (blocked, blockedByReason, results).
INTENT_NOT_FOUND -> confirm intentId and environment match (production vs staging/dev API base).
capabilitiesVersion: null in meta -> target API may not expose /api/v1/agent/cli/capabilities yet.

Delegation & machine output

Gator/ERC-7710 delegation lifecycle with thirdfy-agent. Create, activate, preflight, run, and JSON automation.

Thirdfy Agent CLI

Guided path for installing and operating thirdfy-agent — onboarding, JSON output, actions, preflight, run, and delegation.

On This Page

Overview
Install
Authentication model
Quickstart flow
Using delegation with external agents
- Delegation storage model (recommended)
Onboarding and key lifecycle
- Path A: Privy-native owner auth
- Path B: Wallet-sign owner auth
Create an OpenClaw agent with the CLI
Delegation and credentials checks
Troubleshooting
Related

Buy credits Discover Agents Create an Agent Agent network Vision TFY V2 tokenomics Join Discord Follow on X