Skip to main content

Standards SDK CLI

Interactive terminal interface powered by Ink and Pastel for exploring HCS standards. Provides keyboard-driven navigation, environment validation, and agent tooling.

FeaturesDirect link to Features​

  • Interactive Dashboard - Keyboard-driven interface with category browsing, difficulty badges, and environment validation
  • 40+ Demos - Organized by standard (HCS-2, HCS-5, HCS-10, etc.), difficulty level, and category
  • Configuration - Merges credentials from CLI config, .env files, and environment variables
  • Agent Utilities - Cloudflare tunnel management for registry broker demos
  • Dry Run Mode - Preview demo execution and validate environment
  • Scripted Mode - Non-interactive API for CI/CD pipelines
  • Learning-Focused - Difficulty ratings, estimated duration, learning objectives, and prerequisites

Quick StartDirect link to Quick Start​

Launch the interactive dashboard from the repository root:

pnpm run cli

Installs dependencies and displays the main menu:

╔═══════════════════════════════════════════════════════════╗
║ Hashgraph Online Standards SDK CLI ║
╚═══════════════════════════════════════════════════════════╝

Config file: ~/.config/standards-sdk-cli/config.json
Current network: testnet
Default account: 0.0.•••••1234
Available demos: 42

Select an action:
❯ Run a demo
View configuration summary
Agent utilities
Exit

Use arrow keys and Enter. Press Ctrl+C to exit at any time.

First Run WalkthroughDirect link to First Run Walkthrough​

  1. Choose "Run a demo" → Browse demos by category:

    • 🟢 Getting Started (3 demos)
    • 📚 HCS-2 Standard (4 demos)
    • 📚 HCS-5 Standard (2 demos)
    • 🤖 Registry Broker & Agents (8 demos)
  2. Select a category → See demos sorted by difficulty:

    • 🟢 Beginner: HCS-2 Create Registry (1-2 min)
    • 🟡 Intermediate: HCS-10 Create Registry (3-4 min)
    • 🔴 Advanced: Registry Broker Conversational Demo (10-15 min)
  3. Pick a demo → View detailed preview:

    🟢 HCS-2 Create Registry

    Difficulty: Beginner • 1-2 minutes

    Create a simple topic-based registry on Hedera.

    You'll learn:
    • Understand what a registry is on Hedera
    • Create your first HCS topic
    • Submit your first transaction to Hedera testnet

    Environment: All configured ✓

    Press ENTER to start
  4. Run the demo → Interactive prompts guide execution

Interactive DashboardDirect link to Interactive Dashboard​

  • Run a demo - Browse and execute demos with guided walkthroughs
  • View configuration summary - Inspect network, credentials, registry endpoints (redacted)
  • Agent utilities - Check/install Cloudflare binary, run tunnel dry-runs
  • Exit - Close the CLI

Demo CategoriesDirect link to Demo Categories​

Demos organized by:

  • Getting Started (🟢) - First-time users:

    • HCS-2 Create Registry
    • HCS-5 Mint Hashinal
    • HCS-6 Create Registry
  • HCS Standards (📚) - Organized by standard number:

    • HCS-2 (Topic Registries)
    • HCS-5/HCS-6 (Hashinals)
    • HCS-7 (Smart Hashinals)
    • HCS-10 (Agent Communication)
    • HCS-11 (Profile Metadata)
    • HCS-12 (HashLinks)
    • HCS-14 (Universal Agent IDs)
    • HCS-15/16/17/18 (Petal/Flora Accounts)
    • HCS-20 (Auditable Points)
  • Registry Broker & Agents (🤖) - Advanced integration demos:

    • Agent Registration
    • ERC-8004 Integration
    • Conversational API
    • History Exploration

Demo Detail ViewDirect link to Demo Detail View​

Each demo displays:

  • Difficulty Badge - 🟢 Beginner / 🟡 Intermediate / 🔴 Advanced
  • Estimated Duration - Time commitment upfront
  • Description - What the demo does
  • Learning Objectives - What you'll understand afterward
  • Prerequisites - Required prior demos (if any)
  • Environment Check - Missing variables highlighted in red
  • Command Preview - Exact script that will execute

