CLI reference

This document covers the regentx CLI for managing Regent agents on-chain.

Installation

npm install -g @regent/regentx
# or use without installing
bunx @regent/regentx

Commands

agent:init

Initialize a new Regent agent project.

regentx agent:init [options]

Options:

Option	Description	Default
--name <name>	Agent name	my-regent-agent
--chain <chain>	Default chain ID or name	-
--owner-wallet <id>	Wallet connector ID	local-eoa
--metadata-uri <uri>	Initial metadata URI	ipfs://TODO
--mode <mode>	Deployment mode	mock
-y, --yes	Accept defaults, overwrite	-

Example:

regentx agent:init --name "my-agent" --chain sepolia --mode onchain

Creates regent.config.ts and .env.example.

---

agent:create

Create a new agent via the factory contract.

regentx agent:create [options]

Options:

Option	Description
--name <name>	Override agent name
--metadata-uri <uri>	Override metadata URI
--owner-wallet <id>	Override wallet connector
--rake-bps <bps>	Rake in basis points (0-10000)
--initial-bond <wei>	Initial bond amount
--skip-identity	Don't register with ERC-8004
--dry-run	Show what would be created
--json	Output JSON

Example:

# Mock mode (development)
regentx agent:create --mode mock

# On-chain (production)
regentx agent:create --mode onchain --chain sepolia --rake-bps 500

# Dry run
regentx agent:create --dry-run

---

agent:status

Show the on-chain and ERC-8004 state of an agent.

regentx agent:status [agentId] [options]

Arguments:

Argument	Description	Default
agentId	Agent ID to query	From config

Options:

Option	Description
--json	Output JSON

Example:

# Status of agent from config
regentx agent:status

# Status of specific agent
regentx agent:status 11155111:42

# JSON output
regentx agent:status --json

---

agent:list

List all agents owned by a wallet.

regentx agent:list [options]

Options:

Option	Description	Default
--owner <address>	Override owner address	Current wallet
--limit <n>	Max agents to show	50
--json	Output JSON	-

Example:

regentx agent:list --limit 10
regentx agent:list --owner 0x1234... --json

---

Global Options

Available on all commands:

Option	Description
--config <path>	Path to config file
--chain <chain>	Chain ID or name
--rpc-url <url>	Override RPC URL
--wallet <id>	Wallet connector ID
--factory <address>	Factory contract address
--mode <mode>	Deployment mode: mock or onchain

---

Configuration File

The CLI reads from regent.config.ts (or .js, .json):

import { defineConfig } from '@regent/regentx';

export default defineConfig({
  version: 1,
  agent: {
    name: 'My Regent Agent',
    ownerConnectorId: 'local-eoa',
    metadata: {
      uri: 'ipfs://QmYourMetadataHash',
    },
    deploymentMode: 'mock',
    erc8004: {
      chainId: 11155111,
    },
    tokenomics: {
      rakeBps: 500,
      initialBond: 1000000000000000000n,
    },
    factory: {
      chainId: 11155111,
      address: '0x...',
    },
  },
  state: {
    agentId: '11155111:42',
    lastTxHash: '0x...',
  },
});

---

Chain Aliases

Supported chain names:

Alias	Chain ID
ethereum	1
base	8453
polygon	137
sepolia	11155111
base-sepolia	84532
polygon-amoy	80002
localhost	31337

---

Environment Variables

# Required for on-chain mode
PRIVATE_KEY=0x...

# Optional overrides
RPC_URL=https://...
FACTORY_ADDRESS=0x...

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid config or input

---

Examples

Development Workflow

# Initialize project
regentx agent:init --name "dev-agent"

# Create agent in mock mode
regentx agent:create --mode mock

# Check status
regentx agent:status

Production Workflow

# Initialize for production
regentx agent:init --name "prod-agent" --chain base --mode onchain

# Edit .env with PRIVATE_KEY

# Create on-chain
regentx agent:create

# Verify
regentx agent:status --json

CI/CD Integration

# Non-interactive creation
regentx agent:create \
  --mode mock \
  --name "ci-agent" \
  --metadata-uri "ipfs://QmTest" \
  --json