Automagik CLI

A powerful TypeScript-based CLI chat application for interacting with Automagik Hive multi-agent AI systems. Built with React and designed for seamless integration with Automagik Hive instances.

Quick Start

# 1. Prerequisites
npm install -g pnpm    # Install pnpm package manager
# Ensure Node.js >= 20 and API server running at localhost:8886

# 2. Installation
git clone https://github.com/namastexlabs/automagik-cli.git
cd automagik-cli
pnpm install

# 3. Start interactive mode
pnpm run dev

# 4. Or use headless mode
pnpm run build
./bundle/automagik-cli.js --prompt "Hello" --target "your-agent-id"

Features

• 🎯 Multi-Target Support: Connect to agents, teams, and workflows
• 🔄 Real-time Streaming: Live response streaming with visual indicators
• 💾 Session Management: Persistent conversation history
• ⚙️ Environment Configuration: All settings via .env files
• 🎨 Rich UI: Beautiful terminal interface with React components
• 🔌 Hot Reload: Development mode with instant feedback

Prerequisites

• Node.js >= 20
• pnpm >= 10.12.4 (package manager - install with npm install -g pnpm)
• Automagik Hive instance running (default: http://localhost:8886)

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g automagik-cli

# Use directly with npx
npx automagik-cli --prompt "Hello" --target "agent-id"

Option 2: Development Installation

# Clone the repository
git clone https://github.com/namastexlabs/automagik-cli.git
cd automagik-cli

# Install dependencies
pnpm install

# Copy environment configuration
cp .env.example .env

# Edit configuration as needed
nano .env

Configuration

All configuration is done via environment variables in the .env file. Note that API_BASE_URL is required and must be set:

# API Server Configuration
API_BASE_URL=http://localhost:8886
API_TIMEOUT=30000
API_RETRY_ATTEMPTS=3

# CLI Configuration
CLI_DEBUG=false

# Session Configuration
SESSION_DIR=~/.automagik-cli/sessions
SESSION_MAX_HISTORY=100
SESSION_AUTO_SAVE=true

# Display Configuration
ENABLE_COLORS=true
ENABLE_SPINNER=true
MAX_DISPLAY_WIDTH=200

# Development Configuration
NODE_ENV=production
LOG_LEVEL=error

Usage

The Automagik CLI provides two modes of operation:

Interactive Mode (Default)

The default mode provides a rich terminal UI for chatting with agents, teams, and workflows.

Development Mode

# Start in development mode with hot reload
pnpm run dev

# Or manually
pnpm run start

Production Mode

# Build the application
pnpm run build

# Run in production mode
NODE_ENV=production pnpm run start

# Or run the bundle directly
./bundle/automagik-cli.js

Headless Mode (CLI)

For automation, scripting, and non-interactive usage, the CLI supports headless mode with direct command-line execution.

Basic Usage

# Direct execution with prompt
automagik-cli --prompt "Hello, how are you?" --target "agent-id"

# Specify output format
automagik-cli --prompt "Generate a report" --target "team-id" --output json

# Continue existing session
automagik-cli --prompt "Follow up question" --target "agent-id" --session "session-123"

Command Reference

| Option | Description | Required | Default | |--------|-------------|----------|---------| | --prompt | Message to send to the target | Yes | - | | --target | Target ID (agent, team, or workflow) | Yes | - | | --session | Session ID to continue | No | New session | | --output | Output format: text, json, markdown | No | text |

Examples

# Chat with an agent
automagik-cli --prompt "Explain quantum computing" --target "science-agent"

# Execute a workflow with JSON output
automagik-cli --prompt "Process user data" --target "data-workflow" --output json

# Continue a conversation
automagik-cli --prompt "Can you elaborate?" --target "assistant" --session "conv-456"

# Use in scripts
RESULT=$(automagik-cli --prompt "Analyze logs" --target "dev-team" --output json)
echo $RESULT | jq '.data'

CLI Reference

Interactive Mode Commands

pnpm run dev           # Start in development mode with hot reload
pnpm run start         # Start in production mode
pnpm run build         # Build for production
./bundle/automagik-cli.js  # Run built executable

Headless Mode Options

automagik-cli [OPTIONS]

Required:
  --prompt <message>     Message to send to the target
  --target <id>          Target ID (agent, team, or workflow)

Optional:
  --session <id>         Session ID to continue (default: new session)
  --output <format>      Output format: text|json|markdown (default: text)
  --help                 Show help information
  --version              Show version information

Interactive Mode Controls

• Type messages: Chat with the selected agent/team/workflow
• Enter: Send message
• Ctrl+C or Ctrl+D (twice): Exit
• Tab: Navigate between UI elements
• Arrow keys: Navigate message history when available

Interactive Mode Features

• Target Selection: Choose between agents, teams, and workflows
• Session Management: Create new sessions or continue existing ones
• Real-time Streaming: Watch responses stream in real-time with visual indicators
• Event Visualization: See tool calls, memory updates, and thinking processes
• Session Persistence: Conversations automatically saved to ~/.automagik-cli/sessions/

API Integration

The CLI automatically discovers and connects to:

• Agents: Individual AI agents at /playground/agents
• Teams: Agent teams with routing at /playground/teams
• Workflows: Automated workflows at /playground/workflows

Required API Endpoints

Your local API server should provide:

GET  /openapi.json                # OpenAPI schema
GET  /api/v1/health              # Health check
GET  /playground/agents          # List available agents
GET  /playground/teams           # List available teams
GET  /playground/workflows       # List available workflows

POST /playground/agents/{id}/runs    # Invoke agent
POST /playground/teams/{id}/runs     # Invoke team
POST /playground/workflows/{id}/runs # Execute workflow

Response Format

Expected response format:

{
  "data": "response content",
  "error": null,
  "session_id": "session-123"
}

Advanced Streaming Events

The CLI supports rich real-time streaming with detailed event visualization:

Event Types

• agent_start / team_start: Target initialization
• tool_call_start: Tool execution begins with arguments
• tool_call_complete: Tool execution results
• memory_update: Memory state changes
• thinking: AI reasoning processes
• rag_query: Retrieval-augmented generation queries
• content: Response content streaming
• run_complete: Execution finished

Visual Indicators

• Spinners: Active processing indicators
• Progress: Real-time tool execution status
• Syntax Highlighting: Code and data formatting
• Event Timeline: Chronological process visualization

Development

Project Structure

src/
├── config/
│   ├── settings.ts      # Environment configuration
│   └── localClient.ts   # API client
├── ui/
│   ├── App.tsx          # Main application
│   ├── types.ts         # Type definitions
│   ├── components/      # React components
│   ├── contexts/        # React contexts
│   └── hooks/           # Custom hooks
└── index.ts             # Entry point

Building

# Clean build
pnpm run clean

# TypeScript compilation
pnpm run typecheck

# Create bundle
pnpm run bundle

# Full build process
pnpm run build

Key Components

• App.tsx: Main application with session management
• localClient.ts: HTTP client for API communication
• useLocalAPIStream: Streaming hook for real-time responses
• SessionContext: Persistent conversation management
• StreamingContext: Real-time state management

Troubleshooting

Common Issues

1. Connection Failed

   Error: Cannot connect to API server

   • Check API server: Ensure server is running at http://localhost:8886 (or your configured URL)
   • Verify endpoints: API server must provide /api/v1/health and /playground/* endpoints
   • Network connectivity: Test with curl http://localhost:8886/api/v1/health
   • Configuration: Verify API_BASE_URL in .env file

2. Package Manager Errors

   Error: npm ERR! ENOENT: no such file or directory

   • Use pnpm: This project requires pnpm, not npm
   • Install pnpm: npm install -g pnpm
   • Clear cache: pnpm store prune if installation fails

3. Build Errors

   Error: TypeScript compilation failed

   • Node.js version: Ensure Node.js >= 20 (node --version)
   • Dependencies: Run pnpm install to update dependencies
   • Type checking: pnpm run typecheck for detailed type errors
   • Clean build: pnpm run clean && pnpm run build

4. Streaming Issues

   Error: Response streaming timeout

   • API compatibility: Verify API supports streaming JSON responses
   • Timeout configuration: Increase API_TIMEOUT in .env
   • Debug mode: Enable CLI_DEBUG=true for detailed streaming logs
   • Network: Check for proxy or firewall issues

5. Session Errors

   Error: Cannot write to session directory

   • Permissions: Ensure write access to ~/.automagik-cli/sessions/
   • Directory: Create manually if needed: mkdir -p ~/.automagik-cli/sessions
   • Configuration: Set custom path with SESSION_DIR in .env

Debug Mode

Enable debug mode for detailed logging:

# In .env file
CLI_DEBUG=true

# Or via environment variable
CLI_DEBUG=true pnpm run dev

Session Management

Sessions are automatically saved to ~/.automagik-cli/sessions/ as JSON files:

{
  "id": "session-123",
  "messages": [...],
  "createdAt": 1641234567890,
  "updatedAt": 1641234567890,
  "metadata": {
    "totalMessages": 10,
    "lastTarget": {
      "type": "agent",
      "id": "emissao"
    }
  }
}

Contributing

This CLI was built by stripping down the Gemini CLI and replacing Gemini-specific functionality with local API integration. Key changes:

• Removed Google authentication
• Replaced Gemini API with local HTTP client
• Simplified command system
• Added environment-based configuration
• Preserved React-based UI framework

License

Based on the Gemini CLI (Apache 2.0), modified for local API integration.