adl-cli

command module

v0.7.2 Latest Latest Go to latest Published: Sep 2, 2025 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/inference-gateway/adl-cli

Links

Open Source Insights

README ¶

ADL CLI

A command-line interface for generating production-ready A2A (Agent-to-Agent) servers from Agent Definition Language (ADL) files.

⚠️ Early Development Warning: This project is in its early stages of development. Breaking changes are expected and acceptable until we reach a stable version. Use with caution in production environments.

Overview

The ADL CLI helps you build production-ready A2A agents quickly by generating complete project scaffolding from YAML-based Agent Definition Language (ADL) files. It eliminates boilerplate code and ensures consistent patterns across your agent implementations.

Key Features

🚀 Rapid Development - Generate complete projects in seconds
📋 Schema-Driven - Use YAML Agent Definition Language files (ADL) to define your agents
🎯 Production Ready - Single unified template with AI integration and enterprise features
🔐 Enterprise Features - Authentication, SCM integration, and audit logging
🛠️ Smart Ignore - Protect your implementations with .adl-ignore files
✅ Validation - Built-in ADL schema validation
🛠️ Interactive Setup - Guided project initialization with extensive CLI options
🔧 CI/CD Generation - Automatic GitHub Actions and GitLab CI workflows
🏗️ Sandbox Environments - Flox and DevContainer support for isolated development
🤖 Multi-Provider AI - OpenAI, Anthropic, Azure, Ollama, and DeepSeek support

Installation

Quick Install (Recommended)

Use our install script to automatically download and install the latest binary:

curl -fsSL https://raw.githubusercontent.com/inference-gateway/adl-cli/main/install.sh | bash

Or download and run the script manually:

wget https://raw.githubusercontent.com/inference-gateway/adl-cli/main/install.sh
chmod +x install.sh
./install.sh

Install Options:

Install specific version: ./install.sh --version v1.0.0
Custom install directory: INSTALL_DIR=~/bin ./install.sh
Show help: ./install.sh --help

From Source

git clone https://github.com/inference-gateway/adl-cli.git
cd adl-cli
go install .

Using Go Install

go install github.com/inference-gateway/adl-cli@latest

Pre-built Binaries

Download pre-built binaries from the releases page.

Quick Start

1. Initialize a New Project

# Interactive project setup
adl init my-weather-agent

# Or generate from an existing ADL file
adl generate --file agent.yaml --output ./test-my-agent

2. Implement Your Business Logic

The generated project includes TODO placeholders for your implementations:

// TODO: Implement weather API logic
func GetWeatherTool(ctx context.Context, args map[string]interface{}) (string, error) {
    city := args["city"].(string)
    // TODO: Replace with actual weather API call
    return fmt.Sprintf(`{"city": "%s", "temp": "22°C"}`, city), nil
}

3. Build and Run

cd test-weather-agent
task build
task run

Usage

Commands

Command	Description
`adl init [name]`	Initialize a new project interactively with comprehensive options
`adl generate`	Generate project from ADL file with CI/CD and sandbox support
`adl validate [file]`	Validate an ADL file against the complete schema

Init Command

The adl init command provides a comprehensive interactive wizard for creating new A2A agent projects:

# Interactive project setup
adl init my-weather-agent

# Use defaults for all prompts
adl init my-agent --defaults

# Non-interactive with specific configuration
adl init my-agent \
  --name "Weather Agent" \
  --description "Provides weather information" \
  --provider openai \
  --model gpt-4o-mini \
  --language go \
  --flox \
  --overwrite

Init Command Options

The init command supports extensive configuration options:

Project Settings:

--defaults - Use default values for all prompts
--path - Project directory path
--name - Agent name
--description - Agent description
--version - Agent version
--overwrite - Overwrite existing files

Agent Configuration:

--type - Agent type (ai-powered/minimal)
--provider - AI provider (openai/anthropic/azure/ollama/deepseek)
--model - AI model name
--system-prompt - System prompt for the agent
--max-tokens - Maximum tokens (integer)
--temperature - Temperature (0.0-2.0)

Capabilities:

--streaming - Enable streaming responses
--notifications - Enable push notifications
--history - Enable state transition history

Server Configuration:

--port - Server port (integer)
--debug - Enable debug mode

Language-Specific Options:

--language - Programming language (go/rust/typescript)

Go Options:

--go-module - Go module path (e.g., github.com/user/project)
--go-version - Go version (e.g., 1.24)

Rust Options:

--rust-package-name - Rust package name
--rust-version - Rust version (e.g., 1.88)
--rust-edition - Rust edition (e.g., 2024)

TypeScript Options:

--typescript-name - TypeScript package name

Environment Options:

--flox - Enable Flox environment
--devcontainer - Enable DevContainer environment

Generate Command

