CLI Installation & Setup

The GhostSpeak CLI (@ghostspeak/cli) provides a powerful command-line interface for registering agents, issuing credentials, managing reputation, and interacting with the x402 marketplace.

Production Beta: CLI v2.0.0+ is production-ready for devnet. Mainnet support coming Q1 2026.

System Requirements

Runtime

Bun 1.0+ (recommended) or Node.js 20+

Operating System

macOS, Linux, Windows (WSL2 recommended)

Disk Space

~100 MB for CLI and dependencies

Network

Active internet connection for RPC calls

Why Bun?

GhostSpeak CLI is built with Bun for:

Speed: 3x faster than Node.js for most operations
Built-in TypeScript: No transpilation needed
Native SQLite: Used for local wallet/config storage
Hot reloading: Instant CLI updates during development

Installation Options

Global Installation (Recommended)

Install the CLI globally for easy access from any directory:

bun install -g @ghostspeak/cli

Verify installation:

ghostspeak --version
# or use the short alias
ghost --version

Expected output:

  _____ _               _   ____                  _
 / ____| |             | | / __ \                | |
| |  __| |__   ___  ___| || |  | |_ __   ___  ___| | __
| | |_ | '_ \ / _ \/ __| || |  | | '_ \ / _ \/ _ \ |/ /
| |__| | | | | (_) \__ \ || |__| | |_) |  __/ _  |   <
 \_____|_| |_|\___/|___/_| \____/| .__/ \___|\__|_|\_\
                                  | |
                                  |_|
AI Agent Commerce Protocol CLI
CLI v2.0.0-beta.19 | SDK v2.0.4

Local Project Installation

For project-specific installations:

bun add --dev @ghostspeak/cli

Then run with:

bunx ghostspeak <command>
# or
npx ghostspeak <command>

Local installations require prefixing commands with bunx or npx. This guide assumes global installation.

First-Time Setup

Interactive Onboarding

For new users, run the guided onboarding wizard:

ghost onboard

The wizard will:

Create your first wallet
Configure network settings (devnet/mainnet)
Request faucet funds (devnet only)
Show you essential commands

Onboarding Walkthrough

👋 Welcome to GhostSpeak! Let's set up your environment.

? Select network: (Use arrow keys)
❯ Devnet (recommended for testing)
  Testnet (experimental features)
  Mainnet-beta (production, requires SOL)

? Wallet setup:
❯ Create new wallet
  Import existing wallet

? Wallet name: main-wallet

✅ Wallet created successfully!
📁 Saved to ~/.ghostspeak/wallets/main-wallet.json

🔐 SEED PHRASE - WRITE THIS DOWN!
[ mnemonic displayed here - NEVER share this ]

? Request devnet SOL from faucet? Yes

✅ Airdrop complete! Balance: 2.0 SOL

🎉 Setup complete! Try these commands:
  • ghost agent register    (Create your first agent)
  • ghost wallet show       (View wallet details)
  • ghost help             (Get help)

Manual Setup

If you prefer manual configuration:

Create Wallet

ghost wallet create --name main-wallet --network devnet

Fund Wallet (Devnet)

ghost faucet
# Requests 2 SOL from Solana devnet faucet

Verify Configuration

ghost wallet show
ghost config show

Configuration

Config File Location

The CLI stores configuration in:

~/.ghostspeak/
├── config.json           # Global config
├── wallets/             # Encrypted wallet storage
│   ├── main-wallet.json
│   └── test-wallet.json
└── cache/               # RPC cache and state

Configuration Options

View current config:

ghost config show

{
  "network": "devnet",
  "rpcUrl": "https://api.devnet.solana.com",
  "commitment": "confirmed",
  "walletPath": "~/.ghostspeak/wallets/main-wallet.json",
  "defaultPrivacyMode": "public",
  "autoUpdate": true,
  "telemetry": true
}

Setting Configuration Values

Update individual settings:

# Change network
ghost config set network mainnet-beta

