@thirdfy/agent-cli 0.1.5 → 0.1.7

package/README.md

@@ -16,6 +16,9 @@ If you want the full developer docs, start here:
 - [API Reference home](https://docs.thirdfy.com/api)
 - [LLM docs map (llms.txt)](https://docs.thirdfy.com/llms.txt)
 - [LLM full API snapshot (llms-full.txt)](https://docs.thirdfy.com/llms-full.txt)
+- [DogeOS quickstart (repo)](./docs/dogeos-quickstart.md)
+- [Action onboarding standard](./docs/action-onboarding-standard.md)
+- [Skill integration RFC](./docs/skill-integration-rfc.md)
 
 ## Install
 
@@ -33,38 +36,64 @@ npx @thirdfy/agent-cli --help
 ## Quick start
 
 ```bash
-export THIRDFY_API_BASE="https://api.thirdfy.com"
 export AGENT_API_KEY="..."
 export THIRDFY_AUTH_TOKEN="..."
 export THIRDFY_OWNER_SESSION_TOKEN="..."
 
-thirdfy-agent actions --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --json
+thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
 thirdfy-agent profile init --profile personal --json
-thirdfy-agent preflight --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
-thirdfy-agent run --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
-thirdfy-agent intent-status --api-base "$THIRDFY_API_BASE" --intent-id "<intentId>" --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 and policy-aware action access (`actions --agent-api-key`, `preflight`, `run`)
-- `THIRDFY_AUTH_TOKEN`: Privy-native owner/account auth (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
-- `THIRDFY_OWNER_SESSION_TOKEN`: wallet-sign owner auth session (`agent register`, `agent key *`)
+- `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
+
+```bash
+# 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
 
 ```bash
-thirdfy-agent agent auth challenge --api-base "$THIRDFY_API_BASE" --agent-key "0xYOUR_AGENT_KEY" --json
+thirdfy-agent agent auth challenge --agent-key "0xYOUR_AGENT_KEY" --json
 # Sign challenge.message with your wallet, then:
-thirdfy-agent agent auth verify --api-base "$THIRDFY_API_BASE" --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
+thirdfy-agent agent auth verify --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
 ```
 
 Use the returned session token:
 
 ```bash
-thirdfy-agent agent register --api-base "$THIRDFY_API_BASE" --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json
+thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json
 ```
 
 ### Idempotency behavior (`run`)
@@ -81,6 +110,12 @@ thirdfy-agent agent register --api-base "$THIRDFY_API_BASE" --owner-session-toke
 - `--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`
@@ -98,6 +133,28 @@ 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:
+
+```bash
+# 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:
@@ -113,9 +170,87 @@ Jeff-friendly aliases map directly to core commands:
 - 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 upsert`, `delegation status`, `credentials upsert`, `credentials status`
+- 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:
+
+```bash
+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)
+
+```bash
+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: