1.0.23

ZeroCode CLI

A comprehensive Node.js/TypeScript CLI for bundling React components and publishing them to the URT protocol.

Features

• Component Bundling: Single-file ESM bundles with tree-shaking and minification
• Manifest Generation: Automatic generation of prepublish and publish manifests
• Offchain Storage: Integration with p2p-0storage for decentralized content storage
• Onchain Publishing: Direct integration with URT protocol smart contracts
• Development Mode: File watching with automatic rebuilds
• Wallet Management: Built-in wallet generation and management

Installation

Global Installation (Development Mode)

For development with the local CLI from source:

# From the zerocode-cli directory
cd packages/zerocode-cli
npm install
npm run build
npm link

# Now you can use 'zc' globally
zc --help

To unlink later:

npm unlink -g zerocode-cli

Production Installation

npm install -g zerocode-cli
zc --help

Development Setup (Local/From Source)

Prerequisites

Make sure you have the following services running locally:

• p2p-0storage: Running on http://localhost:4000
• Local blockchain: Anvil, Hardhat, or testnet
• Core protocol: Deployed URT contracts

Step-by-Step Setup

1. Clone and setup the CLI (development mode)

   # From the monorepo root
   cd packages/zerocode-cli
   npm install
   npm run build
   
   # Link for global access (optional)
   npm link
   

2. Initialize a new project

   # Create a new directory for your components
   mkdir my-zerocode-project
   cd my-zerocode-project
   
   # Option 1: Using global CLI (if npm linked)
   zc init --dev --git --ui
   
   # Option 2: Direct CLI execution (from source)
   npx tsx ../../packages/zerocode-cli/bin/cli.ts init --dev --git --ui
   
   # Option 3: Basic init without flags
   zc init
   

   Available flags:

   • --dev: Generate package.json with local CLI references for monorepo development
   • --git: Initialize git repository and create initial commit
   • --ui: Generate additional UI components (input, textarea, select, etc.)
   • --force: Overwrite existing configuration files

3. Configure environment variables

   # Edit the generated .env file
   nano .env
   

   Set the required variables:

   # Generate a new wallet or use existing one
   PRIVATE_KEY=0x1234567890abcdef...
   
   # Deploy a URT contract (see step 4) and set its address
   URT_ADDRESS=0xYourURTContractAddress
   
   # Local services
   P2P_URL=http://localhost:8787
   CHAIN_ID=31337  # For local Anvil
   RPC_URL=http://localhost:8545
   
   # Registry address from core deployment
   REGISTRY_ADDRESS=0xRegistryContractAddress
   
   # Model IDs are pre-configured with defaults
   

4. Deploy URT contract (if needed)

   # From the core directory
   cd ../../core
   npm install
   npm run build
   
   # Start local blockchain (if not already running)
   npx hardhat node
   # or
   anvil
   
   # Deploy contracts (in another terminal)
   npx hardhat run scripts/00_deploy_local.ts --network localhost
   
   # Copy the URT address from deployment output to your .env
   

5. Start p2p-0storage (if not already running)

   # From the p2p-0storage directory
   cd ../../p2p-0storage
   npm install
   npm start
   # Should be running on http://localhost:8787
   

6. Configure the CLI project

   # Back to your project directory
   cd my-zerocode-project
   
   # Update zerocode.yaml with your addresses
   nano zerocode.yaml
   

   Update the publisher and registry addresses:

   publisher: "0xYourSignerAddress" # Address derived from PRIVATE_KEY
   registry: "0xYourRegistryAddress" # From core deployment
   

7. Check system health

   npx tsx ../../packages/zerocode-cli/bin/cli.ts health
   

   This command will verify:

   • Configuration files are valid
   • Environment variables are set
   • URT authentication is working
   • p2p-0storage is reachable
   • Model IDs are configured

8. Build components

   # Build all components
   npx tsx ../../packages/zerocode-cli/bin/cli.ts build --all
   
   # Or build specific component
   npx tsx ../../packages/zerocode-cli/bin/cli.ts build --component Hero
   

9. Validate manifests

   npx tsx ../../packages/zerocode-cli/bin/cli.ts validate --all
   

10. Development workflow

    # Start development mode (auto-rebuild on changes)
    npx tsx ../../packages/zerocode-cli/bin/cli.ts dev
    
    # In another terminal, test commit (offchain)
    npx tsx ../../packages/zerocode-cli/bin/cli.ts commit --all
    
    # Test publish (onchain) - requires funded wallet
    npx tsx ../../packages/zerocode-cli/bin/cli.ts publish --all
    

Development Tips

• Hot reload: Use zc dev to automatically rebuild on file changes
• Check wallet: Use zc whoami to verify configuration
• Health check: Use zc health to diagnose issues
• Mock mode: CLI falls back to mocks if services are unavailable
• Local testing: All operations work with local blockchain and p2p-0storage

Troubleshooting

