@proofs-io/shotgun

Shotgun CLI

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

Installation

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

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

Usage

Interactive Mode

# Start the interactive CLI
$ shotgun-cli

Non-Interactive Mode

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

# 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

# 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

# In interactive mode, use the slash command
/status

Non-Interactive Mode

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

• WebSocket Connection - Verifies connection to shotgund server
• Shotgund Health Check - Calls REST API health endpoint
• Provider Configuration - Lists configured LLM providers and API keys
• 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

# 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