Quickstart

Get ENShell running in under 5 minutes. This guide walks through installing the SDK and CLI, registering an agent, and submitting your first protected action.

Prerequisites

  • Node.js >= 22.10.0
  • An Ethereum wallet with Sepolia ETH (for gas)
  • A wallet app that supports WalletConnect (e.g., MetaMask, Rainbow, Ledger Live)

Install

SDK

npm install @enshell/sdk

CLI

npm install -g @enshell/cli

Verify the installation:

enshell --version

Connect Your Wallet

The CLI supports three wallet modes. The easiest way to start is with WalletConnect:

enshell connect

This displays a QR code in your terminal. Scan it with your wallet app to establish a session. The session persists in ~/.enshell/wc-session.json so you don't need to reconnect every time.

Alternative: Environment Private Key

For scripting or CI environments, use a private key from .env:

# .env
ENSHELL_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

Then pass --wallet env to any command:

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

For named keys (useful for managing multiple agents):

# .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

Register an Agent

enshell register \
  --id my-agent \
  --agent-wallet 0xYourAgentWalletAddress \
  --spend-limit 1.0

This does three things:

  1. Calls registerAgentSimple() on the AgentFirewall contract
  2. Creates the ENS subdomain my-agent.enshell.eth with default text records
  3. Posts the agent info to the relay for dashboard display

You'll see output like:

Agent registered: my-agent
ENS: my-agent.enshell.eth
Tx: https://sepolia.etherscan.io/tx/0x...

Submit a Protected Action

enshell protect \
  --id my-agent \
  --target 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D \
  --value 0.05 \
  --instruction "Swap 0.05 ETH for USDC on Uniswap V2 Router"

Behind the scenes, the CLI:

  1. Encrypts the instruction with the oracle's public key (ECIES)
  2. Stores the encrypted payload on the relay
  3. Submits instructionHash + target + value to the contract
  4. Waits for the CRE oracle to analyze and resolve the action

Possible Outcomes

Approved -- The CRE scored the action as safe (score < 30,000). The action proceeds.

Escalated -- The CRE flagged potential risks (score 30,000-69,999). The CLI displays Claude's full analysis and prompts you:

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 is the well-known Uniswap V2 Router, but the
instruction contains unusual parameters that warrant human review...

? Approve this action? (y/n)

Blocked -- The CRE detected a clear threat (score >= 70,000). The action is rejected automatically.

Using the SDK Programmatically

import { ENShell, Network } from '@enshell/sdk';
import { Wallet, JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://ethereum-sepolia-rpc.publicnode.com');
const signer = new Wallet(process.env.PRIVATE_KEY, provider);

const enshell = new ENShell({
  network: Network.SEPOLIA,
  signer,
});

// Register an agent
await enshell.registerAgent('my-agent', {
  agentAddress: '0xYourAgentWallet',
  spendLimit: '1.0',
  allowedTargets: ['0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D'],
});

// Protect an action
const result = await enshell.protect('my-agent', {
  instruction: 'Swap 0.05 ETH for USDC on Uniswap V2 Router',
  tx: {
    to: '0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D',
    value: '0.05',
  },
});

console.log('Action ID:', result.actionId);

// Wait for CRE resolution
const resolution = await result.waitForResolution();
console.log('Decision:', resolution.decision); // 1=APPROVED, 2=ESCALATED, 3=BLOCKED

if (resolution.decision === 2) {
  console.log('Analysis:', resolution.analysis);
  // Approve or reject based on your logic
  await enshell.approveAction(result.actionId);
}

Inspect Your Agent

enshell inspect --id my-agent

Agent: my-agent
Status: Active
Wallet: 0xYour...Address
ENS Node: 0xabcd...1234
Spend Limit: 1.0 ETH
Threat Score: 15000
Strikes: 0
Registered: 2026-04-05T12:00:00.000Z

List Your Agents

enshell list

Shows all agents owned by your connected wallet. Use --all to see every agent on the network.

Check Trust

enshell trust --id my-agent --check other-agent

This performs an on-chain trust check and emits a TrustChecked event. The result tells you whether the target agent is currently trusted based on their threat score and strike count.

Next Steps