Keyboard NavigationDirect link to Keyboard Navigation​

  • Arrow Keys - Navigate menus
  • Enter - Select highlighted item
  • Escape - Go back one level
  • Ctrl+C - Exit immediately
  • D (in demo detail) - Toggle dry-run mode

Scripted UsageDirect link to Scripted Usage​

All features are available via command-line arguments for automation and CI/CD.

List All DemosDirect link to List All Demos​

## Human-readable table
pnpm run cli -- demo list

## JSON output for parsing
pnpm run cli -- demo list --json

Example output:

┌─────────────────────────────────────────┬────────────┬──────────────┐
│ Demo ID │ Category │ Difficulty │
├─────────────────────────────────────────┼────────────┼──────────────┤
│ hcs-2:create │ getting-st │ beginner │
│ hcs-5 │ getting-st │ beginner │
│ hcs-10:create-registry │ hcs-10 │ intermediate │
│ registry-broker │ registry-b │ advanced │
└─────────────────────────────────────────┴────────────┴──────────────┘

Inspect Demo MetadataDirect link to Inspect Demo Metadata​

pnpm run cli -- demo info hcs-2:create
pnpm run cli -- demo info registry-broker

Returns:

  • Full description
  • Required environment variables
  • Learning objectives
  • Prerequisites
  • Estimated duration
  • Example output format

Run a DemoDirect link to Run a Demo​

## Execute a specific demo
pnpm run cli -- demo run hcs-2:create

## Dry run (validate environment only)
pnpm run cli -- demo run hcs-2:create --dry-run

## Dry run with environment printout
pnpm run cli -- demo run registry-broker --dry-run --print-env

## Forward additional flags to the demo script
pnpm run cli -- demo run registry-broker -- --profile=mcp

## Suppress progress UI (for logging)
pnpm run cli -- demo run hcs-10:create-registry --no-progress

Direct Script ExecutionDirect link to Direct Script Execution​

Bypass the wrapper when iterating locally:

pnpm --dir cli/standards-cli start -- demo run hcs-5

Configuration SystemDirect link to Configuration System​

The CLI merges configuration from three sources (highest priority first):

  1. CLI config file - ~/.config/standards-sdk-cli/config.json (macOS/Linux follow XDG)
  2. Repository .env files - .env.local then .env from SDK root
  3. Process environment - Shell variables like HEDERA_ACCOUNT_ID

Persist DefaultsDirect link to Persist Defaults​

Store credentials and preferences to avoid re-entering:

pnpm run cli -- config \
--network testnet \
--account-id 0.0.123456 \
--private-key 302e020100300506032b657004220420... \
--registry-base-url https://hol.org/registry/api/v1 \
--prefer-cloudflared true

Configuration OptionsDirect link to Configuration Options​

Hedera Network SettingsDirect link to Hedera Network Settings​

--network <mainnet|testnet|previewnet>  # Active network (default: testnet)
--account-id <0.0.xxxxx> # Default account ID
--private-key <hex-key> # Default private key (DER-encoded hex)

Network-specific credentials (override defaults per network):

--mainnet-account-id <0.0.xxxxx>
--mainnet-private-key <hex-key>
--testnet-account-id <0.0.xxxxx>
--testnet-private-key <hex-key>
--previewnet-account-id <0.0.xxxxx>
--previewnet-private-key <hex-key>

Registry Broker SettingsDirect link to Registry Broker Settings​

--registry-base-url <url>               # Broker API endpoint
--registry-api-key <key> # Optional auth key
--autoTopUp <true|false> # Auto-fund registry operations
--historyAutoTopUp <true|false> # Auto-fund history queries
--profile-mode <ai|mcp> # Agent profile type

Agent SettingsDirect link to Agent Settings​

--prefer-cloudflared <true|false>       # Use cloudflared for tunnels
--fallback-to-local-tunnel <true|false> # Fall back if cloudflared unavailable
--default-port <number> # Agent server port (default: 8787)

OpenRouter SettingsDirect link to OpenRouter Settings​

--openrouter-api-key <key>              # API key for OpenRouter models
--openrouter-model-id <model> # Model ID (default: anthropic/claude-3.5-sonnet)

