CLI Reference

Overview

Karen provides a comprehensive command-line interface for all wallet and agent operations. The CLI is built with Commander.js and supports:

Wallet management (create, list, balance, send, airdrop)
DeFi operations (token launch, staking, wrapped SOL)
Agent lifecycle (create, start/stop, chat)
Server control (REST API, MCP server)
Transaction history and audit logs

The CLI reads configuration from .env and stores encrypted keystores in ~/.karen/keystore.enc

Installation

Clone and build

git clone https://github.com/Don-Vicks/karen.git
cd karen
npm install
npm run build

Link globally (optional)

npm link

This makes karen available globally in your terminal.

Configure environment

Create .env:

KEYSTORE_PASSWORD=your-secure-password
SOLANA_NETWORK=devnet

Global Options

karen --version          # Show version
karen --help             # Show help for all commands
karen <command> --help   # Show help for specific command

Wallet Commands

All wallet operations are under the karen wallet namespace.

Create Wallet

Create a new standalone or HD-derived wallet.

karen wallet create --name my-wallet

Options:

--name, -n

string

required

Wallet name (default: my-wallet)

--mnemonic, -m

string

Master mnemonic for HD derivation (24 words)

--index, -i

number

default:"0"

Derivation index for HD wallets

Output:

✅ Wallet created:
   Name:    my-wallet
   ID:      550e8400-e29b-41d4-a716-446655440000
   Address: 7xKKzD8qHa...

List Wallets

karen wallet list

Output:

📜 Wallets (3):

  trading-bot (550e8400...)
    Address: 7xKKzD8qHa...
    Tags: automated, trading
    Created: 2024-01-15T10:30:00Z

  agent-1 (660f9511...)
    Address: 9xYzW5pQr...
    Tags: mcp, external
    Created: 2024-01-16T14:20:00Z

Check Balance

karen wallet balance --name my-wallet

Options:

--name, -n

string

required

Wallet name to query

Output:

💰 my-wallet (7xKKzD8qHa...):

  SOL: 1.5000

  Tokens:
    EPjFWdd5...: 100.50 USDC
    DezXAZ8z...: 50.00 BONK

Request Airdrop

karen wallet airdrop --name my-wallet --amount 2

Options:

--name, -n

string

required

Wallet name to fund

--amount, -a

number

default:"1"

Amount of SOL to request (max 2 per request on devnet)

Output:

⏳ Requesting 2 SOL airdrop...
✅ Airdropped 2 SOL
   Signature: 5Kn8fGzXv...

Airdrop only works on devnet. Mainnet requires purchasing SOL from an exchange.

Send SOL

karen wallet send \
  --name my-wallet \
  --to 7xKKzD8qHa... \
  --amount 0.5

Options:

--name, -n

string

required

Source wallet name

--to, -t

string

required

Recipient Solana address (base58)

--amount, -a

number

required

Amount of SOL to send

Output:

⏳ Sending 0.5 SOL to 7xKKzD8qHa...
✅ Sent 0.5 SOL
   Signature: 5Kn8fGzXv...

Guardrails:

Max 2 SOL per transaction (default)
Max 5 transactions per minute
Daily spending limit: 10 SOL

If blocked:

🛡️ Blocked by guardrails: Amount exceeds maxSolPerTransaction (2 SOL)

Generate Master Mnemonic

karen wallet mnemonic

Output:

🔑 New Master Mnemonic (24 words):

   abandon ability able about above absent absorb abstract absurd abuse access accident
   account accuse achieve acid acoustic acquire across act action actor actress actual

   ⚠️  Store this securely! Anyone with this can derive all agent wallets.

Never share your mnemonic. Store it in a password manager or hardware wallet. This phrase can recover all HD-derived wallets.

DeFi Wallet Commands

Launch Token

Create a new SPL token with initial supply.

karen wallet launch-token \
  --name my-wallet \
  --token-name "Agent Coin" \
  --symbol AGT \
  --decimals 9 \
  --supply 1000000

Options:

--name, -n

string

required

Wallet name (you become mint authority)

--token-name

string

required

Token full name

--symbol

string

required

Token ticker symbol (e.g., AGT)

--decimals

number

default:"9"

Decimal places

--supply

number

default:"1000000"

Initial supply in whole units

Output:

⏳ Launching token AGT...
✅ Token launched!
   Name:    Agent Coin (AGT)
   Mint:    7xKKzD8qHa...
   Supply:  1,000,000
   Tx:      5Kn8fGzXv...

Mint Additional Supply

karen wallet mint-supply \
  --name my-wallet \
  --mint 7xKKzD8qHa... \
  --amount 500000 \
  --decimals 9

Options:

--mint

string

required

Token mint address

--amount, -a

number

required

Amount to mint in whole units

--decimals

number

default:"9"

Token decimals

Revoke Authority

Permanently revoke mint or freeze authority. Irreversible!

karen wallet revoke-authority \
  --name my-wallet \
  --mint 7xKKzD8qHa... \
  --type mint

Options:

