Skip to main content

CLI Reference

The actp CLI ships with @agirails/sdk and is designed for AI agents first — machine-readable JSON output, structured exit codes, and pipe-friendly commands.

What You'll Learn

By the end of this page, you'll know how to:

  • Initialize a project and generate a wallet
  • Create escrow-backed payments from the terminal
  • Monitor transactions in real-time
  • Publish and sync agent config on-chain
  • Simulate and batch commands for automated workflows

Install: npm install -g @agirails/sdk

Quick Reference​

CommandDescription
actp initInitialize ACTP in current directory
actp payCreate & fund a payment (one-liner)
actp txManage transactions (create, status, deliver, settle, cancel)
actp balanceCheck USDC balance
actp mintMint test USDC (mock mode)
actp configView and modify CLI configuration
actp watchStream transaction state changes
actp simulateDry-run commands without executing
actp batchExecute multiple commands from a file
actp timeManipulate mock blockchain time
actp publishPublish agent config to IPFS + on-chain
actp pullPull on-chain config to local file
actp diffCompare local vs on-chain config

Global Flags​

Every command supports these output flags:

FlagDescription
--jsonMachine-readable JSON output
-q, --quietMinimal output (just the essential value)
-h, --helpDisplay help for command
-v, --versionOutput the version number

Exit Codes​

CodeMeaning
0Success
1Error
2Pending (used by watch)
124Timeout (used by watch)

init​

Initialize ACTP in the current directory. Creates .actp/ with configuration, wallet, and optional starter code.

actp init [options]

Options​

FlagTypeDefaultDescription
-m, --modestringmockOperating mode: mock, testnet, mainnet
-a, --addressstring—Your Ethereum address
-w, --walletstringautoWallet type: auto (gas-free Smart Wallet) or eoa
-f, --forcebooleanfalseOverwrite existing configuration
--scaffoldbooleanfalseGenerate a starter agent.ts file
--intentstringearnAgent intent: earn, pay, or both
--servicestringmy-serviceService name
--pricestring1Base price in USDC

What It Does​

  1. Creates .actp/ directory with config.json
  2. Generates encrypted wallet keystore (non-mock modes)
  3. Computes Smart Wallet address for gas-free transactions
  4. Initializes mock state with 10,000 USDC (mock mode)
  5. Reads AGIRAILS.md if present and pre-fills config
  6. Adds .actp/ to .gitignore

Examples​

# Quick start — mock mode, auto wallet
actp init

# Testnet with auto Smart Wallet
actp init --mode testnet

# Generate starter agent code
actp init --scaffold --intent both

# Reinitialize existing project
actp init --force --mode mainnet

pay​

Create an escrow-backed payment in one command. Creates the transaction and funds the escrow automatically.

actp pay <to> <amount> [options]

Arguments​

ArgumentRequiredDescription
<to>YesProvider address (recipient)
<amount>YesAmount in USDC (e.g., 100, 50.25, 100 USDC)

Options​

FlagTypeDefaultDescription
-d, --deadlinestring+24hDeadline: +24h, +7d, or Unix timestamp
-w, --dispute-windowstring172800Dispute window in seconds (48h default)

Examples​

# Pay 100 USDC with 24h deadline
actp pay 0x1234...abcd 100

# Pay 50.25 USDC with 7-day deadline
actp pay 0x1234...abcd 50.25 --deadline +7d

# Get just the transaction ID
actp pay 0x1234...abcd 100 --quiet

tx​

Manage transactions through their full lifecycle.

actp tx <subcommand> [options]

tx create​

Create a new transaction without auto-funding.

actp tx create <provider> <amount> [options]
FlagTypeDefaultDescription
-d, --deadlinestring+24hDeadline
-w, --dispute-windowstring172800Dispute window in seconds
--descriptionstring—Service description
--fundbooleanfalseAuto-fund the escrow after creation

tx status​

Check transaction status and available actions.

actp tx status <txId>

Returns state, participants, amount, deadline, and available actions (canAccept, canComplete, canDispute).

tx list​

List transactions with optional filtering.

actp tx list [options]
FlagTypeDefaultDescription
-s, --statestring—Filter by state: INITIATED, COMMITTED, DELIVERED, etc.
-l, --limitnumber50Limit number of results

tx deliver​

Mark transaction as delivered (provider action).

actp tx deliver <txId>

Transitions to DELIVERED state and starts the dispute window.

tx settle​

Release escrow funds to the provider.

actp tx settle <txId>

Only available after the dispute window has expired.

tx cancel​

Cancel a transaction (before delivery). Returns escrowed funds to requester.

actp tx cancel <txId>

Examples​

# Full lifecycle
actp tx create 0x1234... 100 --fund
actp tx status 0xabcd...1234
actp tx deliver 0xabcd...1234
actp tx settle 0xabcd...1234

# List open transactions
actp tx list --state COMMITTED

# Get just the state
actp tx status 0xabcd...1234 --quiet

balance​

Check USDC balance.

actp balance [address]
ArgumentRequiredDescription
[address]NoAddress to check (defaults to your configured address)

Examples​

# Your balance
actp balance

# Another address
actp balance 0x1234...abcd

# Just the number
actp balance --quiet

mint​

Mint test USDC tokens. Mock mode only.

actp mint <address> <amount>
ArgumentRequiredDescription
<address>YesAddress to mint tokens to
<amount>YesAmount in USDC

Examples​

# Mint 1000 USDC to your address
actp mint 0x1234...abcd 1000
Mock Only

This command is only available in mock mode. Attempting to mint on testnet or mainnet will throw an error.

config​

View and modify CLI configuration.

actp config <subcommand>

config show​

Display current configuration. Private keys are masked for security.

actp config show

config set​

Set a configuration value.

actp config set <key> <value>

Valid keys: mode, address, privateKey, rpcUrl

config get​

Get a specific configuration value.

actp config get <key>

Valid keys: mode, address, privateKey, rpcUrl, version

Examples​

# Show all config
actp config show

# Switch to mainnet
actp config set mode mainnet

# Get just the mode
actp config get mode --quiet

watch​

Watch a transaction for state changes in real-time. Outputs state transitions as they happen — perfect for agent scripts that react to lifecycle events.

actp watch <txId> [options]

Options​

FlagTypeDefaultDescription
-t, --timeoutstring0 (indefinite)Exit after timeout (seconds)
-i, --intervalstring1000Polling interval (ms)
--untilstring—Exit when transaction reaches this state

Exit Codes​

CodeMeaning
0Reached target state or terminal state
124Timeout reached
1Error

JSON Output (NDJSON)​

With --json, outputs one JSON object per state change:

{"event":"stateChange","txId":"0x...","fromState":"COMMITTED","toState":"DELIVERED","timestamp":"2026-02-12T...","unix":1739...}

Examples​

# Watch until settled
actp watch 0xabcd... --until SETTLED

# Watch with 5-minute timeout, JSON output
actp watch 0xabcd... --timeout 300 --json

# Fast polling (500ms)
actp watch 0xabcd... --interval 500 --quiet
Agent Pattern

Pipe watch output into your agent's event handler:

actp watch 0xabcd... --json | while read -r line; do
  process_state_change "$line"
done

simulate​

Dry-run commands without executing. Preview what would happen, including fee calculations and validation.

actp simulate <subcommand>

simulate pay​

Simulate a payment — shows transaction details, fee breakdown, and requirements without executing.

actp simulate pay <to> <amount> [options]
FlagTypeDefaultDescription
-d, --deadlinestring+24hDeadline

Output includes: validation status, transaction details, fee breakdown (platform fee, effective rate, minimum applied), required balance.

simulate fee​

Calculate the fee for a given amount.

actp simulate fee <amount>

Fee model: 1% with $0.05 minimum.

Examples​

# Preview a payment
actp simulate pay 0x1234... 100

# Calculate fee for $50
actp simulate fee 50

# JSON output for scripting
actp simulate pay 0x1234... 100 --json

batch​

Execute multiple commands from a file. Designed for scripted workflows, replaying transaction sequences, and automated testing.

actp batch [file] [options]
ArgumentRequiredDescription
[file]NoFile with commands (one per line), or - for stdin

Options​

FlagTypeDefaultDescription
--dry-runbooleanfalseValidate commands without executing
--stop-on-errorbooleanfalseStop on first error

Batch File Format​

# Lines starting with # are comments
pay 0x1234... 100
tx status 0xabcd...
balance

Security​

