Effect AI CLI

A comprehensive TypeScript CLI application built with Effect-TS for managing AI-powered pattern processing, run management, and observability.

Overview

The Effect AI CLI is a production-ready command-line interface that demonstrates advanced Effect-TS patterns including service composition, resource management, observability, and AI integration. It provides tools for managing AI workflows, tracking metrics, and maintaining run history.

Execution Plans:

• By default, LLM calls use an ExecutionPlan with sensible retries and provider fallbacks.
• You can override attempts and timing and also customize fallback provider/model order with the plan command.

Features

Core Capabilities

• AI Integration: Seamless integration with multiple AI providers (OpenAI, Anthropic, Google)
• Run Management: Complete lifecycle management for AI processing runs
• Metrics Tracking: Comprehensive metrics collection and reporting
• Observability: Full OpenTelemetry integration for tracing and monitoring
• Configuration Management: Flexible configuration with environment variables
• Authentication: Secure API key management
• Extensibility: Plugin system to add custom commands via CliPlugin

Development Setup

Prerequisites

• Node.js 20+
• Bun (recommended package manager)

Installation

# Clone the repository
git clone <repository-url>
cd effect-ai-cli

# Install dependencies
bun install

# Build the project
bun run build

# Run tests
bun run test

# Start development mode
bun run dev

Available Scripts

• bun run build - Build the project
• bun run build:watch - Build with watch mode
• bun run dev - Start development mode with watch
• bun run start - Run the CLI directly
• bun run test - Run tests
• bun run test:watch - Run tests in watch mode
• bun run test:coverage - Run tests with coverage
• bun run test:ui - Run tests with UI
• bun run lint - Run linter
• bun run lint:fix - Fix linting issues
• bun run format - Format code
• bun run type-check - Type check without building

Quick Start

# Generate (streams by default)
effect-ai-cli generate "Write a haiku about Effect"

# Configure execution plan overrides
effect-ai-cli plan create --retries 2 --retry-ms 1200 \
  --fallbacks openai:gpt-4o-mini,anthropic:claude-3-5-haiku
effect-ai-cli plan list

# View metrics for recent runs
effect-ai-cli metrics last
effect-ai-cli metrics report --format console

Commands

Core Commands

• effect-ai-cli list - List available patterns
• effect-ai-cli generate (alias gen) - Generate with AI
  • Input forms: inline text, file path, or stdin (--stdin)
  • Streaming by default for text format; buffer with --no-stream
  • -o, --output <path> write full output to file (tee when streaming)
  • -p, --provider <openai|anthropic|google> select provider
  • -m, --model <name> select model
  • -f, --format <text|json> select output format (default: text)
  • --json convenience for --format=json
  • -s, --schema-prompt <file> required when --format=json
  • --quiet suppress stdout (useful with --output)
  • Generation params: --temperature, --max-tokens, --top-p, --seed
• effect-ai-cli health - Check system health
• effect-ai-cli config - Manage configuration
• effect-ai-cli auth - Manage authentication
• effect-ai-cli model - Manage AI models
• effect-ai-cli trace - View traces
• effect-ai-cli dry-run - Test without execution

Execution Plan Management

• effect-ai-cli plan create — Set plan overrides
  • --retries <n> number of retries for the primary provider (attempts = retries + 1). Default: 1 retry
  • --retry-ms <ms> delay between attempts for the primary. Default: 1000
  • --fallbacks <list> comma-separated provider:model fallbacks, e.g. openai:gpt-4o-mini,anthropic:claude-3-5-haiku
• effect-ai-cli plan list — Show the current plan (effective defaults if unset)
• effect-ai-cli plan clear — Remove overrides
• effect-ai-cli plan reset — Reset to defaults

Defaults

• Primary: 2 attempts (1 retry) with 1000ms spacing
• Fallbacks: openai:gpt-4o-mini then anthropic:claude-3-5-haiku, each 1 attempt with 1500ms spacing

Note: process-prompt remains available as a legacy alias for backward compatibility.

Run Management

• effect-ai-cli runs list - List all runs
• effect-ai-cli runs create - Create a new run
• effect-ai-cli runs update - Update run information
• effect-ai-cli runs delete - Delete a run

Metrics

• effect-ai-cli metrics report — Report metrics
  • --format <console|json|jsonl> (default: console)
  • -o, --output <path> when json or jsonl, write to file
• effect-ai-cli metrics last — Pretty table for the most recent run
• effect-ai-cli metrics clear — Clear metrics history

Architecture

Service Architecture

The CLI uses a modern Effect-TS service architecture with:

• Effect.Service Pattern: All services use the modern Effect.Service pattern
• Layer Composition: Proper service layer composition with dependency injection
• Resource Management: Scoped resource management with automatic cleanup
• Error Handling: Comprehensive error handling with typed errors
• Testing: Full test coverage with real services (no mocks)

Project Structure

src/
├── bin/           # CLI entry points
├── commands/      # CLI command implementations
├── config/        # Configuration constants
├── core/          # Core CLI framework
├── runtime/       # Runtime configurations
├── services/      # Business logic services
└── __tests__/     # Test files

Contributing

See CONTRIBUTING.md for development guidelines.

Release Process

• CHANGELOG.md - Version history and changes
• docs/SEMANTIC_VERSIONING.md - Versioning strategy and policies
• docs/RELEASE_WORKFLOW.md - Release process and workflow

License

This project is licensed under the MIT License - see the LICENSE file for details.