--type

string

default:"mint"

Authority type: mint or freeze

Output:

⚠️  Revoking mint authority (IRREVERSIBLE)...
✅ mint authority permanently revoked
   Tx: 5Kn8fGzXv...

Stake SOL

karen wallet stake \
  --name my-wallet \
  --amount 1.0 \
  --validator BeachiopjxQxL7CaHNSZsynRdj6vY5vCeaTXGKqfCZTP

Options:

--amount, -a

number

required

Amount of SOL to stake

--validator, -v

string

Validator vote account (optional — uses default devnet validator)

Output:

⏳ Staking 1.0 SOL...
✅ Staked 1.0 SOL
   Stake Account: 9xYzW5pQr...
   Validator:     BeachiopjxQxL7CaHNSZsynRdj6vY5vCeaTXGKqfCZTP
   Tx:            5Kn8fGzXv...

Unstake SOL

Deactivate a stake account (withdrawal available after 1 epoch).

karen wallet unstake \
  --name my-wallet \
  --stake-account 9xYzW5pQr...

Options:

--stake-account, -s

string

required

Stake account public key

Withdraw Stake

karen wallet withdraw-stake \
  --name my-wallet \
  --stake-account 9xYzW5pQr...

List Stake Accounts

karen wallet stakes --name my-wallet

Output:

🥩 Stake Accounts (2):

  9xYzW5pQr...
    Balance:  1.0000 SOL
    State:    active
    Validator: BeachiopjxQxL7CaHNSZsynRdj6vY5vCeaTXGKqfCZTP

  5KnAbC3d...
    Balance:  0.5000 SOL
    State:    deactivating
    Validator: N/A

Burn Tokens

karen wallet burn \
  --name my-wallet \
  --mint 7xKKzD8qHa... \
  --amount 100

Close Token Account

Close an empty token account to reclaim rent (~0.002 SOL).

karen wallet close-account \
  --name my-wallet \
  --mint 7xKKzD8qHa...

Output:

✅ Token account closed
   Rent reclaimed: 0.002039 SOL
   Tx: 5Kn8fGzXv...

Wrap/Unwrap SOL

karen wallet wrap-sol \
  --name my-wallet \
  --amount 1.0

Agent Commands

Manage autonomous AI agents that run trading strategies.

Create Agent

karen agent create \
  --name trader-bot \
  --strategy "Buy low, sell high on SOL/USDC" \
  --llm openai \
  --model gpt-4 \
  --interval 30000 \
  --max-per-tx 2 \
  --daily-limit 10

Options:

--name, -n

string

required

Agent name

--strategy, -s

string

required

Trading strategy description (used as LLM system prompt)

--llm, -l

string

default:"openai"

LLM provider: openai, anthropic, grok, or gemini

--model, -m

string

LLM model (defaults depend on provider)

OpenAI: gpt-4o-mini
Anthropic: claude-3-5-sonnet-20241022
Grok: grok-beta
Gemini: gemini-2.0-flash-exp

--interval

number

default:"30000"

Loop interval in milliseconds (30000 = 30 seconds)

--max-per-tx

number

default:"2"

Max SOL per transaction

--daily-limit

number

default:"10"

Daily spending limit in SOL

Output:

✅ Agent created:
   Name:     trader-bot
   ID:       550e8400-e29b-41d4-a716-446655440000
   Wallet:   660f9511-f3ac-52e5-b827-557766551111
   LLM:      openai (gpt-4)
   Strategy: Buy low, sell high on SOL/USDC

   Start with: karen agent start --name trader-bot

List Agents

karen agent list

Output:

🤖 Agents (2):

  trader-bot (550e8400...)
    Status:   running
    Wallet:   660f9511...
    LLM:      openai (gpt-4)
    Strategy: Buy low, sell high on SOL/USDC...
    Created:  2024-01-15T10:30:00Z

  hodl-agent (770fabc2...)
    Status:   stopped
    Wallet:   880fdef3...
    LLM:      anthropic (claude-3-5-sonnet-20241022)
    Strategy: Hold SOL and stake for passive income...
    Created:  2024-01-16T08:15:00Z

Start Agent

karen agent start --name trader-bot

Output:

✅ Agent "trader-bot" started. It is now running autonomously.
   Loop interval: 30000ms
   Press Ctrl+C to stop.

The agent will:

Check its wallet balance
Analyze market conditions (simulated on devnet)
Execute trades via Jupiter DEX
Log all decisions and transactions
Repeat every 30 seconds

Agents run in the foreground. Use Ctrl+C to stop, or run in a process manager like PM2 for production.

Stop Agent

karen agent stop --name trader-bot

Chat with Agent

Send a message to an agent and get a response.

karen agent chat \
  --name trader-bot \
  --message "What is your current balance?"

Output:

⏳ Talking to trader-bot...

🤖 trader-bot:
   I currently have 1.5 SOL and 100.50 USDC in my wallet.

Server Commands

Start REST API Server

karen server start --port 3001

Options:

--port, -p

number

