CLI Reference

The @enshell/cli provides 9 commands for interacting with the ENShell firewall from the terminal. It supports three wallet modes and includes interactive escalation handling.

npm install -g @enshell/cli

Version: 0.9.2 | Binary: enshell

Global Options

These flags apply to every command:

Flag Values Default Description
--wallet <mode> walletconnect, env, ledger walletconnect How to obtain an Ethereum signer
--key <name> string (none) Named key for env mode
--version flag Print version
--help flag Print help

Wallet Modes

WalletConnect (default)

Requires a prior enshell connect session. Session persists in ~/.enshell/wc-session.json.

enshell connect              # Establish session (shows QR code)
enshell register --id foo    # Uses saved session

When a command needs wallet signing, the spinner shows "approve in your wallet" as a hint.

Environment Private Key (--wallet env)

Reads from .env file (via dotenv):

# .env
ENSHELL_PRIVATE_KEY=0xYourPrivateKey

enshell register --wallet env --id my-agent --agent-wallet 0x... --spend-limit 1.0

Named Keys (--wallet env --key <name>)

For managing multiple wallets:

# .env
ENSHELL_PRIVATE_KEY_ALICE=0x...
ENSHELL_PRIVATE_KEY_BOB=0x...

enshell register --wallet env --key alice --id alice-trader --agent-wallet 0x... --spend-limit 0.5

The <name> is uppercased and appended to ENSHELL_PRIVATE_KEY_.

Ledger (--wallet ledger)

Not yet implemented. Throws an error directing you to use WalletConnect or env mode instead.

Environment Variables

Variable Default Description
ENSHELL_RPC_URL https://ethereum-sepolia-rpc.publicnode.com JSON-RPC endpoint
ENSHELL_PRIVATE_KEY (required for --wallet env) Default private key
ENSHELL_PRIVATE_KEY_<NAME> (required for named keys) Named private key
ENSHELL_CONTRACT_ADDRESS SDK default for Sepolia Override contract address

Commands

enshell connect

Establish a WalletConnect session.

enshell connect

Displays a QR code in the terminal. Scan with any WalletConnect-compatible wallet (MetaMask, Rainbow, Ledger Live, etc.). Also prints the raw WalletConnect URI for manual pasting.

If a valid session already exists, returns the connected address immediately.

Requires signer: No (creates the session)

enshell disconnect

Clear the saved WalletConnect session.

enshell disconnect

Disconnects the active session and wipes ~/.enshell/wc-session.json.

Requires signer: No

enshell register

Register a new AI agent on the firewall.

enshell register \
  --id <agentId> \
  --agent-wallet <address> \
  --spend-limit <ethAmount> \
  [--targets <address> [<address> ...]]
Option Required Description
--id <agentId> Yes Unique agent identifier
--agent-wallet <address> Yes Agent's Ethereum address
--spend-limit <limit> Yes Max spend in ETH
--targets <addresses...> No Allowed target addresses (variadic)

Creates the agent on-chain, creates ENS subdomain {id}.enshell.eth, and posts to relay.

Requires signer: Yes

enshell protect

Submit an action through the firewall with encryption and CRE analysis.

enshell protect \
  --id <agentId> \
  --target <address> \
  --value <ethAmount> \
  --instruction <text> \
  [--data <hex>]
Option Required Default Description
--id <agentId> Yes Agent identifier
--target <address> Yes Target contract/EOA
--value <eth> Yes ETH value
--data <hex> No "0x" Transaction calldata
--instruction <text> Yes Human-readable instruction

Two-phase execution:

Phase 1 -- Submit: Encrypts instruction, stores on relay, submits on-chain. Prints action ID and tx link.

Phase 2 -- Wait: Polls for CRE resolution. Three outcomes:

  • APPROVED -- Prints success message
  • ESCALATED -- Displays full Claude analysis, prompts Approve this action? (y/n), signs approve/reject
  • BLOCKED -- Displays analysis, exits

Escalation Display

When the CRE escalates, the CLI renders:

ESCALATED - Score: 45.2 / 100

Agent: my-agent.enshell.eth
Target: 0x7a25...488D
Instruction: Swap 0.05 ETH for USDC on Uniswap V2 Router

Reasoning:
The target address matches the well-known Uniswap V2 Router...

? Approve this action? (y/n)

Answering y or yes calls approveAction(). Anything else calls rejectAction(). Both are on-chain transactions.

Requires signer: Yes

enshell freeze

Deactivate (freeze) an agent.

enshell freeze --id <agentId>
Option Required Description
--id <agentId> Yes Agent to freeze

Requires signer: Yes

enshell activate

Reactivate a frozen agent.

enshell activate --id <agentId>
Option Required Description
--id <agentId> Yes Agent to activate

Requires signer: Yes

enshell trust

Check trust between two agents (on-chain write, emits event).

enshell trust --id <agentId> --check <targetId>
Option Required Description
--id <agentId> Yes Your agent (checker)
--check <targetId> Yes Target agent to evaluate

Displays TRUSTED (green) or NOT TRUSTED (red), plus target's threat score, strikes, and active status.

Requires signer: Yes

enshell list

List registered agents.

enshell list [--all]
Option Required Description
--all No Show all agents on the network, not just yours

By default, filters to agents owned by the connected wallet. Falls back to showing all agents with a warning if no wallet is connected.

Displays: ENS name, status (ACTIVE/FROZEN), threat score (x/100).

Requires signer: Conditionally (for owner filtering)

enshell inspect

Inspect a specific agent's details.

enshell inspect --id <agentId>
Option Required Description
--id <agentId> Yes Agent to inspect

Displays: status, wallet address, ENS node, spend limit, threat score, strikes, World ID status, registration timestamp.

Requires signer: No (read-only)

Output Conventions

  • All write transactions print a Sepolia Etherscan link: https://sepolia.etherscan.io/tx/{hash}
  • Spinners indicate pending operations, with "approve in your wallet" hint in WalletConnect mode
  • Errors are printed in red and exit with code 1
  • Threat scores are normalized to x/100 for display (raw on-chain values are 0-100,000)