npm package: @proofs-io/shotgun
Description: An interactive command-line interface for the Shotgun multi-agent platform. Built on the [Shotgun SDK](/shotgun-sdk), this CLI implements the WebSocket v2 protocol for agent communication, lifecycle management, and real-time interaction with the multi-age
Latest version: 0.9.2

# Shotgun CLI

An interactive command-line interface for the Shotgun multi-agent platform. Built on the [Shotgun SDK](/shotgun-sdk), this CLI implements the WebSocket v2 protocol for agent communication, lifecycle management, and real-time interaction with the multi-agent system.

## Installation

```bash
# Install globally
$ npm install --global shotgun-cli

# Or use locally with pnpm
$ pnpm install
$ pnpm build
```

## Usage

### Interactive Mode

```bash
# Start the interactive CLI
$ shotgun-cli

```

### Non-Interactive Mode

```bash
# Execute commands directly
$ shotgun-cli agent list
$ shotgun-cli agent spawn simple_agent
$ shotgun-cli agent terminate agent-123

# Use with output formats
$ shotgun-cli agent list --json
$ shotgun-cli agent list --csv
$ shotgun-cli agent list --plain

# Show help
$ shotgun-cli --help
$ shotgun-cli help
```

## Commands

### Interactive Mode Commands

When in interactive chat mode, you can use these commands:

#### General Commands

- `/help` - Display available commands
- `/status` - Show system health status and configuration
- Regular text messages - Send messages to agents

#### Agent Control Commands

- `/agent spawn <type> [config]` - Spawn a new agent
- `/agent terminate <id>` - Terminate a specific agent
- `/agent suspend <id>` - Suspend an agent
- `/agent resume <id>` - Resume a suspended agent
- `/agent list` - List all active agents

### Non-Interactive Mode Commands

Execute commands directly from the command line:

```bash
# Agent management
$ shotgun-cli agent list
$ shotgun-cli agent spawn <type> [config]
$ shotgun-cli agent terminate <id>
$ shotgun-cli agent suspend <id>
$ shotgun-cli agent resume <id>

# System status
$ shotgun-cli status
$ shotgun-cli status --json

# Help
$ shotgun-cli help
$ shotgun-cli help agent
```

### Examples

```bash
# Interactive mode examples
/agent spawn simple_agent {"name": "MyAgent"}
/agent list
/agent terminate agent-123
/status

# Non-interactive mode examples
$ shotgun-cli agent spawn simple_agent
$ shotgun-cli agent list --json
$ shotgun-cli agent terminate agent-123
$ shotgun-cli status --json
```

## Status Command

The `/status` command provides comprehensive health checks for the Shotgun system:

### Interactive Mode
```bash
# In interactive mode, use the slash command
/status
```

### Non-Interactive Mode
```bash
# Basic status check
$ shotgun-cli status

# JSON output for scripting
$ shotgun-cli status --json

# Exit codes: 0 = healthy, 1 = unhealthy or error
$ shotgun-cli status && echo "System is healthy"
```

### Health Checks

The status command performs these checks:

1. **WebSocket Connection** - Verifies connection to shotgund server
2. **Shotgund Health Check** - Calls REST API health endpoint
3. **Provider Configuration** - Lists configured LLM providers and API keys
4. **CLI Version** - Reports current CLI version

### Status Output

The status report includes:
- Overall system health (healthy/unhealthy/unknown)
- Individual check results with details and error messages
- CLI version information  
- Timestamp of the check

### Exit Codes

In non-interactive mode, the command returns:
- `0` - System is healthy
- `1` - System is unhealthy or check failed

This makes it suitable for use in scripts and monitoring systems.


## Features

- **Real-time WebSocket Communication**: Connects to the Shotgun server for instant messaging
- **Agent Management**: Full lifecycle control over agents (spawn, terminate, suspend, resume)
- **Conversation Management**: Automatic conversation creation and event subscriptions
- **Message Types**: Support for user messages, agent responses, system messages, and errors
- **Session Persistence**: Unique user and session IDs for tracking conversations
- **Status Indicator**: Visual connection status in the interface
- **Multiple Output Formats**: JSON, CSV, plain text, and formatted tables
- **Command Autocomplete**: Live suggestions with descriptions in interactive mode

## Development

```bash
# Install dependencies
$ pnpm install

# Build the project
$ pnpm build

# Watch mode for development
$ pnpm build:watch

# Run tests
$ pnpm test

# Format code
$ pnpm format

# Regenerate TypeScript schemas from protocol.json
$ pnpm codegen
```

## Architecture

The CLI is built with:
- **Ink**: React-based framework for building CLI apps
- **TypeScript**: Type-safe development
- **Zod**: Runtime validation for WebSocket messages
- **WebSocket**: Real-time bidirectional communication
- **Zustand**: State management for messages and connection status

## Protocol Compatibility

This CLI implements the Shotgun WebSocket protocol v2.0, supporting:
- Request/Response pattern for method-based operations
- Event messages for bidirectional event streaming
- Control messages for connection management
- Error messages for error handling
- Unified message structure with correlation support