@horneross/cli

Terminal interface for Horneross AI agents - interact with your agents directly from the command line.

Installation

Development (from monorepo)

cd packages/cli
pnpm install
pnpm build

# Test locally
node dist/index.js --help

Global Installation (Future)

npm install -g @horneross/cli

Quick Start

1. Initialize Configuration

horneross config init

You'll be prompted for:

• Agent name: A friendly name (e.g., "adam")
• Agent ID: Your agent's ID (e.g., clrz0tn6h000108kxfyomdzxg)
• API Key: Your agent's API key
• Base URL: API endpoint (default: http://localhost:3000)

Configuration is saved to ~/.horneross/config.yaml.

2. Send a Message

horneross chat "Hello, how are you?"

3. Interactive Mode

horneross interactive

Start a continuous conversation. Type exit to quit.

Commands

horneross chat <message>

Send a one-shot message to your agent.

Options:

• -a, --agent <name> - Use a specific agent (default: configured default agent)
• --conversation-id <id> - Continue an existing conversation

Examples:

# Basic chat
horneross chat "What is TypeScript?"

# Use specific agent
horneross chat "Generate a PDF report" --agent adam

# Continue conversation
horneross chat "Tell me more" --conversation-id abc123

horneross interactive

Start an interactive chat session (REPL mode).

Options:

• -a, --agent <name> - Use a specific agent

Examples:

# Interactive session with default agent
horneross interactive

# Interactive session with specific agent
horneross interactive --agent adam

In interactive mode:

• Type messages and press Enter
• Conversation persists across messages
• Type exit or press Ctrl+C to quit

horneross config init

Initialize or update CLI configuration.

horneross config show

Display current configuration.

Configuration File

Configuration is stored at ~/.horneross/config.yaml:

default_agent: adam
base_url: http://localhost:3000

agents:
  adam:
    id: clrz0tn6h000108kxfyomdzxg
    api_key: f7d3174f-4335-4a2b-bb02-416453ea2099
    name: Adam

Multiple Agents

You can configure multiple agents and switch between them:

# Add second agent
horneross config init
# Enter "maria" as name, then her ID and API key

# Use specific agent
horneross chat "Hello" --agent maria

Features

✅ Phase 1 MVP (Complete)

• ✅ One-shot chat command
• ✅ Configuration management
• ✅ SSE streaming support
• ✅ Tool execution visualization (spinners)
• ✅ Interactive REPL mode
• ✅ Bearer token authentication

🚧 Future Phases

• File attachments (--attach)
• Markdown rendering with syntax highlighting
• Conversation history management
• Tab completion
• Multi-agent switching improvements

Architecture

The CLI is a pure HTTP client that consumes the existing Horneross API:

Terminal → CLI → HTTP POST /api/v2/agent/{agentId}/chat → ChatService → Agent
                                                               ↓
                                                          SSE Response
                                                               ↓
                                                        Stream Adapter
                                                               ↓
                                                            stdout

Key Components

• ConfigManager (src/config/config-manager.ts) - YAML config handling
• StreamAdapter (src/adapters/stream-adapter.ts) - SSE → terminal output
• AuthManager (src/auth/auth-manager.ts) - API key validation
• Commands (src/commands/) - CLI command implementations

Development

Build

pnpm build

Watch Mode

pnpm dev

Type Check

pnpm typecheck

Troubleshooting

"No default agent configured"

Run horneross config init to set up your configuration.

"Authentication failed"

Verify your API key and agent ID are correct:

horneross config show

Re-run horneross config init if needed.

"Connection failed"

Ensure the Horneross API server is running:

# In the main project
pnpm dev  # Should run on http://localhost:3000

License

MIT