Custom Environment VariablesDirect link to Custom Environment Variables​

Inject arbitrary variables for specific demos:

--env KEY=VALUE                         # Repeatable flag
--env FOO=bar --env BAZ=qux

Reset to DefaultsDirect link to Reset to Defaults​

pnpm run cli -- config --reset

View Current ConfigDirect link to View Current Config​

pnpm run cli -- config

Example output (credentials redacted):

{
"schemaVersion": 1,
"hedera": {
"network": "testnet",
"defaultAccountId": "0.0.123456",
"defaultPrivateKey": "302e…7890"
},
"registryBroker": {
"baseUrl": "https://hol.org/registry/api/v1",
"useLedger": true,
"autoTopUp": true,
"profileMode": "ai"
},
"agent": {
"preferCloudflared": true,
"defaultPort": 8787
}
}

Environment Variable ResolutionDirect link to Environment Variable Resolution​

The CLI intelligently resolves credentials with network-specific prefixes and fallbacks.

Supported Variable PatternsDirect link to Supported Variable Patterns​

For account ID:

TESTNET_HEDERA_ACCOUNT_ID       # Network-specific (highest priority)
MAINNET_HEDERA_ACCOUNT_ID
PREVIEWNET_HEDERA_ACCOUNT_ID
HEDERA_ACCOUNT_ID # Generic fallback
HEDERA_OPERATOR_ID # Operator alias
ACCOUNT_ID # Legacy fallback

For private key:

TESTNET_HEDERA_PRIVATE_KEY      # Network-specific
MAINNET_HEDERA_PRIVATE_KEY
PREVIEWNET_HEDERA_PRIVATE_KEY
HEDERA_PRIVATE_KEY # Generic fallback
HEDERA_OPERATOR_KEY # Operator alias
PRIVATE_KEY # Legacy fallback

Network SelectionDirect link to Network Selection​

The CLI sets HEDERA_NETWORK and exports network-specific credentials:

HEDERA_NETWORK=testnet
TESTNET_HEDERA_ACCOUNT_ID=0.0.123456
TESTNET_HEDERA_PRIVATE_KEY=302e...

Even when running on testnet, mainnet/previewnet credentials are populated if configured (for multi-network demos).

Registry Broker VariablesDirect link to Registry Broker Variables​

REGISTRY_BROKER_BASE_URL                    # API endpoint
REGISTRY_BROKER_API_KEY # Auth token
REGISTRY_BROKER_DEMO_USE_LEDGER # 1 or 0
REGISTRY_BROKER_DEMO_AUTO_TOP_UP # 1 or 0
REGISTRY_BROKER_HISTORY_AUTO_TOP_UP # 1 or 0
REGISTRY_BROKER_DEMO_PROFILE # ai or mcp
REGISTRY_BROKER_DEMO_HEADERS_TIMEOUT_MS # Timeout in ms
REGISTRY_BROKER_DEMO_BODY_TIMEOUT_MS # Timeout in ms

Additional VariablesDirect link to Additional Variables​

OPENROUTER_MODEL_ID             # Model selection for OpenRouter UAID demos
CLOUDFLARED_BIN # Path to cloudflared binary
STANDARDS_SDK_ROOT # SDK repository root

Agent UtilitiesDirect link to Agent Utilities​

Registry broker demos often require public HTTPS endpoints. The CLI bundles Cloudflare tunnel management.

Check for Cloudflared BinaryDirect link to Check for Cloudflared Binary​

pnpm run cli -- agent check

Output:

Checking for cloudflared binary...
✓ Found: /usr/local/bin/cloudflared
Binary path: /usr/local/bin/cloudflared

If not found:

✗ No cloudflared binary detected
Run with --install to download the bundled version

Install Bundled BinaryDirect link to Install Bundled Binary​

pnpm run cli -- agent check --install

Downloads and installs cloudflared from the cloudflared npm package. The path is stored in CLOUDFLARED_BIN for subsequent demo runs.

Test Tunnel (Dry Run)Direct link to Test Tunnel (Dry Run)​

pnpm run cli -- agent tunnel --dry-run --port 8787

Validates tunnel setup without starting a live connection.

Start Live TunnelDirect link to Start Live Tunnel​

