CLI

Terminal-based agent registration and deregistration workflows

Self Agent ID includes a cross-language CLI for registering and deregistering agents from the terminal. Available in TypeScript, Python, and Rust with identical command surfaces.

Install

TypeScript

npm install -g @selfxyz/agent-sdk
# or use npx:
npx @selfxyz/agent-sdk register init ...

Python

Rust

Registration Flow

The CLI uses a browser handoff pattern: the terminal creates a session, generates a URL, and the user completes the Self proof in their browser.

Step 1: Create Session

self-agent register init \
  --mode linked \
  --human-address 0xYourWalletAddress \
  --network mainnet \
  --out .self/session.json

Modes: linked, wallet-free, ed25519, ed25519-linked, smartwallet

The default network is mainnet, which requires a real passport scanned via the Self app. Use --network testnet for development — testnet also requires the Self app, but you can generate mock documents within the app instead of using a real passport.

Step 2: Open Browser Handoff

self-agent register open --session .self/session.json

Opens the handoff URL in the default browser. The user scans the QR code with the Self app.

Step 3: Wait for Completion

self-agent register wait --session .self/session.json

Polls the registration status until the Hub V2 callback confirms verification.

Step 4: Check Status

self-agent register status --session .self/session.json

Returns the current session state (pending, verified, failed).

Step 5: Export Credentials

self-agent register export --session .self/session.json

Outputs the agent address, agent key (bytes32), agent ID, and private key for use in your agent's environment.

Deregistration Flow

# Create deregistration session
self-agent deregister init \
  --mode linked \
  --human-address 0xYourWalletAddress \
  --network mainnet \
  --out .self/session-deregister.json

# Open browser for Self proof
self-agent deregister open --session .self/session-deregister.json

# Wait for completion
self-agent deregister wait --session .self/session-deregister.json

Ed25519 Registration

For agents that use Ed25519 keys instead of Ethereum wallets. Two modes are available:

Standalone Ed25519

Register an agent identified solely by its Ed25519 public key:

self-agent register init \
  --mode ed25519 \
  --ed25519-pubkey <hex> \
  --ed25519-signature <hex> \
  --network mainnet \
  --out .self/session.json

Ed25519 Linked to Human

Register an Ed25519 agent linked to a human's Ethereum address:

self-agent register init \
  --mode ed25519-linked \
  --ed25519-pubkey <hex> \
  --ed25519-signature <hex> \
  --human-address 0xYourWalletAddress \
  --network mainnet \
  --out .self/session.json

The --ed25519-signature is a hex-encoded signature over the session challenge, proving ownership of the Ed25519 private key. The --ed25519-pubkey is the hex-encoded 32-byte public key.

After init, the remaining steps (open, wait, status, export) are identical to the standard registration flow.

Agent-Guided Flow (Recommended)

For automated onboarding, your backend or agent runtime orchestrates the CLI commands and sends the handoff URL to the user:

1. Backend calls register init and stores session state

2. Backend calls register open and forwards URL to user UI

3. User completes browser proof flow

4. Backend runs register wait and records the returned lifecycle state

The agent-guided flow is the recommended integration pattern for services that onboard users programmatically. The CLI handles all the complexity of session management and proof verification.

Session Schema (v1)

The session file (.self/session.json) contains:

{
  "version": 1,
  "mode": "linked",
  "network": "mainnet",
  "humanAddress": "0x...",
  "agentAddress": "0x...",
  "agentPrivateKey": "0x...",
  "sessionId": "uuid",
  "handoffUrl": "https://selfagentid.xyz/cli/register?session=...",
  "status": "pending",
  "createdAt": "2026-02-22T..."
}

Network Flag

Value	Chain	Notes
mainnet (default)	Celo Mainnet (42220)	Real passports required
testnet	Celo Sepolia (11142220)	Mock documents only