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

Command	Description
`actp init`	Initialize ACTP in current directory
`actp pay`	Create & fund a payment (one-liner)
`actp tx`	Manage transactions (create, status, deliver, settle, cancel)
`actp balance`	Check USDC balance
`actp mint`	Mint test USDC (mock mode)
`actp config`	View and modify CLI configuration
`actp watch`	Stream transaction state changes
`actp simulate`	Dry-run commands without executing
`actp batch`	Execute multiple commands from a file
`actp time`	Manipulate mock blockchain time
`actp publish`	Publish agent config to IPFS + on-chain
`actp pull`	Pull on-chain config to local file
`actp diff`	Compare local vs on-chain config
`actp deploy:env`	Generate `ACTP_KEYSTORE_BASE64` for CI/CD
`actp deploy:check`	Scan repo for exposed secrets

Global Flags

Every command supports these output flags:

Flag	Description
`--json`	Machine-readable JSON output
`-q, --quiet`	Minimal output (just the essential value)
`-h, --help`	Display help for command
`-v, --version`	Output the version number

Exit Codes

Code	Meaning
`0`	Success
`1`	Error
`2`	Pending (used by `watch`)
`124`	Timeout (used by `watch`)

init

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

actp init [options]

Options

Flag	Type	Default	Description
`-m, --mode`	string	`mock`	Operating mode: `mock`, `testnet`, `mainnet`
`-a, --address`	string	—	Your Ethereum address
`-w, --wallet`	string	`auto`	Wallet type: `auto` (gas-free Smart Wallet) or `eoa`
`-f, --force`	boolean	`false`	Overwrite existing configuration
`--scaffold`	boolean	`false`	Generate a starter `agent.ts` file
`--intent`	string	`earn`	Agent intent: `earn`, `pay`, or `both`
`--service`	string	`my-service`	Service name
`--price`	string	`1`	Base price in USDC

What It Does

Creates .actp/ directory with config.json
Generates encrypted wallet keystore (non-mock modes)
Computes Smart Wallet address for gas-free transactions
Initializes mock state with 10,000 USDC (mock mode)
Reads AGIRAILS.md if present and pre-fills config
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

Argument	Required	Description
`<to>`	Yes	Provider address (recipient)
`<amount>`	Yes	Amount in USDC (e.g., `100`, `50.25`, `100 USDC`)

Options

Flag	Type	Default	Description
`-d, --deadline`	string	`+24h`	Deadline: `+24h`, `+7d`, or Unix timestamp
`-w, --dispute-window`	string	`172800`	Dispute 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]

Flag	Type	Default	Description
`-d, --deadline`	string	`+24h`	Deadline
`-w, --dispute-window`	string	`172800`	Dispute window in seconds
`--description`	string	—	Service description
`--fund`	boolean	`false`	Auto-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]

Flag	Type	Default	Description
`-s, --state`	string	—	Filter by state: `INITIATED`, `COMMITTED`, `DELIVERED`, etc.
`-l, --limit`	number	`50`	Limit 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]

Argument	Required	Description
`[address]`	No	Address 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>

Argument	Required	Description
`<address>`	Yes	Address to mint tokens to
`<amount>`	Yes	Amount 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

Flag	Type	Default	Description
`-t, --timeout`	string	`0` (indefinite)	Exit after timeout (seconds)
`-i, --interval`	string	`1000`	Polling interval (ms)
`--until`	string	—	Exit when transaction reaches this state

Exit Codes

Code	Meaning
`0`	Reached target state or terminal state
`124`	Timeout reached
`1`	Error

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]

Flag	Type	Default	Description
`-d, --deadline`	string	`+24h`	Deadline

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]

Argument	Required	Description
`[file]`	No	File with commands (one per line), or `-` for stdin

Options

Flag	Type	Default	Description
`--dry-run`	boolean	`false`	Validate commands without executing
`--stop-on-error`	boolean	`false`	Stop 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]

Argument	Required	Description
`[path]`	No	Path to `AGIRAILS.md` (defaults to `./AGIRAILS.md`)

Options

Flag	Type	Default	Description
`--skip-arweave`	boolean	`false`	Skip permanent Arweave storage (dev mode)
`--dry-run`	boolean	`false`	Show what would happen without executing

Workflow

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

Environment Variables

Variable	Description
`FILEBASE_ACCESS_KEY`	Filebase S3 credentials
`FILEBASE_SECRET_KEY`	Filebase S3 credentials
`ARCHIVE_UPLOADER_KEY`	Arweave 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]

Argument	Required	Description
`[path]`	No	Path to write (defaults to `./AGIRAILS.md`)

Options

Flag	Type	Default	Description
`-n, --network`	string	`base-sepolia`	`base-sepolia` or `base-mainnet`
`-a, --address`	string	—	Agent address (auto-derived from keystore if not set)
`--force`	boolean	`false`	Overwrite 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]

Argument	Required	Description
`[path]`	No	Path to `AGIRAILS.md` (defaults to `./AGIRAILS.md`)

Options

Flag	Type	Default	Description
`-n, --network`	string	`base-sepolia`	`base-sepolia` or `base-mainnet`
`-a, --address`	string	—	Agent address (auto-derived from keystore if not set)

Status Values

Status	Meaning	Action
`in-sync`	Local and on-chain match	None needed
`local-ahead`	Local changes not yet published	Run `actp publish`
`remote-ahead`	On-chain config is newer	Run `actp pull`
`diverged`	Configs have diverged	Run `actp publish` or `actp pull --force`
`no-local`	No local `AGIRAILS.md`	Run `actp pull`
`no-remote`	Not yet published on-chain	Run `actp publish`

Examples

# Check sync status
actp diff

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

# Just the status word
actp diff --quiet

deploy:env

Generate a base64-encoded keystore string for use in CI/CD environments. Reads your local .actp/keystore.json and outputs ACTP_KEYSTORE_BASE64 ready to paste into environment variables.

actp deploy:env [options]

Options

Flag	Type	Default	Description
`--keystore`	string	`.actp/keystore.json`	Path to keystore file
`--output`	string	`stdout`	Output: `stdout`, `dotenv` (append to `.env`)

Examples

# Print base64 keystore to stdout
actp deploy:env

# Append to .env file
actp deploy:env --output dotenv

# Use with custom keystore location
actp deploy:env --keystore /path/to/keystore.json

CI/CD Usage

Set ACTP_KEYSTORE_BASE64 and ACTP_KEY_PASSWORD as secrets in your CI/CD platform (GitHub Actions, Railway, Vercel, etc.). The SDK auto-detects these at runtime — no file needed on the server.

deploy:check

Scan your repository for exposed secrets, missing .gitignore entries, and deployment security issues. Recursively scans monorepos (up to depth 5).

actp deploy:check [path] [options]

Arguments

Argument	Required	Description
`[path]`	No	Directory to scan (defaults to current directory)

Options

Flag	Type	Default	Description
`--quiet`	boolean	`false`	Hide PASS and WARN results, show only FAIL
`--fix`	boolean	`false`	Auto-generate `.dockerignore` and `.railwayignore` if missing

What It Checks

Check	Severity	Description
`.env` in `.gitignore`	FAIL	Prevents committing secrets
`.actp/` in `.gitignore`	FAIL	Prevents committing keystore
`ACTP_PRIVATE_KEY` in code	FAIL	Hardcoded private keys
`.dockerignore` exists	WARN	Prevents secrets in Docker images
`.railwayignore` exists	WARN	Prevents secrets in Railway deploys
`keystore.json` in git	FAIL	Encrypted key in version control

Examples

# Full scan with all results
actp deploy:check

# CI mode — only show failures
actp deploy:check --quiet

# Auto-fix missing ignore files
actp deploy:check --fix

# Scan specific directory
actp deploy:check ./packages/my-agent

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

Installation — Set up your environment
Quick Start — First transaction end-to-end
SDK Reference — Programmatic API docs
Cookbook — Production-ready recipes

Need help? Join our Discord

Quick Reference​

Global Flags​

Exit Codes​

init​

Options​

What It Does​

Examples​

pay​

Arguments​

Options​

Examples​

tx​

tx create​

tx status​

tx list​

tx deliver​

tx settle​

tx cancel​

Examples​

balance​

Examples​

mint​

Examples​

config​

config show​

config set​

config get​

Examples​

watch​

Options​

Exit Codes​

JSON Output (NDJSON)​

Examples​

simulate​

simulate pay​

simulate fee​

Examples​

batch​

Options​

Batch File Format​

Security​

Examples​

time​

time show​

time advance​

time set​

Examples​

publish​

Options​

Workflow​

Environment Variables​

Examples​

pull​

Options​

Examples​

diff​

Options​

Status Values​

Examples​

deploy:env​

Options​

Examples​

deploy:check​

Arguments​

Options​

What It Checks​

Examples​

Common Workflows​

First-Time Setup​

Payment Flow​

Config Sync (CI/CD)​

Automated Testing​

Next Steps​

Quick Reference

Global Flags

Exit Codes

init

Options

What It Does

Examples

pay

Arguments

Options

Examples

tx

tx create

tx status

tx list

tx deliver

tx settle

tx cancel

Examples

balance

Examples

mint

Examples

config

config show

config set

config get

Examples

watch

Options

Exit Codes

JSON Output (NDJSON)

Examples

simulate

simulate pay

simulate fee

Examples

batch

Options

Batch File Format

Security

Examples

time

time show

time advance

time set

Examples

publish

Options

Workflow

Environment Variables

Examples

pull

Options

Examples

diff

Options

Status Values

Examples

deploy:env

Options

Examples

deploy:check

Arguments

Options

What It Checks

Examples

Common Workflows

First-Time Setup

Payment Flow

Config Sync (CI/CD)

Automated Testing

Next Steps