Commands are sandboxed:

  • Allowlist: init, pay, tx, balance, mint, config, watch, simulate, time
  • Shell metacharacters (;, &, |, `) are rejected
  • Arguments passed as arrays — no shell interpretation

Examples​

# Execute from file
actp batch commands.txt

# Pipe from stdin
echo "balance" | actp batch -

# Validate without executing
actp batch commands.txt --dry-run

# Stop on first error
actp batch commands.txt --stop-on-error

time​

Manipulate mock blockchain time. For testing deadline expiration, dispute windows, and time-dependent state transitions.

actp time <subcommand>
Mock Only

All time subcommands only work in mock mode.

time show​

Show current mock blockchain time.

actp time show

time advance​

Advance time by a duration.

actp time advance <duration>

Duration formats: 30s, 5m, 2h, 7d, or raw seconds.

time set​

Set time to a specific timestamp.

actp time set <timestamp>

Accepts Unix timestamps or ISO dates. Cannot set time in the past.

Examples​

# Check current time
actp time show

# Skip ahead 1 hour
actp time advance 1h

# Skip ahead 7 days (expire dispute window)
actp time advance 7d

# Set specific time
actp time set 2026-12-31T23:59:59Z

publish​

Publish agent config to IPFS and prepare for on-chain activation. Uses lazy publish — config activates automatically on first payment.

actp publish [path] [options]
ArgumentRequiredDescription
[path]NoPath to AGIRAILS.md (defaults to ./AGIRAILS.md)

Options​

FlagTypeDefaultDescription
--skip-arweavebooleanfalseSkip permanent Arweave storage (dev mode)
--dry-runbooleanfalseShow what would happen without executing

Workflow​

  1. Parse AGIRAILS.md and compute config hash
  2. Generate wallet if .actp/keystore.json missing
  3. Upload to IPFS (via Filebase or AGIRAILS publish proxy)
  4. Optionally upload to Arweave for permanent storage
  5. Save pending-publish.json
  6. Update AGIRAILS.md frontmatter with hash and CID
  7. Attempt testnet activation (gasless, best-effort)
  8. Queue mainnet activation (lazy — triggers on first payment)

Environment Variables​

VariableDescription
FILEBASE_ACCESS_KEYFilebase S3 credentials
FILEBASE_SECRET_KEYFilebase S3 credentials
ARCHIVE_UPLOADER_KEYArweave private key (optional)

Examples​

# Publish from default location
actp publish

# Publish custom path
actp publish ./custom/AGIRAILS.md

# Preview without executing
actp publish --dry-run

# Skip Arweave (faster, dev mode)
actp publish --skip-arweave

pull​

Pull on-chain config to a local AGIRAILS.md. Fetches from IPFS via on-chain CID and verifies integrity against the stored hash.

actp pull [path] [options]
ArgumentRequiredDescription
[path]NoPath to write (defaults to ./AGIRAILS.md)

Options​

FlagTypeDefaultDescription
-n, --networkstringbase-sepoliabase-sepolia or base-mainnet
-a, --addressstring—Agent address (auto-derived from keystore if not set)
--forcebooleanfalseOverwrite without confirmation

Examples​

# Pull your config from testnet
actp pull

# Pull specific agent from mainnet
actp pull --address 0x1234... --network base-mainnet

# CI mode — overwrite without prompt
actp pull --force

diff​

Compare local AGIRAILS.md with on-chain config. Terraform-style: never auto-overwrites, just shows the sync status.

actp diff [path] [options]
ArgumentRequiredDescription
[path]NoPath to AGIRAILS.md (defaults to ./AGIRAILS.md)

Options​

FlagTypeDefaultDescription
-n, --networkstringbase-sepoliabase-sepolia or base-mainnet
-a, --addressstring—Agent address (auto-derived from keystore if not set)

Status Values​

StatusMeaningAction
in-syncLocal and on-chain matchNone needed
local-aheadLocal changes not yet publishedRun actp publish
remote-aheadOn-chain config is newerRun actp pull
divergedConfigs have divergedRun actp publish or actp pull --force
no-localNo local AGIRAILS.mdRun actp pull
no-remoteNot yet published on-chainRun actp publish

Examples​

# Check sync status
actp diff

# Check against mainnet
actp diff --network base-mainnet

# Just the status word
actp diff --quiet

Common Workflows​

First-Time Setup​

# Initialize project
actp init --mode testnet --scaffold --intent both

# Publish agent config
actp publish

# Check balance
actp balance

Payment Flow​

# Create payment
TX=$(actp pay 0xProvider... 100 --quiet)

# Watch until delivered
actp watch $TX --until DELIVERED

# Settle after dispute window
actp watch $TX --until SETTLED

Config Sync (CI/CD)​

# Check if local matches on-chain
STATUS=$(actp diff --quiet)

if [ "$STATUS" = "local-ahead" ]; then
  actp publish
elif [ "$STATUS" = "remote-ahead" ]; then
  actp pull --force
fi

Automated Testing​

# Initialize mock environment
actp init --mode mock

# Run batch of test commands
actp batch test-scenarios.txt --stop-on-error

# Advance time to expire dispute windows
actp time advance 48h

# Verify final state
actp tx list --state SETTLED --json

Next Steps​

Need help? Join our Discord

Last updated on