CLI › Command Reference

ATF Command Reference

How to install the CLI, which commands to learn first, and where to find advanced operations. One page, no ambiguity.

Install & Run

The ATF CLI is published as @trucore/atf on npm. Node.js ≥ 18 is required.

Recommended

Install globally

Install once and use the short atf command everywhere.

Install globally

npm install -g @trucore/atf@1.5.1

Then run commands directly:

Example: first trade

atf trade

Alternative: Run with npx (zero install)

No installation required. npx downloads the pinned version on first run and caches it locally.

Run any command

npx @trucore/atf@1.5.1 <command>

Example: first trade

npx @trucore/atf@1.5.1 trade

Version pinned to 1.5.1 for reproducibility. Never use @latest.

When this documentation shows bare atf commands, it assumes either a global install or an equivalent alias.

Wrong package name?

If you see npm ERR! 404 for @trucore/atf-cli, use the correct name: @trucore/atf

Golden Path - Start Here

Four commands take you from first trade to verified receipt. This is the recommended order for every new user.

# Golden path - copy and run in order
npx @trucore/atf@1.5.1 trade          # 1. Try a protected trade (demo mode)
npx @trucore/atf@1.5.1 setup          # 2. Connect your API key
npx @trucore/atf@1.5.1 doctor         # 3. Diagnose your environment
npx @trucore/atf@1.5.1 verify <id>    # 4. Verify and share a receipt

First Protected Trade

npx @trucore/atf@1.5.1 trade

Guided workflow: route → classify → policy check → decide → execute → receipt.

Runs in demo mode by default. No wallet. No on-chain execution. Add --pretty for human-readable terminal output. In real mode it executes a protected trade on Solana mainnet, enforced by ATF policy.

Interactive Setup

npx @trucore/atf@1.5.1 setup

Writes your API key to ~/.atf/config.json. Run this to move from demo to real mode.

Interactive prompts guide you through configuration. Pass --api-key and --yes for non-interactive CI usage. No manual .env editing needed.

Environment Diagnostics

npx @trucore/atf@1.5.1 doctor

Checks config, RPC, wallet, Node.js version, and CLI health in one pass.

Run doctor whenever something seems off. It validates RPC reachability, active profile, wallet detection, and network selection. Add --verbose for full diagnostic detail.

Receipt Verification

npx @trucore/atf@1.5.1 verify <receipt-id>

Verify a receipt by ID or URL. Shareable proof of protection.

Recomputes the deterministic content hash locally and confirms integrity. Use it to share verified receipts with humans (--pretty) or feed verification results to automation.

Dual-Surface Output

Every ATF command produces output designed for two audiences at once:

Humans - clear, colored terminal messages with status indicators and next-step suggestions.
Bots & agents - structured JSON with machine-readable fields for automated decision-making.

Use --pretty or --format pretty for human-optimized output. Default JSON output is always machine-parsable.

Human-readable output

Operators

Clear terminal messages with color, status indicators, and actionable next steps. Use --pretty or --format pretty.

machine_summary

Bots / agents

Concise structured summary of the decision, suitable for automated parsing.

suggested_action

Bots / agents

Recommended next step the caller should take (e.g., EXECUTE, RETRY, ABORT).

suggested_command

Bots / agents

Ready-to-run CLI command for the suggested action - copy/paste or pipe directly.

This dual-surface design means a single CLI call can serve an operator monitoring a dashboard and a bot consuming JSON - no format switching required.

Advanced Command Groups

Beyond the golden path, the CLI offers specialized commands grouped by function. Use these when you need fine-grained control over specific operations.

Protected Trade & Simulation

Lower-level swap, simulation, and approval controls.

swapsimulateapprove

Deep dive →

Receipts & Transactions

Sign, send, check status, list and verify receipts.

tx signtx sendtx statusreceipts listreceipts verify

Deep dive →

Bot & Agent Operations

Protect, execute, and explain intents for bots and AI agents.

bot protectbot executebot explain

Config, Profiles & Secrets

Named profiles, per-profile config, and secrets separation.

profile createprofile switchconfig setconfig getsecret set

Deep dive →

Network & RPC

Endpoint configuration, latency testing, and devnet burner mode.

rpc setrpc pingburner

Deep dive →

Policy & Validation

Policy inspection, intent validation, and rule diagnostics.

policy showpolicy validatepolicy explain

Environment & Identity

Health checks, shell completion, identity, and listing.

doctorwhoamilscompletion

Deep dive →

Run npx @trucore/atf@1.5.1 --help for the full command list, or npx @trucore/atf@1.5.1 <command> --help for per-command usage and flags.

Performance & Execution Characteristics

The CLI is a lightweight Node.js binary with no heavy runtime dependencies. Commands start fast and produce deterministic, structured output.

Demo mode executes instantly with local simulation - no network calls.
Real mode performance depends on RPC latency and route complexity.
Policy evaluation is deterministic and runs before any on-chain execution.
All outputs are structured JSON by default, suitable for piping and automation.

Demo vs Real Mode

Demo Mode

Instant, local simulation. No API key or RPC required. Produces realistic receipts for integration testing.

Real Mode

Network-dependent. Policy evaluation runs first, then RPC simulation, then execution. RPC latency dominates total time.

In real mode, classification occurs before execution to avoid wasted compute. Typical SAFE routes observed under ~170k compute units in mainnet test matrices.

Next Steps

First Protected Trade – end-to-end walkthrough with code samples in Python, TypeScript, CLI, and OpenClaw.
CLI Documentation – full reference with all commands, flags, and response fields.
CLI Guides – step-by-step walkthroughs for common workflows.
Verification – what content_hash proves and how to use receipt verification in production.