CLI not found: Use full path npx tsx ../../packages/zerocode-cli/bin/cli.ts instead of zc

URT authentication failed: Verify URT_ADDRESS and PRIVATE_KEY match deployed contract

P2P-0storage unreachable: Make sure p2p-0storage is running on port 8787

Transaction failed: Ensure your wallet has sufficient ETH for gas

Build errors: Check that your React components follow the expected structure

Production Setup (Published CLI)

For production use, install the CLI from npm:

npm install -g zerocode-cli
zc init
# Follow the same steps as development mode

Commands

zc init

Initialize a new zerocode project with example components and configuration.

Options:

• -f, --force: Overwrite existing configuration

zc build

Bundle components into single-file ESM modules and generate manifests.

Options:

• -c, --component <name>: Build specific component
• -a, --all: Build all components

zc validate

Validate component manifests against JSON schemas.

Options:

• -c, --component <name>: Validate specific component
• -a, --all: Validate all components

zc commit

Commit components to offchain storage (p2p-0storage).

Options:

• -c, --component <name>: Commit specific component
• -a, --all: Commit all components

zc publish

Publish components onchain to URT protocol contracts.

Options:

• -c, --component <name>: Publish specific component
• -a, --all: Publish all components

zc dev

Start development mode with file watching and automatic rebuilds.

Options:

• -c, --component <name>: Watch specific component (default: all)

zc whoami

Display current wallet address, URT configuration, and authentication status.

zc login

Configure wallet for onchain operations.

Options:

• --new: Generate a new wallet
• --key <privateKey>: Use existing private key

zc health

Check system health and configuration status. Verifies:

• Configuration files
• Environment variables
• URT authentication
• p2p-0storage connectivity
• Model IDs setup

Configuration

The CLI is configured via zerocode.yaml:

name: "zerocode-modules"
publisher: "0xYourAddress"
chainId: 8453 # Base mainnet
rpcUrl: "https://mainnet.base.org"
registry: "0xRegistryAddress"

storage:
  driver: "p2p-0storage"
  baseUrl: "http://localhost:8787"

build:
  outdir: "./dist"
  format: "esm"
  target: "es2022"
  minify: true
  external:
    - react
    - react-dom

resolveAliases:
  "@/components": "./src/components"
  "@/lib": "./src/lib"

components:
  - name: "Hero"
    entry: "./src/components/Hero/index.tsx"
    version: "0.1.0"
    description: "Hero section component"
    # ... component configuration

Environment Variables

Create a .env file with:

# ===== AUTHENTICATION =====
# Private key for your URT (Universal Responsibility Token)
PRIVATE_KEY=your_private_key_here

# Your URT contract address (each module is published from its own URT)
URT_ADDRESS=0xYourURTContract

# ===== P2P STORAGE =====
# P2P-0storage API endpoint for offchain storage
P2P_URL=http://localhost:8787

# Optional: IPFS API if p2p-0storage uses IPFS backend
IPFS_API_URL=http://127.0.0.1:5001

# ===== BLOCKCHAIN =====
# Chain ID (8453 = Base mainnet, 84532 = Base Sepolia)
CHAIN_ID=8453

# RPC endpoint for blockchain interactions
RPC_URL=https://mainnet.base.org

# URT Registry contract address (from core protocol deployment)
REGISTRY_ADDRESS=0xRegistryContract

URT Authentication

The CLI uses URT-based authentication for all operations:

1. Each module is published from its own URT contract
2. The URT uses EIP-1271 (isValidSignature) for authentication
3. P2P-0storage requires URT signatures for all operations
4. Onchain publishing is done via URT's callContract function

Make sure your PRIVATE_KEY corresponds to the admin of the URT_ADDRESS contract.

Project Structure

After initialization:

your-project/
├── zerocode.yaml          # CLI configuration
├── .env                   # Environment variables
├── src/
│   └── components/
│       ├── Hero/
│       │   ├── index.tsx
│       │   └── props.schema.ts
│       └── Button/
│           └── index.tsx
└── dist/                  # Build output
    ├── Hero/
    │   ├── index.js
    │   ├── build.manifest.json
    │   ├── publish.manifest.json
    │   ├── commit.result.json
    │   └── publish.result.json
    └── Button/
        └── ...

Development

Building from source

npm run build

Running in development

npm run dev

Integration

The CLI integrates with:

• p2p-0storage: For offchain content storage with URT authentication
• URT Core Contracts: For URT-based onchain module registration via callContract
• URT Protocol: Each module is published from its own URT using EIP-1271 signatures
• Zerocode App: Optional hooks for UI integration

URT Protocol Integration

1. Authentication: All operations use URT's isValidSignature (EIP-1271)
2. Publishing: Modules are published via URT's callContract function
3. Verification: P2P-0storage verifies signatures against URT contracts
4. Ownership: Each module belongs to a specific URT, enabling decentralized governance

License

MIT