cli

AI Workflow Framework - CLI

A Go CLI tool for orchestrating AI agents (Claude, Gemini, Codex, OpenAI-Compatible APIs) through YAML-configured workflows with state machine execution.

Features

• State Machine Execution - Define workflows as state machines with conditional transitions based on exit codes, command output, or custom expressions
• Inline Error Handling - Specify error messages and exit codes directly on steps without creating separate terminal states
• Agent Steps - Invoke AI agents via CLI tools (Claude, Codex, Gemini) or direct HTTP (OpenAI, Ollama, vLLM, Groq) with prompt templates, response parsing, and accurate token tracking
• Output Formatting for Agent Steps - Automatically strip markdown code fences and validate JSON output
• External Prompt Files - Load agent prompts from .md files with full template interpolation, helper functions, and local override support
• External Script Files - Load commands from external script files with shebang-based interpreter dispatch, template interpolation, path resolution, and local override support
• Conversation Mode - Multi-turn conversations with native session resume for CLI providers (claude, codex, gemini, opencode), automatic context window management for HTTP providers, mid-conversation context injection via inject_context field, and token tracking across all turns
• OpenAI-Compatible Provider - Use any Chat Completions API (OpenAI, Ollama, vLLM, Groq) with native HTTP integration, accurate token reporting, and no CLI tool required
• Parallel Execution - Run multiple steps concurrently with configurable strategies
• Loop Constructs - For-each and while loops with full context access
• Sub-Workflows - Invoke workflows from other workflows with input/output mapping
• Retry with Backoff - Automatic retry with exponential, linear, or constant backoff
• Workflow Templates - Reusable step patterns with parameters
• Input Validation - Type checking, patterns, enums, file validation
• Dry-Run Mode - Preview execution plan without running commands
• Interactive Mode - Step-by-step execution with prompts
• Interactive Input Collection - Automatically prompt for missing required inputs in terminal sessions
• Structured Error Codes - Hierarchical error taxonomy (USER.INPUT.MISSING_FILE) with awf error lookup command
• Actionable Error Hints - Context-aware suggestions ("Did you mean?") with fuzzy matching, suppressible via --no-hints
• Audit Trail - Structured JSONL audit log with paired start/end entries per execution, secret masking, configurable path, and atomic writes
• Plugin System - Extend AWF with custom operations, validators, and step types via gRPC plugins (HashiCorp go-plugin); validators run custom rules during awf validate, custom step types register new type: values for workflow steps; includes sdk.Serve() entry point for plugin authors, and install/update/remove from GitHub Releases with checksum verification
• Built-in GitHub Plugin - Declarative GitHub operations (get_issue, create_pr, batch) with auth fallback and concurrent execution
• Built-in HTTP Operation - Declarative REST API calls (GET, POST, PUT, DELETE) with configurable timeout, response capture, and retryable status codes
• Built-in Notification Plugin - Workflow completion alerts via desktop and webhooks with configurable backends

Installation

curl -fsSL https://raw.githubusercontent.com/awf-project/cli/main/scripts/install.sh | sh

Or via Go:

go install github.com/awf-project/cli/cmd/awf@latest

Or build from source:

git clone https://github.com/awf-project/cli.git
cd cli && make build && make install

See Installation Guide for details.

Quick Start

# Initialize AWF
awf init

# Run example workflow
awf run example

# Create your own workflow
cat > .awf/workflows/hello.yaml << 'EOF'
name: hello
version: "1.0.0"

inputs:
  - name: name
    type: string
    default: World

states:
  initial: greet
  greet:
    type: step
    command: echo "Hello, {{.inputs.name}}!"
    on_success: done
  done:
    type: terminal
    status: success
EOF

# Run with input
awf run hello --input name=World

See Quick Start Guide for more.

⚠️ Security & Risk Disclaimer

AWF is a powerful orchestration tool that grants AI agents and workflows direct access to your system's shell. While this enables complex automation, it carries significant risks:

1. Arbitrary Code Execution: Workflows behave like shell scripts. Never run a workflow definition (YAML) from an untrusted source without auditing it first.
2. AI Non-Determinism: AI agents (LLMs) can produce incorrect, unexpected, or destructive output ("hallucinations"). A prompt that seems safe might generate a harmful command in a specific context.
3. No Sandboxing: By default, AWF executes commands with the same privileges as the user running the CLI.

Best Practices for Safe Execution:

• Audit Workflows: Always review the YAML and prompt files before execution.
• Use Dry-Run: Preview the execution plan using awf run --dry-run.
• Interactive Mode: Use awf run --interactive to approve commands step-by-step.
• Isolate Execution: Run risky workflows or those from external sources within a sandboxed environment (e.g., Docker, VM).

Commands

See Command Reference for all options.

Example Workflow

name: code-review
version: "1.0.0"

inputs:
  - name: file
    type: string
    required: true
    validation:
      file_exists: true

states:
  initial: read

  read:
    type: step
    command: cat "{{.inputs.file}}"
    on_success: analyze
    on_failure: {message: "File not found: {{.inputs.file}}", status: 1}

  analyze:
    type: agent
    provider: claude
    prompt: |
      Review this code for bugs, security issues, and improvements:
      {{.states.read.Output}}
    output_format: json
    options:
      model: claude-sonnet-4-20250514
    timeout: 120
    on_success: report
    on_failure: {message: "Analysis failed: {{.states.analyze.Output}}"}

  report:
    type: step
    command: echo "Severity: {{.states.analyze.JSON.severity}} — {{.states.analyze.JSON.summary}}"
    on_success: done

  done:
    type: terminal
    status: success

awf run code-review --input file=main.go

See Examples for more workflows.

Documentation

📖 Browse the documentation site — searchable, with dark mode.

Or read locally:

Architecture

AWF follows hexagonal (clean) architecture:

Interfaces (CLI) → Application (Services) → Domain (Entities, Ports)
                                                    ↑
                        Infrastructure (YAML, JSON, Shell) ─┘

See Architecture for details.

Development

make build          # Build binary
make test           # Run all tests
make lint           # Run linter
make lint-arch      # Check architecture constraints
make test-coverage  # Generate coverage report
make quality        # Run all quality checks
make proto-gen      # Regenerate protobuf Go code
make docs           # Build documentation site
make docs-serve     # Serve documentation site locally
make docs-clean     # Clean documentation build artifacts

See Testing Guide for conventions.

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Submit a Pull Request

Support the Project

AWF is maintained by Alexandre Balmes and relies on community support to ensure continued development, maintenance, and reliability.

Why Sponsor?

Your support helps:

• Maintenance: Bug fixes, security updates, dependency upgrades
• Improvements: New features, performance optimizations
• Quality: Documentation, testing, code reviews
• Reliability: CI/CD, release management, long-term support

How to Support

Direct sponsorship:

• GitHub Sponsors

Commercial engagement:

Hiring services from the author's companies directly funds AWF development:

• Vanoix - Tech Consulting
• d11n Studio - AI Solutions
• akawaka - Web Development

All commercial clients receive a free commercial license for AWF.

License

Open Source License

This project is licensed under the EUPL-1.2 (European Union Public License).

• Individuals: Free to use, modify, and distribute
• Companies: Free to use under EUPL-1.2 terms (copyleft - modifications must be shared)
• GPL Compatibility: EUPL-1.2 is compatible with GPL

Commercial License

Companies seeking exemption from copyleft obligations can obtain a commercial license.

Free commercial license for:

• Project sponsors
• Active contributors
• Clients of Vanoix, akawaka, d11n Studio (author's company)

Contact: [email protected]