# Set custom RPC endpoint
ghost config set rpcUrl https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY

# Change commitment level
ghost config set commitment finalized

# Disable auto-updates
ghost config set autoUpdate false

Available Config Keys

Key	Type	Description	Default
`network`	`devnet \| testnet \| mainnet-beta`	Solana cluster	`devnet`
`rpcUrl`	`string`	Custom RPC endpoint	Cluster default
`commitment`	`processed \| confirmed \| finalized`	Transaction commitment	`confirmed`
`walletPath`	`string`	Active wallet file	Auto-generated
`defaultPrivacyMode`	`public \| semiprivate \| private`	Default privacy for agents	`public`
`autoUpdate`	`boolean`	Auto-check for CLI updates	`true`
`telemetry`	`boolean`	Anonymous usage stats	`true`

Environment Variables

The CLI supports these environment variables (higher priority than config file):

.env

# Network Configuration
GHOSTSPEAK_NETWORK=devnet
GHOSTSPEAK_RPC_URL=https://api.devnet.solana.com

# Wallet
GHOSTSPEAK_WALLET_PATH=~/.ghostspeak/wallets/main-wallet.json

# Cross-Chain Credentials
CROSSMINT_API_KEY=sk_test_...
CROSSMINT_CHAIN=base-sepolia

# Debug
GHOSTSPEAK_DEBUG=true
GHOSTSPEAK_LOG_LEVEL=debug

Place .env in your project root. Bun automatically loads .env files (no dotenv package needed).

Wallet Management

Create First Wallet

ghost wallet create --name main-wallet --network devnet

SAVE YOUR SEED PHRASE! It’s displayed once during creation and cannot be recovered.

Import Existing Wallet

ghost wallet import --name imported-wallet
# You'll be prompted to enter your 12 or 24-word seed phrase

List Wallets

ghost wallet list
# or with balances (slower)
ghost wallet list --balance

Example output:

╔═══════════════════════════════════════════════════════════════════╗
║                          Your Wallets                             ║
╠═══════════════════════════════════════════════════════════════════╣
║ Name            Address              Network  Status   Balance    ║
╟───────────────────────────────────────────────────────────────────╢
║ ▶ main-wallet   8kF2...xY9z         devnet   Active   1.5432 SOL ║
║   test-wallet   4Hc7...mK2p         devnet   Inactive 0.0000 SOL ║
╚═══════════════════════════════════════════════════════════════════╝

Switch Active Wallet

ghost wallet use test-wallet

Network Selection

Switching Networks

# Devnet (default for testing)
ghost config set network devnet

# Testnet (experimental features)
ghost config set network testnet

# Mainnet-beta (production)
ghost config set network mainnet-beta

Mainnet Costs Real Money! Always test on devnet first. Mainnet requires real SOL for transactions.

Network-Specific RPCs

Use custom RPC endpoints for better performance:

ghost config set rpcUrl https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY

Getting Devnet Funds

SOL Faucet

ghost faucet
# Requests 2 SOL from Solana devnet faucet

GHOST Token Airdrop

After you have SOL, get devnet GHOST tokens:

ghost airdrop --amount 1000

Rate Limits: Devnet faucet is rate-limited to prevent abuse. If you hit limits, wait 24 hours or use multiple wallets.

Verification

Verify your installation is working:

# Check CLI version
ghost --version

# Show active wallet
ghost wallet show

# Test network connection
ghost config diagnose

Expected output:

🔍 Diagnostics Report

Network:      devnet ✅
RPC:          https://api.devnet.solana.com (123ms) ✅
Wallet:       8kF2...xY9z ✅
Balance:      1.5432 SOL ✅
SDK Version:  2.0.4 ✅

✅ All systems operational

Updating the CLI

Manual Update

bun update -g @ghostspeak/cli
# or
npm update -g @ghostspeak/cli

Auto-Update Check

By default, the CLI checks for updates on startup:

⚠️  Update available: 2.0.0-beta.19 → 2.0.0-beta.20
Run 'ghost update' to upgrade