# Generate project from ADL file
adl generate --file agent.yaml --output ./test-my-agent

# Overwrite existing files (respects .adl-ignore)
adl generate --file agent.yaml --output ./test-my-agent --overwrite

# Generate with CI workflow configuration
adl generate --file agent.yaml --output ./test-my-agent --ci

Generate Flags

Flag	Description
`--file`, `-f`	ADL file to generate from (default: "agent.yaml")
`--output`, `-o`	Output directory for generated code (default: ".")
`--template`, `-t`	Template to use (default: "minimal")
`--overwrite`	Overwrite existing files (respects .adl-ignore)
`--ci`	Generate CI workflow configuration (GitHub Actions, GitLab CI)

CI Generation Features:

Automatic Provider Detection: Detects GitHub/GitLab from ADL spec.scm.provider
Language-Specific Workflows: Tailored CI configurations for Go, Rust, and TypeScript
Version Integration: Uses language versions from ADL configuration
Task Integration: Leverages generated Taskfile for consistent build processes
Caching: Includes dependency caching for faster builds

Agent Definition Language (ADL)

ADL files use YAML to define your agent's configuration, capabilities, and tools.

Example ADL File

apiVersion: adl.dev/v1
kind: Agent
metadata:
  name: weather-agent
  description: "Provides weather information for cities worldwide"
  version: "1.0.0"
spec:
  capabilities:
    streaming: true
    pushNotifications: false
    stateTransitionHistory: false
  agent:
    provider: openai
    model: gpt-4o-mini
    systemPrompt: "You are a helpful weather assistant."
    maxTokens: 4096
    temperature: 0.7
  tools:
    - name: get_weather
      description: "Get current weather for a city"
      schema:
        type: object
        properties:
          city:
            - type: string
              description: "City name"
          country:
            - type: string
              description: "Country code"
        required:
          - city
  server:
    port: 8080
    debug: false
  language:
    go:
      module: "github.com/example/weather-agent"
      version: "1.24"

ADL Schema

The complete ADL schema includes:

metadata: Agent name, description, and version
capabilities: Streaming, notifications, state history
agent: AI provider configuration (OpenAI, Anthropic, Azure, Ollama, DeepSeek)
tools: Function definitions with complex JSON schemas and validation
server: HTTP server configuration with authentication support
language: Programming language-specific settings (Go, Rust, TypeScript)
scm: Source control management configuration (GitHub, GitLab)
sandbox: Development environment configuration (Flox, DevContainer)

Complete ADL Example

apiVersion: adl.dev/v1
kind: Agent
metadata:
  name: advanced-agent
  description: "Enterprise agent with full feature set"
  version: "1.0.0"
spec:
  capabilities:
    streaming: true
    pushNotifications: true
    stateTransitionHistory: true
  agent:
    provider: openai
    model: gpt-4o-mini
    systemPrompt: |
      You are a helpful assistant with enterprise capabilities.
      Always prioritize security and compliance.
    maxTokens: 8192
    temperature: 0.3
  tools:
    - name: query_database
      description: "Execute database queries with validation"
      schema:
        type: object
        properties:
          query:
            type: string
            description: "SQL query to execute"
          table:
            type: string
            description: "Target table name"
          limit:
            type: integer
            description: "Result limit"
            maximum: 1000
        required: [query, table]
    - name: send_notification
      description: "Send multi-channel notifications"
      schema:
        type: object
        properties:
          recipient:
            type: string
            description: "Recipient identifier"
          message:
            type: string
            description: "Message content"
          priority:
            type: string
            enum: ["low", "medium", "high", "critical"]
          channel:
            type: string
            enum: ["email", "slack", "teams", "webhook"]
        required: [recipient, message, priority, channel]
  server:
    port: 8443
    debug: false
    auth:
      enabled: true
  language:
    go:
      module: "github.com/company/advanced-agent"
      version: "1.24"
  scm:
    provider: github
    url: "https://github.com/company/advanced-agent"
  sandbox:
    flox:
      enabled: true

Generated Project Structure

The ADL CLI generates comprehensive project scaffolding tailored to your chosen language:

Go Project Structure

my-go-agent/
├── main.go                    # Main server setup
├── go.mod                     # Go module definition
├── tools/                     # Tool implementations directory
│   ├── query_database.go      # Individual tool files (TODO placeholders)
│   └── send_notification.go
├── Taskfile.yml               # Development tasks (build, test, lint)
├── Dockerfile                 # Container configuration
├── .adl-ignore                # Files to protect from regeneration
├── .well-known/
│   └── agent.json             # Agent capabilities (auto-generated)
├── .github/workflows/         # Generated when using --ci flag
│   └── ci.yml                 # GitHub Actions workflow
├── k8s/
│   └── deployment.yaml        # Kubernetes deployment manifest
├── .flox/                     # Generated when sandbox: flox
│   ├── env/manifest.toml
│   ├── env.json
│   ├── .gitignore
│   └── .gitattributes
├── .gitignore                 # Standard Git ignore patterns
├── .gitattributes             # Git attributes configuration
├── .editorconfig              # Editor configuration
└── README.md                  # Project documentation with setup instructions