default:"3001"

Port number (can also set via API_PORT env var)

Output:

╔═══════════════════════════════════════════╗
║  ⚡ Karen — Autonomous Wallet Infrastructure  ║
║     for Solana AI Agents                    ║  
╚═══════════════════════════════════════════╝

🚀 Karen API server running on http://localhost:3001
   Health: http://localhost:3001/api/v1/health
   Docs:   See SKILLS.md for API reference

Press Ctrl+C to stop.

Start MCP Server

Start the Model Context Protocol server for Claude Desktop / OpenClaw integration.

karen server mcp

Output:

Karen MCP server running on stdio

The MCP server runs on stdio and is typically launched by the MCP client (Claude Desktop). See MCP Server for configuration.

Transaction Commands

List Transactions

View transaction history with optional wallet filter.

karen tx list --wallet my-wallet --limit 20

Options:

--wallet, -w

string

Filter by wallet name (omit for all wallets)

--limit, -l

number

default:"20"

Number of transactions to display

Output:

📋 Transactions (5):

  ✅ transfer_sol (tx-550e84...)
     Wallet: 660f9511...
     Tx: 5Kn8fGzXv...
     Time: 2024-01-15T12:30:00Z

  🛡️ transfer_sol (tx-770fabc...)
     Wallet: 660f9511...
     Error: Amount exceeds maxSolPerTransaction (2 SOL)
     Time: 2024-01-15T12:25:00Z

  ✅ swap (tx-880fdef...)
     Wallet: 660f9511...
     Tx: 3HnXdE4pM...
     Time: 2024-01-15T12:20:00Z

Info Command

Display Karen system information and health.

karen info

Output:

╔═══════════════════════════════════════════╗
║  ⚡ Karen — Autonomous Wallet Infrastructure  ║
║     for Solana AI Agents                    ║  
╚═══════════════════════════════════════════╝

  System Info:

    Solana:    Connected (devnet)
    Slot:      123456789
    Wallets:   3
    Agents:    2

Environment Variables

Karen reads configuration from .env:

.env

# Required
KEYSTORE_PASSWORD=your-secure-password

# Network (default: devnet)
SOLANA_NETWORK=devnet  # or mainnet-beta
SOLANA_RPC_URL=https://api.devnet.solana.com

# API Server (optional)
API_PORT=3001
API_SECRET=your-admin-secret

# LLM Providers (required for agents)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROK_API_KEY=xai-...
GEMINI_API_KEY=...

# Telegram (optional)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

Tips & Troubleshooting

Keystore location

By default, encrypted keystores are stored at ~/.karen/keystore.encTo use a custom location:

export KAREN_KEYSTORE_PATH=/custom/path/keystore.enc

Reset/delete wallets

Wallets are stored in the encrypted keystore. To reset:

rm ~/.karen/keystore.enc

Warning: This deletes all wallets. Export private keys first if you need to recover funds.

Change keystore password

Currently not supported. To change password:

Export all wallet private keys
Delete keystore
Recreate wallets with new password
Import private keys

Network switching

To switch between devnet and mainnet:

.env

SOLANA_NETWORK=mainnet-beta
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

Warning: Mainnet requires real SOL. Start on devnet for testing.

Next Steps

REST API

Integrate Karen via HTTP endpoints

TypeScript SDK

Use Karen as a library

MCP Server

Integrate with Claude Desktop

Build Agents

Create autonomous AI agents

Get Started

Core Concepts

Integration

Agent Skills

Development

​Overview

​Installation

​Global Options

​Wallet Commands

​Create Wallet

​List Wallets

​Check Balance

​Request Airdrop

​Send SOL

​Generate Master Mnemonic

​DeFi Wallet Commands

​Launch Token

​Mint Additional Supply

​Revoke Authority

​Stake SOL

​Unstake SOL

​Withdraw Stake

​List Stake Accounts

​Burn Tokens

​Close Token Account

​Wrap/Unwrap SOL

​Agent Commands

​Create Agent

​List Agents

​Start Agent

​Stop Agent

​Chat with Agent

​Server Commands

​Start REST API Server

​Start MCP Server

​Transaction Commands

​List Transactions

​Info Command

​Environment Variables

​Tips & Troubleshooting

​Next Steps

REST API

TypeScript SDK

MCP Server

Build Agents

Build docs developers (and LLMs) love

Overview

Installation

Global Options

Wallet Commands

Create Wallet

List Wallets

Check Balance

Request Airdrop

Send SOL

Generate Master Mnemonic

DeFi Wallet Commands

Launch Token

Mint Additional Supply

Revoke Authority

Stake SOL

Unstake SOL

Withdraw Stake

List Stake Accounts

Burn Tokens

Close Token Account

Wrap/Unwrap SOL

Agent Commands

Create Agent

List Agents

Start Agent

Stop Agent

Chat with Agent

Server Commands

Start REST API Server

Start MCP Server

Transaction Commands

List Transactions

Info Command

Environment Variables

Tips & Troubleshooting

Next Steps