pnpm run cli -- agent tunnel --port 8787

Opens a trycloudflare.com tunnel to localhost:8787. Press Ctrl+C to close.

Example output:

Starting tunnel to localhost:8787...
┌──────────────────────────────────────────────────────────┐
│ Tunnel URL: https://abc-123-xyz.trycloudflare.com │
└──────────────────────────────────────────────────────────┘
Tunnel active. Press Ctrl+C to stop.

Registry broker ERC-8004 and Agentverse demos use this automatically when --prefer-cloudflared is enabled.

Demo System Deep DiveDirect link to Demo System Deep Dive​

Demo MetadataDirect link to Demo Metadata​

Every demo can define:

{
id: "hcs-2:create",
label: "🟢 HCS-2 Create Registry",
category: "getting-started",
difficulty: "beginner",
estimatedDuration: "1-2 minutes",
description: "Create a simple topic-based registry on Hedera.",

learningObjectives: [
"Understand what a registry is on Hedera",
"Create your first HCS topic",
"Submit your first transaction to Hedera testnet"
],

prerequisites: [],

requiredEnv: [
"HEDERA_ACCOUNT_ID",
"HEDERA_PRIVATE_KEY"
],

exampleOutput: `
✅ Registry created successfully!
Topic ID: 0.0.123456
Registry Type: HCS-2 (Simple Topic Registry)
View on HashScan: https://hashscan.io/testnet/topic/0.0.123456
`
}

Demo DiscoveryDirect link to Demo Discovery​

Demos are auto-discovered from:

  1. package.json scripts - Any script starting with demo: or demo
  2. Filesystem scan - TypeScript files in demo/**/*.ts (excluding utils, browser, assets)

The CLI parses script commands to extract file paths and matches them against metadata hints for rich labels.

Demo RunnersDirect link to Demo Runners​

Three execution modes:

// Via npm/pnpm script
{kind: 'package-script', script: 'demo:hcs-2:create'}

// Direct TypeScript execution
{kind: 'typescript', entry: 'demo/hcs-2/create.ts'}

// Shell command
{kind: 'shell', command: 'echo "Demo complete"'}

Most demos use package-script for consistency with repository conventions.

Difficulty LevelsDirect link to Difficulty Levels​

  • 🟢 Beginner - No prior HCS knowledge required, under 5 minutes, minimal config
  • 🟡 Intermediate - Requires basic Hedera understanding, 5-10 minutes, moderate setup
  • 🔴 Advanced - Multi-step workflows, 10+ minutes, extensive configuration

Demos are sorted by difficulty within each category, with beginner demos always appearing first.

Advanced PatternsDirect link to Advanced Patterns​

Chaining Demos with PrerequisitesDirect link to Chaining Demos with Prerequisites​

Some demos require prior execution. The CLI shows prerequisites in the detail view:

pnpm run cli -- demo info registry-broker
🔴 Registry Broker Conversational Demo

Prerequisites: hcs-10:create-registry, registry-broker:register-agent

Run the prerequisites first:
pnpm run cli -- demo run hcs-10:create-registry
pnpm run cli -- demo run registry-broker:register-agent

The interactive dashboard highlights missing prerequisites in yellow.

Registry Broker demo playbookDirect link to Registry Broker demo playbook​

The CLI bundles the full suite of registry-broker demos from standards-sdk/demo/registry-broker. Run them end-to-end with ledger authentication, Cloudflare tunneling, and ERC-8004 publishing:

## 1. Inspect configuration requirements
pnpm run cli -- demo info registry-broker:register-agent-erc8004

## 2. Dry run to view missing env vars (does not execute remote calls)
pnpm run cli -- demo run registry-broker:register-agent-erc8004 --dry-run --print-env

## 3. Execute against mainnet (auto top-up enabled by default)
pnpm run cli -- demo run registry-broker:register-agent-erc8004 \
--env HEDERA_NETWORK=mainnet \
--env MAINNET_HEDERA_ACCOUNT_ID=0.0.123456 \
--env MAINNET_HEDERA_PRIVATE_KEY=302e... \
--env REGISTRY_BROKER_DEMO_TUNNEL=cloudflare