Rust Project Structure

my-rust-agent/
├── src/
│   ├── main.rs                # Main application entry point
│   └── tools/                 # Tool implementations directory
│       ├── mod.rs             # Module declarations
│       ├── query_database.rs  # Individual tool implementations
│       └── send_notification.rs
├── Cargo.toml                 # Rust package configuration
├── Taskfile.yml               # Development tasks
├── Dockerfile                 # Rust-optimized container
├── .adl-ignore                # Protection configuration
├── .well-known/
│   └── agent.json             # Agent capabilities
├── .github/workflows/         # CI configuration (with --ci)
│   └── ci.yml                 # Rust-specific workflow
├── k8s/
│   └── deployment.yaml        # Kubernetes deployment
└── README.md                  # Documentation

Universal Generated Files

All projects include these essential files regardless of language:

.well-known/agent.json - A2A agent discovery and capabilities manifest
Taskfile.yml - Unified task runner configuration for build, test, lint, run
Dockerfile - Language-optimized container configuration
k8s/deployment.yaml - Kubernetes deployment manifest
.adl-ignore - Protects user implementations from overwrite
CI Workflows - When using --ci flag, generates appropriate workflows:
- GitHub Actions: .github/workflows/ci.yml
- GitLab CI: .gitlab-ci.yml (planned)
Development Environment - Based on sandbox configuration:
- Flox: .flox/ directory with environment configuration when sandbox.flox.enabled: true
- DevContainer: .devcontainer/devcontainer.json when sandbox.devcontainer.enabled: true

CI Integration

When using the --ci flag, the ADL CLI generates GitHub Actions workflows for your project:

# Generate project with CI workflow
adl generate --file agent.yaml --output ./test-my-agent --ci

This creates a GitHub Actions workflow (.github/workflows/ci.yml) that includes:

Automated Testing: Runs all tests on every push and pull request
Code Quality: Format checking and linting
Multi-Environment: Supports main and develop branches
Caching: Go module caching for faster builds
Task Integration: Uses the generated Taskfile for consistent build steps

The generated workflow automatically detects your Go version from the ADL file and configures the appropriate environment.

Sandbox Environments

The ADL CLI supports multiple development environments for isolated, reproducible development:

Flox Environment

Configure Flox for your project by adding to your ADL file:

spec:
  sandbox:
    flox:
      enabled: true

Generated files:

.flox/env/manifest.toml - Flox environment manifest with language-specific dependencies
.flox/env.json - Environment configuration
.flox/.gitignore - Flox-specific ignore patterns
.flox/.gitattributes - Git attributes for Flox files

DevContainer Environment

Configure DevContainer for your project:

spec:
  sandbox:
    devcontainer:
      enabled: true

Generated files:

.devcontainer/devcontainer.json - VS Code DevContainer configuration with language support

Multiple Environment Support

You can enable multiple sandbox environments simultaneously:

spec:
  sandbox:
    flox:
      enabled: true
    devcontainer:
      enabled: true

This generates both Flox and DevContainer configurations, allowing developers to choose their preferred environment.

Benefits of Sandbox Environments

Reproducible Development - Consistent environments across team members
Isolated Dependencies - No conflicts with system-wide installations
Language-Specific Tooling - Pre-configured with appropriate development tools
CI/CD Integration - Matches production environment characteristics

Enterprise Features

Authentication Configuration

Enable server authentication in your ADL file:

spec:
  server:
    port: 8443
    debug: false  
    auth:
      enabled: true

This generates enterprise-ready authentication scaffolding in your project.

SCM Integration

Configure source control management for automatic CI/CD provider detection:

spec:
  scm:
    provider: github  # or gitlab
    url: "https://github.com/company/my-agent"

Features:

Automatic CI Detection - Generates appropriate workflows based on SCM provider
Repository Integration - Links generated projects to source control
Workflow Optimization - SCM-specific optimizations and best practices

AI Provider Support

The ADL CLI supports multiple AI providers with provider-specific optimizations:

OpenAI

spec:
  agent:
    provider: openai
    model: gpt-4o-mini
    maxTokens: 8192
    temperature: 0.7

Anthropic

spec:
  agent:
    provider: anthropic
    model: claude-3-haiku-20240307
    maxTokens: 4096
    temperature: 0.3

Azure OpenAI

spec:
  agent:
    provider: azure
    model: gpt-4o
    maxTokens: 8192
    temperature: 0.5

