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 /agents
Teams: Agent teams with routing at /teams
Workflows: Automated workflows at /workflows

Required API Endpoints

Your local API server should provide:

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

POST /agents/{id}/runs           # Invoke agent
POST /teams/{id}/runs            # Invoke team
POST /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

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 /health, /agents, /teams, and /workflows endpoints
- Network connectivity: Test with curl http://localhost:8886/health
- Configuration: Verify API_BASE_URL in .env file
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
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
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
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.

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.claude		.claude
.genie		.genie
scripts		scripts
src		src
.env.backup		.env.backup
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
RESPONSIVE_IMPLEMENTATION.md		RESPONSIVE_IMPLEMENTATION.md
esbuild.config.js		esbuild.config.js
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
test-cli-fix.sh		test-cli-fix.sh
test_input_fix.sh		test_input_fix.sh
tsconfig.json		tsconfig.json

License

namastexlabs/automagik-cli

Folders and files

Latest commit

History

Repository files navigation

Automagik CLI

Quick Start

Features

Prerequisites

Installation

Option 1: Install from npm (Recommended)

Option 2: Development Installation

Configuration

Usage

Interactive Mode (Default)

Development Mode

Production Mode

Headless Mode (CLI)

Basic Usage

Command Reference

Examples

CLI Reference

Interactive Mode Commands

Headless Mode Options

Interactive Mode Controls

Interactive Mode Features

API Integration

Required API Endpoints

Response Format

Advanced Streaming Events

Event Types

Visual Indicators

Development

Project Structure

Building

Key Components

Troubleshooting

Common Issues

Debug Mode

Session Management

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 4

Uh oh!

Languages

Packages