Skip to main content

⌨️ CLI Reference

The Agent Wallet CLI provides a complete set of commands for wallet management, identity, ENS, and system operations. Every command supports positional arguments, interactive prompts, and scripting overrides.

Installation / Usage​

The CLI is included in the project root as cli.js:

node cli.js --help

Global Options​

These options can be appended to any command to alter its behavior globally:

FlagDescription
-v, --verboseEnable verbose HTTP logging (prints raw HTTP requests and responses)
-q, --quietSuppress all non-essential output (like spinners, prompts, and ASCII banners)
-j, --jsonOutput the final result strictly as raw JSON (ideal for piping into jq in scripts)
-h, --helpDisplay the dynamic help menu for the specific command

Environment Variables​

VariableDescription
AGENT_WALLET_APIBase URL of the API (default: http://localhost:3000)
AGENT_WALLET_API_KEYYour API key required for route authentication
AGENT_WALLET_RPC_URLOverride the managed RPC with a custom 'Bring Your Own' RPC endpoint

👛 Wallet Commands​

create​

Create a new agent wallet (generates a private key and encrypts it safely on the server).

  • Usage: node cli.js create <name> [chain]
  • Arguments:
    • <name>: The name of the AI agent owning the wallet (Required)
    • [chain]: The blockchain network (Optional, default: base-sepolia)
  • Options:
    • --chain=<chain>: Alternative named flag for chain.

import​

Import an existing EVM wallet via its private key.

  • Usage: node cli.js import <privateKey> <name> [chain]
  • Arguments:
    • <privateKey>: Hex private key string (with or without '0x') (Required)
    • <name>: Agent name to associate with (Required)
    • [chain]: The primary chain (Optional, default: base-sepolia)

balance (Alias: bal)​

Check the native token balance of a specific address.

  • Usage: node cli.js balance <address> [chain]
  • Arguments:
    • <address>: Wallet address (Required)
    • [chain]: The chain to check (Optional, defaults to wallet's primary chain)

balances (Alias: bals)​

Aggregates and checks the balance of the address across all supported chains concurrently.

  • Usage: node cli.js balances <address>
  • Arguments:
    • <address>: Wallet address (Required)

send​

Send ETH or native currency from one wallet to another. This routes through the Policy Engine.

  • Usage: node cli.js send <from> <to> <value> [chain]
  • Arguments:
    • <from>: Sender address (Required)
    • <to>: Recipient address (Required)
    • <value>: Amount in decimal ETH (e.g., 0.01) (Required)
    • [chain]: Blockchain network (Optional, default: base-sepolia)
  • Options:
    • -y, --yes: Skip the interactive confirmation prompt (Required for CI/CD scripting).

sweep​

Sweep (empty) all native funds from a wallet, automatically calculating and subtracting gas costs.

  • Usage: node cli.js sweep <from> <to> [chain]
  • Arguments:
    • <from>: Sender address (Required)
    • <to>: Recipient address (Required)
    • [chain]: Blockchain network (Optional, default: base-sepolia)
  • Options:
    • -y, --yes: Skip interactive confirmation.

estimate​

Estimate gas costs for a transaction without broadcasting it to the network.

  • Usage: node cli.js estimate <from> <to> [value] [chain]
  • Arguments:
    • <from>: Sender address (Required)
    • <to>: Recipient address (Required)
    • [value]: Amount to send in ETH (Optional)
    • [chain]: Blockchain network (Optional, default: base-sepolia)

tx​

Get the status, block number, and block explorer URL for a broadcasted transaction.

  • Usage: node cli.js tx <hash> [chain]
  • Arguments:
    • <hash>: The transaction hash (Required)
    • [chain]: Blockchain network (Optional, default: base-sepolia)

list (Alias: ls)​

List all wallets stored in the system (paginated view).

  • Usage: node cli.js list

chains​

List all supported mainnet and testnet blockchains configured in the service.

  • Usage: node cli.js chains

🔑 Identity Commands (ERC-8004)​

identity create​

Create an on-chain ERC-8004 identity for an agent, establishing granular capabilities.

  • Usage: node cli.js identity create <wallet> <name> [type]
  • Arguments:
    • <wallet>: Associated wallet address (Required)
    • <name>: Logical name of the identity (Required)
    • [type]: Agent type enum (assistant, autonomous, hybrid) (Optional, default: assistant)

identity list​

List all registered ERC-8004 identities in the system.

  • Usage: node cli.js identity list

identity get​

Fetch details about a specific agent identity record including its metadata capabilities.

  • Usage: node cli.js identity get <agentId>
  • Arguments:
    • <agentId>: The identity identifier (Required)

identity wallet​

Lookup and return the identity or array of identities bound to a specific wallet address.

  • Usage: node cli.js identity wallet <address>
  • Arguments:
    • <address>: Wallet address (Required)

🌐 ENS Commands​

ens list​

List all registered ENS records actively tracked by the Agent Wallet Service.

  • Usage: node cli.js ens list

ens get​

Resolve an ENS name (e.g., agent.eth) to its underlying 0x address.

  • Usage: node cli.js ens get <name>
  • Arguments:
    • <name>: Web3 ENS name (Required)

ens check​

Check network availability and pricing estimates for registering a new ENS name.

  • Usage: node cli.js ens check <name>
  • Arguments:
    • <name>: The target ENS name (Required)

⚙️ System Commands​

setup​

Pings the service health check endpoints and validates that your API key is functioning.

  • Usage: node cli.js setup
  • Options:
    • --init: Run the interactive one-command onboarding flow to automatically provision a scoped API key if you own the boostrap admin key.

demo​

Runs an end-to-end interactive demo connecting all services (Retrieves chains -> creates wallet -> checks balance -> creates identity).

  • Usage: node cli.js demo

interactive​

Launch the full interactive Terminal UI (TUI) menu system.

  • Usage: node cli.js interactive
╔═══════════════════════════════════════════════════╗
║   🦞  Agent Wallet CLI v0.3.1                    ║
║   Stripe for AI Agent Wallets                    ║
╚═══════════════════════════════════════════════════╝

? What would you like to do?
  👛 wallet - Manage wallets
  🔑 identity - Manage identities
  🌐 ens - ENS operations
  ⚙️ setup - Server setup
  🎬 demo - Run demo
  ❌ Exit

Security Best Practices​

  • Password Masking: Private keys are never shown in the terminal.
  • Confirmation Prompts: Destructive actions (send, sweep) require strict y/N confirmation unless -y is explicitly passed.
  • Sensitive Field Redaction: Passing --verbose will automatically redact API keys and private keys from the HTTP logs.