npm package: @perkos/cli
Description: PerkOS CLI - Command line tools for creating sites and agents with PerkOS
Author: PerkOS
Latest version: 0.2.7

# PerkOS CLI

Scaffold-style templates for building Web3 apps with AI agent backends.

## Templates

| Template | Description | Chain |
|----------|-------------|-------|
| 🔐 `selfclaw` | Human verification with Self.xyz proofs | EVM (Foundry) |
| 🏆 `talent` | Builder Score reputation gating | EVM (Foundry) |
| ⚡ `stacks` | Clarity smart contracts on Stacks | Stacks (Clarinet) |

Each template includes:
- Smart contracts with tests
- Next.js frontend
- Docker + OpenClaw AI backend
- Local blockchain & faucet
- VPS deployment scripts

## Workshop

Interactive exercises for the ERC-8004 Workshop. Run against the live PerkOS Stack at `stack.perkos.xyz`.

```bash
# Run all 7 exercises
npx @perkos/cli workshop all

# Run a specific exercise
npx @perkos/cli workshop 1
```

| Exercise | Description |
|----------|-------------|
| 1 | **Discovery** — Query 5 standard agent endpoints |
| 2 | **Identity** — Lookup on-chain identity on Base |
| 3 | **Reputation** — Query agent reputation score |
| 4 | **Onboarding** — Get full agent registration package |
| 5 | **x402 Payment** — Explore payment networks and health |
| 6 | **Full Flow** — End-to-end agent lifecycle |
| 7 | **Live Registration** — Register an agent on Base mainnet (requires wallet) |

### Exercise 7: Live Agent Registration

Exercise 7 performs **real on-chain transactions** on Base mainnet. It registers your wallet as an agent in the ERC-8004 Identity Registry.

**Setup:**

```bash
# Copy the example env file
cp .env.example .env

# Add your private key (wallet needs ~$0.01 ETH on Base for gas)
# Edit .env and set PERKOS_PRIVATE_KEY=0x...
```

**Run:**

```bash
npx @perkos/cli workshop 7
```

**What it does:**
1. Reads your wallet from `.env`
2. Calls PerkOS Stack for onboarding package
3. Checks if already registered on-chain
4. Signs and submits `register()` to Base mainnet
5. Waits for confirmation and shows BaseScan link
6. Verifies registration + queries reputation

## Quick Start

### Prerequisites

```bash
# Node.js 18+
node --version

# For EVM templates (selfclaw, talent)
curl -L https://foundry.paradigm.xyz | bash
foundryup

# For Stacks template
brew install clarinet

# Docker (for OpenClaw backend)
docker --version
```

### Create a Project

```bash
# Clone the repo
git clone https://github.com/PerkOS-xyz/PerkOS-Client.git
cd PerkOS-Client

# Install CLI dependencies
npm install

# Build CLI
npm run build

# Create a new project
node dist/cli.js create-app my-app --template selfclaw
```

## Local Testing

### Test SelfClaw Template (EVM)

```bash
# 1. Create project
node dist/cli.js create-app test-selfclaw --template selfclaw

# 2. Go to project
cd test-selfclaw

# 3. Initialize git (required for Foundry)
git init

# 4. Install Foundry dependencies
cd contracts
forge install foundry-rs/forge-std OpenZeppelin/openzeppelin-contracts --no-git

# 5. Build contracts
forge build

# 6. Run tests
forge test -vvv
# Expected: 5 tests passing

# 7. Start local chain (Terminal 1)
anvil --block-time 2

# 8. Deploy contracts (Terminal 2)
forge script script/Deploy.s.sol --rpc-url http://localhost:8545 --broadcast --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# 9. Start frontend (Terminal 3)
cd ../frontend
pnpm install
pnpm dev
# Open http://localhost:3000
```

### Test Talent Template (EVM)

```bash
# 1. Create project
node dist/cli.js create-app test-talent --template talent

# 2. Go to project
cd test-talent
git init

# 3. Install & test
cd contracts
forge install foundry-rs/forge-std OpenZeppelin/openzeppelin-contracts --no-git
forge build
forge test -vvv
# Expected: 8 tests passing

# 4. Run full stack (same as selfclaw)
```

### Test Stacks Template

```bash
# 1. Create project
node dist/cli.js create-app test-stacks --template stacks

# 2. Go to project
cd test-stacks/contracts

# 3. Check contracts
clarinet check
# Expected: 2 contracts checked, warnings only

# 4. Install test dependencies
npm install

# 5. Run tests
npm test
# Expected: 7 tests passing

# 6. Start devnet
clarinet devnet start

# 7. Start frontend (new terminal)
cd ../frontend
pnpm install
pnpm dev
```

### Test OpenClaw Docker Backend

```bash
# In any project directory
cd docker

# Copy env file
cp .env.example .env

# Add your API key
echo "ANTHROPIC_API_KEY=sk-ant-your-key" >> .env

# Start OpenClaw
docker compose up -d

# Check logs
docker compose logs -f

# Test health endpoint
curl http://localhost:3030/health

# Stop
docker compose down
```

## All-in-One Commands

Once inside a project, use these convenience commands:

```bash
# Install everything
pnpm install:all

# Run full stack (chain + contracts + frontend + openclaw)
pnpm dev

# Individual services
pnpm chain          # Start local blockchain
pnpm deploy         # Deploy contracts
pnpm frontend       # Start frontend
pnpm openclaw:start # Start OpenClaw Docker

# Testing
pnpm test           # Run contract tests

# Production
pnpm build          # Build frontend
pnpm openclaw:deploy # Deploy OpenClaw to VPS
```

## Project Structure

```
my-app/
├── contracts/          # Smart contracts
│   ├── src/            # Contract source
│   ├── script/         # Deploy scripts
│   └── test/           # Tests
├── frontend/           # Next.js app
│   └── src/
│       ├── app/
│       ├── components/
│       └── lib/
├── docker/             # OpenClaw backend
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── config.yaml
├── scripts/            # Utilities
│   ├── faucet.mjs      # Local faucet
│   └── deploy-vps.sh   # VPS deployment
└── package.json
```

## Templates Detail

### 🔐 SelfClaw

Human verification for AI agents using Self.xyz passport proofs.

- **Contract**: `SelfClawVerifier.sol` - On-chain verification attestations
- **Features**: EIP-712 signatures, expiration, revocation
- **Use Case**: Prove an agent is controlled by a verified human

### 🏆 Talent

Gate access based on Talent Protocol Builder Score.

- **Contract**: `BuilderScoreGate.sol` - Score-based access control
- **Features**: Score thresholds, attestations, tiers
- **Use Case**: Premium features for established builders

### ⚡ Stacks

Clarity smart contracts on the Stacks blockchain.

- **Contracts**: `counter.clar`, `nft-collection.clar`
- **Features**: SIP-009 NFT, minting, Bitcoin settlement
- **Use Case**: Bitcoin-secured applications

## VPS Deployment

Deploy OpenClaw to any VPS via SSH:

```bash
# Configure in docker/.env
VPS_HOST=your-server.com
VPS_USER=root
VPS_SSH_KEY=~/.ssh/id_rsa
VPS_DEPLOY_PATH=/opt/openclaw

# Deploy
pnpm openclaw:deploy
```

## Development

```bash
# Clone
git clone https://github.com/PerkOS-xyz/PerkOS-Client.git
cd PerkOS-Client

# Install
npm install

# Build
npm run build

# Test CLI
node dist/cli.js templates

# Run TypeScript directly
npx tsx src/cli.ts create-app test --template selfclaw
```

## License

MIT

---

Built with 💖 by [PerkOS](https://perkos.xyz)