Ollama (Local LLMs)

spec:
  agent:
    provider: ollama
    model: llama3.1
    maxTokens: 4096
    temperature: 0.7

DeepSeek

spec:
  agent:
    provider: deepseek
    model: deepseek-chat
    maxTokens: 8192
    temperature: 0.3

Examples

The CLI includes example ADL files in the examples/ directory:

# Validate examples
adl validate examples/go-agent.yaml
adl validate examples/rust-agent.yaml

# Generate from examples
adl generate --file examples/go-agent.yaml --output ./test-go-agent
adl generate --file examples/rust-agent.yaml --output ./test-rust-agent

Template System & Architecture

The ADL CLI uses a sophisticated template system that generates language-specific projects:

Language Detection

The generator automatically detects your target language from the ADL file:

// Automatic detection based on spec.language configuration
func DetectLanguageFromADL(adl *schema.ADL) string {
    if adl.Spec.Language.Go != nil     { return "go" }
    if adl.Spec.Language.Rust != nil   { return "rust" }  
    if adl.Spec.Language.TypeScript != nil { return "typescript" }
    return "go" // default
}

File Mapping System

Each language has its own file mapping that determines what gets generated:

Go Projects:

main.go → Go main server setup
tools/{toolname}.go → Individual tool implementations
go.mod → Go module configuration
Language-specific Dockerfile and CI configurations

Rust Projects:

src/main.rs → Rust main application
src/tools/{toolname}.rs → Tool implementations
src/tools/mod.rs → Module declarations
Cargo.toml → Rust package configuration

Universal Files:

Taskfile.yml → Development task runner
.well-known/agent.json → A2A capabilities manifest
k8s/deployment.yaml → Kubernetes deployment
CI workflows and sandbox configurations

Template Context

All templates receive a rich context object:

type Context struct {
    ADL      *schema.ADL           // Complete ADL configuration
    Metadata GeneratedMetadata     // Generation metadata
    Language string               // Detected language
}

This allows templates to access any ADL configuration and generate language-appropriate code.

Customizing Generation with .adl-ignore

The ADL CLI automatically creates a .adl-ignore file during project generation to protect files containing TODO implementations. This file works similar to .gitignore and prevents important implementation files from being overwritten during subsequent generations.

Automatically Protected Files

When you generate a project, implementation files are automatically added to .adl-ignore to protect your business logic from being overwritten during regeneration.

You can control which additional files are generated or updated by editing the .adl-ignore file:

# .adl-ignore
# Skip Docker-related files if you have custom containerization
Dockerfile
docker-compose.yml

# Skip Kubernetes manifests if you use different deployment tools
k8s/

# Skip specific generated files you want to customize
middleware.go
auth.go

# Skip build configuration if you have custom setup
Taskfile.yml

.adl-ignore Patterns

Use # for comments
Use / at the end to match directories
Use * for wildcards
Exact file paths or glob patterns
Protects files during all generate operations

Common Use Cases

Custom Deployment: Skip Dockerfile, k8s/, docker-compose.yml
Custom Build: Skip Taskfile.yml, Makefile
Custom Auth: Skip auth.go, middleware.go
Custom Documentation: Skip README.md

Development

Prerequisites

Go 1.21+
Task (optional, for using Taskfile commands)

Building from Source

git clone https://github.com/inference-gateway/adl-cli.git
cd adl-cli

# Install dependencies
go mod download

# Build
task build

# Run tests
task test

# Format code
task fmt

# Lint
task lint

Testing

# Run tests
task test

# Test with coverage
task test:coverage

# Test all examples
task examples:test

# Generate all examples
task examples:generate

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run task ci to ensure everything passes
Submit a pull request

Roadmap

Language Support

The ADL CLI currently supports Go, with plans to expand to additional programming languages:

✅ Currently Supported

Go - Full support with templates for main.go, go.mod, and tools
Rust - Full support with templates for main.rs, Cargo.toml, and tools

🚧 Planned Support

TypeScript/Node.js - Complete A2A agent generation with Express.js framework
- AI-powered agents with OpenAI/Anthropic integration
- Enterprise features (auth, metrics, logging)
- Docker and Kubernetes deployment configs
Python - Rapid prototyping and AI-first development
- FastAPI-based server generation
- Rich AI ecosystem integration
- Jupyter notebook support for development

🔮 Future Considerations

Java/Kotlin - Enterprise JVM support
C#/.NET - Microsoft ecosystem integration
Swift - Apple ecosystem and server-side Swift

Template Enhancements

Multi-language projects - Generate polyglot agents with language-specific microservices
Custom templates - User-defined project templates and scaffolding
Plugin system - Extensible architecture for custom generators
Cloud-native templates - Serverless (AWS Lambda, Vercel) and edge deployment support