The CLI automatically:

  • Performs ledger authentication (createLedgerChallenge / verifyLedgerChallenge).
  • Spins up a local agent (Cloudflare tunnel by default, fallback to localtunnel).
  • Registers the agent, polls the asynchronous progress endpoint, and logs ERC-8004 agent IDs.
  • Cleans up the local agent process on exit (even when the script crashes).

Other useful flags:

Force local tunnel (useful when corporate networks block Cloudflare)Direct link to Force local tunnel (useful when corporate networks block Cloudflare)​

pnpm run cli -- demo run registry-broker:register-agent-erc8004
--env REGISTRY_BROKER_DEMO_TUNNEL=localtunnel

Disable auto top-up and rely on a pre-funded accountDirect link to Disable auto top-up and rely on a pre-funded account​

pnpm run cli -- demo run registry-broker:register-agent-erc8004
--env REGISTRY_BROKER_DEMO_AUTO_TOP_UP=0

Run the basic registration flow without ERC-8004 updatesDirect link to Run the basic registration flow without ERC-8004 updates​

pnpm run cli -- demo run registry-broker:register-agent
--env REGISTRY_BROKER_DEMO_ENABLE_ERC8004=0
--env REGISTRY_BROKER_DEMO_SKIP_UPDATE=1


Tip: copy `.env.example` to `.env` and populate `TESTNET_HEDERA_ACCOUNT_ID`, `TESTNET_HEDERA_PRIVATE_KEY`, `MAINNET_HEDERA_ACCOUNT_ID`, and `MAINNET_HEDERA_PRIVATE_KEY`. The CLI reads these automatically for both testnet and mainnet demos.

### Multi-Network Testing

Configure credentials for all networks, then switch with `--network`:

