npm package: @horneross/cli
Description: Terminal interface for Horneross AI agents
Author: Horneross Team
Latest version: 0.6.3

# @horneross/cli

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

## Installation

### Development (from monorepo)

```bash
cd packages/cli
pnpm install
pnpm build

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

### Global Installation (Future)

```bash
npm install -g @horneross/cli
```

## Quick Start

### 1. Initialize Configuration

```bash
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

```bash
horneross chat "Hello, how are you?"
```

### 3. Interactive Mode

```bash
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:**

```bash
# 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:**

```bash
# 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`:

```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:

```bash
# 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

```bash
pnpm build
```

### Watch Mode

```bash
pnpm dev
```

### Type Check

```bash
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:

```bash
horneross config show
```

Re-run `horneross config init` if needed.

### "Connection failed"

Ensure the Horneross API server is running:

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

## License

MIT