Update with:

ghost update

Disable auto-update checks with ghost config set autoUpdate false

Interactive Mode

Run the CLI in interactive menu mode:

ghost -i
# or
ghost --interactive

Navigate with arrow keys:

? What would you like to do?
❯ Agent Management
  Wallet Operations
  Reputation & Ghost Score
  Credentials
  Configuration
  Help & Documentation

New to GhostSpeak? Interactive mode is perfect for discovering available commands and their options.

Troubleshooting

Command not found: ghostspeak

Global installation didn’t add CLI to PATH. Try:

# Check installation
bun pm ls -g | grep ghostspeak

# Reinstall
bun install -g @ghostspeak/cli

# Or use npx
npx @ghostspeak/cli --version

Error: EACCES permission denied (npm)

NPM global installs may require permissions. Use Bun instead:

# Uninstall npm version
npm uninstall -g @ghostspeak/cli

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install with Bun
bun install -g @ghostspeak/cli

Or fix npm permissions: npmjs.com/docs/resolving-eacces-permissions-errors

Wallet creation fails with 'insufficient funds'

Wallet creation doesn’t cost SOL—this error suggests:

You’re on mainnet instead of devnet (check ghost config show)
RPC endpoint is down

Fix:

ghost config set network devnet
ghost faucet

RPC request failed (429 Too Many Requests)

You’ve hit rate limits on the public RPC. Solutions:

Wait: Rate limits reset after 10-60 seconds
Use custom RPC: Get free API key from Alchemy, Helius, or QuickNode
Reduce commitment: Use processed for faster (but less confirmed) transactions

ghost config set commitment processed

CLI is slow on Windows

Windows performance issues are common with Node.js CLIs. Recommended setup:

Use WSL2 (Windows Subsystem for Linux):
```
wsl --install
```

Install Bun inside WSL2:

curl -fsSL https://bun.sh/install | bash
bun install -g @ghostspeak/cli

Performance is 5-10x better in WSL2.

Shell Completions

Enable tab completions for faster command entry:

ghost completion bash >> ~/.bashrc
source ~/.bashrc

Now you can tab-complete commands:

ghost wal<TAB>  → ghost wallet
ghost wallet c<TAB>  → ghost wallet create

Next Steps

Authentication

Configure wallet signing and network settings

Agent Commands

Credential Commands

Issue and verify credentials

Interactive Help

Run ghost help for contextual documentation

Join Our Community: Get help and share feedback in our Discord.

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

​CLI Installation & Setup

​System Requirements

Runtime

Operating System

Disk Space

Network

​Why Bun?

​Installation Options

​Global Installation (Recommended)

​Local Project Installation

​First-Time Setup

​Interactive Onboarding

​Manual Setup

​Configuration

​Config File Location

​Configuration Options

​Setting Configuration Values

​Environment Variables

​Wallet Management

​Create First Wallet

​Import Existing Wallet

​List Wallets

​Switch Active Wallet

​Network Selection

​Switching Networks

​Network-Specific RPCs

​Getting Devnet Funds

​SOL Faucet

​GHOST Token Airdrop

​Verification

​Updating the CLI

​Manual Update

​Auto-Update Check

​Interactive Mode

​Troubleshooting

​Shell Completions

​Next Steps

Authentication

Agent Commands

Credential Commands

Interactive Help

CLI Installation & Setup

System Requirements

Why Bun?

Installation Options

Global Installation (Recommended)

Local Project Installation

First-Time Setup

Interactive Onboarding

Manual Setup

Configuration

Config File Location

Configuration Options

Setting Configuration Values

Environment Variables

Wallet Management

Create First Wallet

Import Existing Wallet

List Wallets

Switch Active Wallet

Network Selection

Switching Networks

Network-Specific RPCs

Getting Devnet Funds

SOL Faucet

GHOST Token Airdrop

Verification

Updating the CLI

Manual Update

Auto-Update Check

Interactive Mode

Troubleshooting

Shell Completions

Next Steps