```bash
## Setup
pnpm run cli -- config \
--testnet-account-id 0.0.111111 \
--testnet-private-key 302e... \
--mainnet-account-id 0.0.999999 \
--mainnet-private-key 302e...

## Run on testnet
pnpm run cli -- config --network testnet
pnpm run cli -- demo run hcs-2:create

## Switch to mainnet
pnpm run cli -- config --network mainnet
pnpm run cli -- demo run hcs-2:create

CI/CD IntegrationDirect link to CI/CD Integration​

Non-interactive mode auto-activates when stdin is not a TTY:

## GitHub Actions example
- name: Run HCS-2 demo
run: pnpm run cli -- demo run hcs-2:create --no-progress
env:
HEDERA_ACCOUNT_ID: ${{ secrets.HEDERA_ACCOUNT_ID }}
HEDERA_PRIVATE_KEY: ${{ secrets.HEDERA_PRIVATE_KEY }}

The --no-progress flag suppresses Ink UI rendering for clean log output.

TroubleshootingDirect link to Troubleshooting​

Demo Fails with "Missing Environment Variables"Direct link to Demo Fails with "Missing Environment Variables"​

Cause: Required credentials not configured.

Fix: Run in dry-run mode to see what's missing:

pnpm run cli -- demo run <demo-id> --dry-run --print-env

Then configure the missing variables:

pnpm run cli -- config --account-id <...> --private-key <...>

Or add to .env:

HEDERA_ACCOUNT_ID=0.0.123456
HEDERA_PRIVATE_KEY=302e...

"CLI dependencies missing" ErrorDirect link to "CLI dependencies missing" Error​

Cause: CLI workspace dependencies not installed.

Fix:

pnpm --dir cli/standards-cli install

Or use the repository-level helper:

pnpm run cli:install

Interactive Mode Not AvailableDirect link to Interactive Mode Not Available​

Cause: Terminal doesn't support raw mode (e.g., CI environment, non-TTY).

Behavior: CLI automatically falls back to non-interactive mode with helpful command suggestions:

Interactive mode requires running in a TTY-enabled terminal.
Run pnpm run cli -- demo list to view demos
or pnpm run cli -- demo run <demo-id> to execute directly.

Fix: Use scripted commands as shown above.

Cloudflared Binary Not FoundDirect link to Cloudflared Binary Not Found​

Cause: Cloudflared not installed and auto-install failed.

Fix:

pnpm run cli -- agent check --install

If installation fails, manually install cloudflared:

## macOS
brew install cloudflare/cloudflare/cloudflared

## Linux
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
chmod +x cloudflared-linux-amd64
sudo mv cloudflared-linux-amd64 /usr/local/bin/cloudflared

## Set path
export CLOUDFLARED_BIN=/usr/local/bin/cloudflared

Demo Hangs or Times OutDirect link to Demo Hangs or Times Out​

Cause: Network issues, invalid credentials, or API endpoint unavailable.

Debug:

  1. Verify credentials:

    pnpm run cli -- config
  2. Test network connectivity:

    curl https://mainnet-public.mirrornode.hedera.com/api/v1/network/nodes
  3. Check registry broker health (if applicable):

    curl https://hol.org/registry/api/v1/health
  4. Run demo with verbose logging:

    DEBUG=* pnpm run cli -- demo run <demo-id>

TypeScript Build ErrorsDirect link to TypeScript Build Errors​

Cause: Source code changes not compiled.

Fix:

pnpm run cli:build

This runs TypeScript compilation for the CLI workspace.

Permission Denied on Config FileDirect link to Permission Denied on Config File​

Cause: Config directory permissions issue.

Fix:

chmod 755 ~/.config/standards-sdk-cli
chmod 644 ~/.config/standards-sdk-cli/config.json

Demo Output GarbledDirect link to Demo Output Garbled​

Cause: Terminal doesn't support ANSI escape codes or Unicode.

Fix: Use --no-color and --no-progress:

NO_COLOR=1 pnpm run cli -- demo run <demo-id> --no-progress

Development & ExtensionDirect link to Development & Extension​

Project StructureDirect link to Project Structure​

cli/standards-cli/
├── src/
│ ├── cli.ts # Entry point & Pastel CLI setup
│ ├── commands/
│ │ ├── index.tsx # Interactive dashboard
│ │ ├── demo/
│ │ │ ├── list.tsx # List demos
│ │ │ ├── info.tsx # Show demo details
│ │ │ └── run.tsx # Execute demos
│ │ ├── config/
│ │ │ └── index.tsx # Configuration management
│ │ └── agent/
│ │ ├── check.tsx # Cloudflared detection
│ │ └── tunnel.tsx # Tunnel management
│ └── lib/
│ ├── config.ts # Config loading/saving
│ ├── demos.ts # Demo discovery
│ ├── environment.ts # Env var resolution
│ ├── runner.ts # Demo execution
│ ├── cloudflared.ts # Tunnel utilities
│ └── logo.tsx # Branding
├── package.json # CLI dependencies
└── tsconfig.json # TypeScript config

Adding New DemosDirect link to Adding New Demos​

  1. Create demo script in demo/ directory

  2. Add npm script to root package.json:

    "demo:my-feature": "tsx demo/my-feature.ts"
  3. Add metadata hint in cli/standards-cli/src/lib/demos.ts:

    'my-feature': {
    label: '🟢 My Awesome Feature',
    category: 'getting-started',
    difficulty: 'beginner',
    estimatedDuration: '2-3 minutes',
    description: 'Learn how to use my awesome feature',
    requiredEnv: ['HEDERA_ACCOUNT_ID', 'HEDERA_PRIVATE_KEY'],
    learningObjectives: [
    'Understand feature concepts',
    'Execute feature workflow',
    'Verify results on-chain'
    ],
    }
  4. Test in CLI:

    pnpm run cli -- demo list
    pnpm run cli -- demo info my-feature
    pnpm run cli -- demo run my-feature --dry-run

Development ModeDirect link to Development Mode​

pnpm --dir cli/standards-cli dev

Watches source files and restarts on changes.

DebuggingDirect link to Debugging​

Set DEBUG=* for verbose logging:

DEBUG=* pnpm --dir cli/standards-cli start -- demo run <demo-id>

Or use Node.js inspector:

node --inspect-brk ./cli/standards-cli/node_modules/.bin/tsx \
cli/standards-cli/src/cli.ts demo run <demo-id>

TestingDirect link to Testing​

Run the build check before committing:

pnpm run cli:build

Validates TypeScript compilation and exports.

SupportDirect link to Support​