KRNL CLI

A specialized Smart Contract deployment CLI for KRNL use cases, built with modern Node.js and TypeScript.

Features

• 🚀 Init: Initialize new template projects with Foundry auto-installation
• 🔨 Compile: Compile smart contracts with auto-detection and progress tracking
• 📦 Deploy: Deploy contracts using Foundry scripts with network auto-detection
• ✅ Verify: Automatic contract verification on Etherscan with --verify flag
• 🔐 Create-Attestor: Create custom attestors for verification

Installation

npm install -g @krnl-dev/krnl-cli

Or use with npx:

npx @krnl-dev/krnl-cli init --name my-project

Quick Start

# Initialize a new project (auto-installs Foundry if needed)
krnl init --name my-project
cd my-project

# Compile smart contracts (auto-detects src/ or contracts/)
krnl compile

# Deploy to localhost (requires Anvil running)
krnl deploy --network localhost

# Deploy to Sepolia with verification
krnl deploy --network sepolia --verify

# Create a new attestor
krnl create-attestor

Commands

Init

Initialize a new KRNL project from the Hello-KRNL template.

Features:

• Auto-installs Foundry (forge, cast, anvil) if not present or version < 1.0.0
• Clones Hello-KRNL template repository
• Installs npm dependencies
• Installs Foundry libraries (OpenZeppelin, Account Abstraction, forge-std)
• Creates .env from .env.example

krnl init [options]

Options:

• -t, --template <template>: Template to use (default: "default")
• -n, --name <name>: Project name

Example:

krnl init --name my-krnl-project
cd my-krnl-project

Compile

Compile smart contracts with auto-detection of project structure.

Features:

• Auto-detects src/ or contracts/ directory
• Auto-detects out/ or artifacts/ output directory
• Reads foundry.toml for configuration
• Zero-config compilation for standard Foundry projects

krnl compile [options]

Options:

• -c, --contracts <path>: Path to contracts directory (optional, auto-detected)
• -o, --output <path>: Output directory for artifacts (optional, auto-detected)
• -p, --project-dir <path>: Path to project root directory

Examples:

# Auto-detect everything
krnl compile

# Explicit paths
krnl compile -c ./src -o ./out

Deploy

Deploy smart contracts using Foundry scripts with network auto-detection.

Features:

• Uses Foundry forge script for deployment
• Auto-detects networks from .env and foundry.toml
• Default script: script/Deploy.s.sol
• Auto-prefixes PRIVATE_KEY with 0x if needed
• Parses deployment address from script output
• Optional contract verification on block explorers
  • Requires ETHERSCAN_API_KEY in environment or .env
  • Supports --verify with --contract <Name> or --verify-all
  • Aligns compiler version for verification from foundry.toml (solc), e.g. passes --compiler-version v0.8.23

krnl deploy [options]

Options:

• -n, --network <network>: Network to deploy to (default: "localhost")
• --script <pathOrTarget>: Forge script file or target (default: "script/Deploy.s.sol")
• --verify: Verify contract on explorer (requires --contract or --verify-all when using --script)
• --contract <name>: Contract name to verify (required with --verify and --script)
• --verify-all: Verify all contracts deployed by the script
• --constructor-args <args>: Constructor arguments for verification (if needed)

Examples:

# Deploy using default script to sepolia
krnl deploy --network sepolia

# Deploy with verification of a specific contract
krnl deploy --network sepolia --verify --contract RealEstateInvestment

# Deploy with verification of all contracts in script
krnl deploy --network sepolia --verify --verify-all

# Use custom script with specific contract target
krnl deploy --network sepolia --script "script/Deploy.s.sol:DeployRealEstateScript" --verify --verify-all

# Deploy to localhost (requires Anvil running)
krnl deploy --network localhost

Network Detection:

• Reads SEPOLIA_RPC_URL, MAINNET_RPC_URL, etc. from .env
• Reads [rpc_endpoints] from foundry.toml
• Always includes localhost (http://localhost:8545)

Verification Details:

• When using --verify with --script, you must specify either:
  • --contract <Name> to verify a specific contract
  • --verify-all to verify all contracts deployed by the script
• The CLI invokes forge verify-contract with:
  • Contract address (parsed from deployment output)
  • Contract identifier: src/<Contract>.sol:<Contract>
  • --chain-id <id>
  • --compiler-version v<solc> read from foundry.toml
  • --etherscan-api-key <key> from ETHERSCAN_API_KEY env var
• If ETHERSCAN_API_KEY is missing and --verify is enabled, the CLI will error with an actionable message

Environment Variables:

• PRIVATE_KEY: Your wallet private key (required for deployment)
• ETHERSCAN_API_KEY: API key for contract verification (required with --verify)
• <NETWORK>_RPC_URL: RPC endpoint for the target network (e.g., SEPOLIA_RPC_URL)
• Additional env vars may be required by your deploy script (e.g., DELEGATED_ACCOUNT_ADDRESS)

Create-Attestor

Create custom attestors for contract verification.

krnl create-attestor

Runs the create-attestor-standalone.sh script for Docker-based attestor creation.

Testing

The project includes a comprehensive smoke test script that validates the entire CLI workflow:

# Run smoke test on localhost (requires Anvil)
./scripts/smoke.sh

# Run smoke test on Sepolia testnet
NETWORK=sepolia \
SEPOLIA_RPC_URL="https://sepolia.infura.io/v3/YOUR_PROJECT_ID" \
PRIVATE_KEY="0x..." \
ETHERSCAN_API_KEY="YOUR_API_KEY" \
./scripts/smoke.sh

# Keep the generated project for inspection
KEEP_PROJECT=1 ./scripts/smoke.sh

# Skip build step (use existing dist/)
SKIP_BUILD=1 ./scripts/smoke.sh

The smoke test performs:

1. krnl init - Creates a fresh project
2. krnl compile - Compiles contracts
3. krnl deploy - Deploys without verification
4. krnl deploy --verify - Deploys with verification (if API key provided)
5. Cleanup - Removes project and stops Anvil

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run smoke test
./scripts/smoke.sh

Architecture

• CLI Router: Commander.js-based command dispatcher
• UI Layer: Ink/InkUI components for interactive terminal experiences
• Configuration: YAML-based configuration management
• TypeScript: Full type safety throughout the codebase
• Error Handling: Comprehensive error reporting with actionable suggestions

Project Structure

src/
├── cli.ts                 # Main CLI entry point
├── commands/              # Individual command implementations
│   ├── init/             # Project initialization with Foundry setup
│   │   ├── index.tsx     # Init command UI
│   │   └── ui.tsx        # Init progress components
│   ├── compile/          # Smart contract compilation
│   │   ├── index.tsx     # Compile command UI
│   │   └── ui.tsx        # Compile progress components
│   ├── deploy/           # Deployment via Foundry scripts
│   │   ├── index.tsx     # Deploy command UI
│   │   └── ui.tsx        # Deploy progress components
│   └── create-attestor/  # Attestor creation
│       └── index.tsx
├── components/            # Shared UI components
│   ├── Spinner.tsx
│   └── Message.tsx
├── utils/                 # Utility functions
│   ├── config.ts         # Configuration management
│   ├── branding.ts       # KRNL logo and branded styles
│   ├── foundry.ts        # Foundry integration utilities
│   └── networks.ts       # Network detection and RPC management
└── scripts/               # Development and testing scripts
    └── smoke.sh          # End-to-end smoke test

Requirements

• Node.js: v18 or higher
• Foundry: Auto-installed by krnl init if not present
  • forge
  • cast
  • anvil
• Git: Required for cloning templates

Troubleshooting

Foundry not found

If you see "Foundry not found" errors, run:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Verification fails

• Ensure ETHERSCAN_API_KEY is set in your environment or .env
• When using --verify with --script, you must specify:
  • --contract <Name> for a specific contract, OR
  • --verify-all to verify all contracts
• Check that your contract source matches the deployed bytecode

Network not detected

• Add RPC URL to .env: SEPOLIA_RPC_URL=https://...
• Or add to foundry.toml:

  [rpc_endpoints]
  sepolia = "https://..."

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run smoke tests: ./scripts/smoke.sh
5. Submit a pull request

License

ISC