id-cli

CLI for ID Chain agent name registration and management. All the features of idchain.world, from your terminal.

Setup

npm install
npm run build
npm link     # adds `id-cli` to your PATH

Create a .env file in the project directory:

PRIVATE_KEY=0x...

PRIVATE_KEY is required for write commands (register, transfer, set records, create subnames).

Supported Chains

All commands accept --chain (or -c). Defaults to base.

Flag	Chain
`base`	Base (8453)
`eth`, `ethereum`	Ethereum (1)
`op`, `optimism`	Optimism (10)
`arb`, `arbitrum`	Arbitrum (42161)
`sep`, `sepolia`	Sepolia (11155111)

You can also pass the numeric chain ID directly: --chain 8453.

Full Domain Paths

All commands accept a short label, a full domain path, or a linked .eth name:

id-cli info agent-0 --chain base
id-cli info agent-0.base.xid.eth
id-cli info agent-0.sep.xid.eth
id-cli info neo.agent-0.base.xid.eth

# Linked .eth names resolve to the linked agent automatically
id-cli info zeroperson.eth
id-cli info treo.zeroperson.eth
id-cli set-text zeroperson.eth description "My agent"
id-cli records zeroperson.eth

Dry Run

Add --dry-run to any write command to see the transaction proposal (contract, function, arguments, calldata) without executing.

id-cli register --chain base --dry-run
id-cli transfer agent-0 --to 0x1234... --dry-run
id-cli set-text agent-0 description "hello" --dry-run

JSON Output

All commands support structured JSON output for agent consumption:

id-cli info agent-0 --output json
id-cli explore --output json

When stdout is not a TTY (e.g., piped), JSON is the default. The envelope format:

{
  "status": "ok",
  "data": { ... },
  "metadata": { "chain": "Base", "chainId": 8453 }
}

Schema Introspection

Agents can discover all commands and their parameters programmatically:

id-cli schema                    # dump all commands as JSON
id-cli schema register           # describe a specific command
id-cli schema set-agent-endpoints

Commands

Register

Register the next available agent name. Names are permanent (one-time $3.50 USDC fee, no renewals).

id-cli register
id-cli register --chain sepolia
id-cli register --text description="My agent" --text url="https://example.com"
id-cli register --address 0x1234...
id-cli register --sublabel neo    # creates neo.<next-label>.base.xid.eth
id-cli register --referrer 0x...  # referrer gets 10% fee share

Transfer

Transfer ownership of a name.

id-cli transfer agent-0 --to 0x1234...
id-cli transfer agent-0.op.xid.eth --to 0x1234...

Info

Show details for a registered name, including owner, lock status, and records.

id-cli info agent-0
id-cli info agent-7 --chain base
id-cli info neo.agent-0.base.xid.eth
id-cli info agent-0 --brief              # skip records, just owner + lock status

Records

View all records for a name.

id-cli records agent-0
id-cli records agent-0 --chain op
id-cli records agent-0 --select text           # only text records
id-cli records agent-0 --select text,address   # text + address records

Set Text

Set a text record on a name.

id-cli set-text agent-0 description "My autonomous agent"
id-cli set-text agent-0 agent-context '{"services":[...]}'

Set Address

Set an address record on a name.

id-cli set-addr agent-0 0x1234...
id-cli set-addr agent-0 0x... --coin-type 0   # Bitcoin (coin type 0)

Set Content Hash

id-cli set-contenthash agent-0 0xe301...

Set Reverse Name (ENSIP-19)

Set the reverse resolution for your wallet address using the ENS Reverse Registrar. Supports the default L1 fallback reverse (reverse), Ethereum-specific reverse (addr.reverse), and chain-specific reverses per ENSIP-19.

# Default fallback reverse (L1 "reverse" namespace) — uses 0x283F...
id-cli set-reverse agent-0.base.xid.eth
id-cli set-reverse agent-0.base.xid.eth DEFAULT

# Ethereum-specific reverse (L1 "addr.reverse" namespace) — uses 0xa58E...
id-cli set-reverse agent-0.base.xid.eth ETH

# Chain-specific reverse — calls setName() on that chain's reverse registrar
id-cli set-reverse agent-0.base.xid.eth BASE
id-cli set-reverse agent-0.op.xid.eth OP
id-cli set-reverse agent-0.arb.xid.eth ARB

# Set reverse for a specific address (e.g., a contract you own)
id-cli set-reverse agent-0.base.xid.eth BASE --addr 0x1234...

Targets: DEFAULT (L1 fallback), ETH (L1 addr.reverse), BASE, OP, ARB, SEP.

Uses setName(string) on the ENS Reverse Registrar for your wallet, or setNameForAddr(address, string) with --addr.

Set Agent Endpoints (ENSIP-26)

Set agent endpoint records per the ENSIP-26 specification. All endpoints are set in a single setRecord transaction.

id-cli set-agent-endpoints agent-0 \
  --mcp https://agent.example.com/mcp \
  --a2a https://agent.example.com/a2a \
  --web https://agent.example.com \
  --context "Token swap agent for DeFi"

# Set only an MCP endpoint
id-cli set-agent-endpoints agent-0 --mcp https://mcp.example.com

# Clear specific endpoints
id-cli set-agent-endpoints agent-0 --clear mcp,a2a

# Clear all agent endpoints
id-cli set-agent-endpoints agent-0 --clear all

Supported protocols: mcp (Model Context Protocol), a2a (Agent-to-Agent), oasf (OpenAPI Service Format), web (Web interface).

Set Record (Bulk)

Set multiple records atomically in a single setRecord transaction.

id-cli set-record agent-0 \
  --text "description=My agent" "url=https://example.com" \
  --addr "60=0x1234..." \
  --contenthash 0xe301...

id-cli set-record agent-0 \
  --text "agent-endpoint[mcp]=https://mcp.example.com" \
  --text "agent-endpoint[a2a]=https://a2a.example.com"

Create Subname

Create a subname under an agent. Useful for building swarms where each worker gets its own identity.

id-cli create-subname neo --parent agent-0
id-cli create-subname worker-1 --parent agent-0 --chain base
id-cli create-subname scout --parent agent-0 --owner 0x1234...

List Subnames

id-cli list-subnames agent-0
id-cli list-subnames agent-0.base.xid.eth
id-cli list-subnames agent-0 --limit 100 --offset 50

Register ENS Name

Register a .eth name via the ENS two-step commit/reveal process. Requires ETH for the registration fee.

# Register on mainnet ENS (default for all chains except Sepolia)
id-cli register-ens alice

# Register on Sepolia ENS
id-cli register-ens alice --chain sepolia

# Custom duration (default: 1 year = 31536000 seconds)
id-cli register-ens alice --duration 63072000   # 2 years

# Register for a different owner
id-cli register-ens alice --owner 0x1234...

Link ENS Name

Link an existing .eth name to an agent ID. This is a three-step process:

Back-link: Set ens-link[name.eth] = "true" on the agent (agent's chain)
Forward link: Call setLink() on the linking resolver (L1/Sepolia)
Set resolver: Point the .eth name's resolver to the linking resolver (L1/Sepolia)

# Link alice.eth to a Base agent (all 3 steps)
id-cli link-ens alice.eth agent-0.base.xid.eth

# Link to an L1 Ethereum agent
id-cli link-ens alice.eth agent-0.eth.xid.eth

# Link to a Sepolia agent
id-cli link-ens alice.eth agent-0.sep.xid.eth

# Run a single step (useful if some steps are already done)
id-cli link-ens alice.eth agent-0.base.xid.eth --step 1   # back-link only
id-cli link-ens alice.eth agent-0.base.xid.eth --step 2   # forward link only
id-cli link-ens alice.eth agent-0.base.xid.eth --step 3   # set resolver only

For L1 agents (eth/sep), uses IDLinkedResolver (on-chain). For L2 agents (base/op/arb), uses IDUnifiedResolver (CCIP-Read).

Register Agent (ERC-8004)

Register on the ERC-8004 IdentityRegistry.

id-cli register-agent agent-0 --chain base
id-cli register-agent agent-0 --chain base --link   # also set ENSIP-25 record
id-cli register-agent agent-0 --mcp https://mcp.example.com

Link Agent (ENSIP-25)

Link an ERC-8004 agent to a name via ENSIP-25.

id-cli link-agent agent-0 12345 --chain base

Explore

List registered agent names.

id-cli explore
id-cli explore --chain op --limit 50
id-cli explore --owner 0x1234...

Mint USDC

Mint test USDC on testnets.

id-cli mint-usdc
id-cli mint-usdc --chain sepolia --amount 1000

Examples

Register an agent with ENSIP-26 endpoints and a swarm:

# Register on Base
id-cli register --text description="Coordinator agent"

# Set agent endpoints (ENSIP-26) in one transaction
id-cli set-agent-endpoints agent-0 \
  --mcp https://agent.example.com/mcp \
  --a2a https://agent.example.com/a2a \
  --context "Coordinator agent that manages DeFi operations"

# Create swarm workers
id-cli create-subname alpha --parent agent-0
id-cli create-subname bravo --parent agent-0

# Set records on a worker using bulk update
id-cli set-record alpha.agent-0 \
  --text "description=Alpha worker" \
  --text "agent-endpoint[mcp]=https://alpha.example.com/mcp"

Use JSON output for agent pipelines:

# Pipe structured data to jq
id-cli info agent-0 --output json | jq '.data.owner'

# Agent discovers CLI capabilities
id-cli schema set-agent-endpoints

Environment Variables

Variable	Required	Description
`PRIVATE_KEY`	For writes	Wallet private key (with 0x prefix)
`RPC_URL_BASE`	No	Custom RPC for Base
`RPC_URL_ETH`	No	Custom RPC for Ethereum
`RPC_URL_OP`	No	Custom RPC for Optimism
`RPC_URL_ARB`	No	Custom RPC for Arbitrum
`RPC_URL_SEPOLIA`	No	Custom RPC for Sepolia
`RPC_URL`	No	Global RPC override (applies to all chains)
`INDEXER_URL`	No	Override the default indexer API URL
`INDEXER_API_KEY`	No	API key for protected indexer endpoints (explore, by-owner)

RPC Configuration

The CLI ships with public RPC endpoints for each chain. These work for most use cases but may be rate-limited under heavy use. To use your own RPC provider, set the per-chain env var:

# In your .env file
RPC_URL_BASE=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
RPC_URL_ETH=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

Per-chain variables take priority over RPC_URL. If neither is set, the built-in public endpoint is used.

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.claude		.claude
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

id-cli

Setup

Supported Chains

Full Domain Paths

Dry Run

JSON Output

Schema Introspection

Commands

Register

Transfer

Info

Records

Set Text

Set Address

Set Content Hash

Set Reverse Name (ENSIP-19)

Set Agent Endpoints (ENSIP-26)

Set Record (Bulk)

Create Subname

List Subnames

Register ENS Name

Link ENS Name

Register Agent (ERC-8004)

Link Agent (ENSIP-25)

Explore

Mint USDC

Examples

Environment Variables

RPC Configuration

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages