{"id":47667745,"url":"https://github.com/awf-project/cli","last_synced_at":"2026-04-02T12:03:26.111Z","repository":{"id":346025857,"uuid":"1115756053","full_name":"awf-project/cli","owner":"awf-project","description":"A Go CLI tool for orchestrating AI agents through YAML workflows","archived":false,"fork":false,"pushed_at":"2026-03-30T12:58:24.000Z","size":6185,"stargazers_count":24,"open_issues_count":14,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T14:36:11.745Z","etag":null,"topics":["ai","claude","codex-cli","gemini","golang"],"latest_commit_sha":null,"homepage":"http://awf-project.ai/cli/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awf-project.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"pocky"}},"created_at":"2025-12-13T13:43:50.000Z","updated_at":"2026-03-30T13:05:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/awf-project/cli","commit_stats":null,"previous_names":["awf-project/cli"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/awf-project/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awf-project%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awf-project%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awf-project%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awf-project%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awf-project","download_url":"https://codeload.github.com/awf-project/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awf-project%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","codex-cli","gemini","golang"],"created_at":"2026-04-02T12:03:25.768Z","updated_at":"2026-04-02T12:03:26.104Z","avatar_url":"https://github.com/awf-project.png","language":"Go","funding_links":["https://github.com/sponsors/pocky"],"categories":[],"sub_categories":[],"readme":"# AI Workflow Framework - CLI\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat\u0026logo=go)](https://go.dev/)\n[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](LICENSE)\n\nA Go CLI tool for orchestrating AI agents (Claude, Gemini, Codex, OpenAI-Compatible APIs) through YAML-configured workflows with state machine execution.\n\n## Features\n\n- **State Machine Execution** - Define workflows as state machines with conditional transitions based on exit codes, command output, or custom expressions\n- **Inline Error Handling** - Specify error messages and exit codes directly on steps without creating separate terminal states\n- **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\n- **Output Formatting for Agent Steps** - Automatically strip markdown code fences and validate JSON output\n- **External Prompt Files** - Load agent prompts from `.md` files with full template interpolation, helper functions, and local override support\n- **External Script Files** - Load commands from external script files with shebang-based interpreter dispatch, template interpolation, path resolution, and local override support\n- **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\n- **OpenAI-Compatible Provider** - Use any Chat Completions API (OpenAI, Ollama, vLLM, Groq) with native HTTP integration, accurate token reporting, and no CLI tool required\n- **Parallel Execution** - Run multiple steps concurrently with configurable strategies\n- **Loop Constructs** - For-each and while loops with full context access\n- **Sub-Workflows** - Invoke workflows from other workflows with input/output mapping\n- **Retry with Backoff** - Automatic retry with exponential, linear, or constant backoff\n- **Workflow Templates** - Reusable step patterns with parameters\n- **Input Validation** - Type checking, patterns, enums, file validation\n- **Dry-Run Mode** - Preview execution plan without running commands\n- **Interactive Mode** - Step-by-step execution with prompts\n- **Interactive Input Collection** - Automatically prompt for missing required inputs in terminal sessions\n- **Structured Error Codes** - Hierarchical error taxonomy (`USER.INPUT.MISSING_FILE`) with `awf error` lookup command\n- **Actionable Error Hints** - Context-aware suggestions (\"Did you mean?\") with fuzzy matching, suppressible via `--no-hints`\n- **Audit Trail** - Structured JSONL audit log with paired start/end entries per execution, secret masking, configurable path, and atomic writes\n- **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\n- **Workflow Packs** - Share reusable workflows and prompts via `awf workflow install owner/repo[@version]` from GitHub Releases with manifest validation, checksum verification, and atomic installation; execute with `awf run pack/workflow` namespace syntax; `{{.awf.prompts_dir}}` and `{{.awf.scripts_dir}}` resolve context-aware with 3-tier resolution (user override → pack embedded → global); `call_workflow` within packs resolves relative to pack root; `--global` flag for user-level installation; `awf workflow remove \u003cpack\u003e` for cleanup; source metadata tracking and plugin dependency warnings\n- **Built-in GitHub Plugin** - Declarative GitHub operations (get_issue, create_pr, batch) with auth fallback and concurrent execution\n- **Built-in HTTP Operation** - Declarative REST API calls (GET, POST, PUT, DELETE) with configurable timeout, response capture, and retryable status codes\n- **Built-in Notification Plugin** - Workflow completion alerts via desktop and webhooks with configurable backends\n\n## Installation\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/awf-project/cli/main/scripts/install.sh | sh\n```\n\nOr via Go:\n\n```bash\ngo install github.com/awf-project/cli/cmd/awf@latest\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/awf-project/cli.git\ncd cli \u0026\u0026 make build \u0026\u0026 make install\n```\n\nSee [Installation Guide](docs/getting-started/installation.md) for details.\n\n## Quick Start\n\n```bash\n# Initialize AWF\nawf init\n\n# Run example workflow\nawf run example\n\n# Create your own workflow\ncat \u003e .awf/workflows/hello.yaml \u003c\u003c 'EOF'\nname: hello\nversion: \"1.0.0\"\n\ninputs:\n  - name: name\n    type: string\n    default: World\n\nstates:\n  initial: greet\n  greet:\n    type: step\n    command: echo \"Hello, {{.inputs.name}}!\"\n    on_success: done\n  done:\n    type: terminal\n    status: success\nEOF\n\n# Run with input\nawf run hello --input name=World\n```\n\nSee [Quick Start Guide](docs/getting-started/quickstart.md) for more.\n\n## ⚠️ Security \u0026 Risk Disclaimer\n\nAWF 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:\n\n1. **Arbitrary Code Execution:** Workflows behave like shell scripts. **Never run a workflow definition (YAML) from an untrusted source** without auditing it first.\n2. **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.\n3. **No Sandboxing:** By default, AWF executes commands with the same privileges as the user running the CLI.\n\n**Best Practices for Safe Execution:**\n* **Audit Workflows:** Always review the YAML and prompt files before execution.\n* **Use Dry-Run:** Preview the execution plan using `awf run --dry-run`.\n* **Interactive Mode:** Use `awf run --interactive` to approve commands step-by-step.\n* **Isolate Execution:** Run risky workflows or those from external sources within a sandboxed environment (e.g., Docker, VM).\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `awf init` | Initialize AWF in current directory |\n| `awf run \u003cworkflow\u003e` | Execute a workflow |\n| `awf validate \u003cworkflow\u003e` | Validate workflow syntax |\n| `awf diagram \u003cworkflow\u003e` | Generate workflow diagram (DOT format) |\n| `awf error [code]` | Lookup error codes with descriptions and resolutions |\n| `awf list` | List available workflows |\n| `awf list prompts` | List available prompt files |\n| `awf resume` | Resume interrupted workflow |\n| `awf history` | Show execution history |\n| `awf status \u003cid\u003e` | Check workflow status |\n| `awf config show` | Display project configuration |\n| `awf plugin list` | List installed plugins |\n| `awf plugin install \u003cowner/repo\u003e` | Install a plugin from GitHub Releases |\n| `awf plugin update [name]` | Update an installed plugin |\n| `awf plugin remove \u003cname\u003e` | Remove an installed plugin |\n| `awf plugin search [query]` | Search for plugins on GitHub |\n| `awf plugin enable \u003cname\u003e` | Enable a plugin |\n| `awf plugin disable \u003cname\u003e` | Disable a plugin |\n| `awf workflow install \u003cowner/repo\u003e` | Install a workflow pack from GitHub Releases |\n| `awf workflow remove \u003cpack\u003e` | Remove an installed workflow pack |\n| `awf version` | Show version information |\n| `awf completion \u003cshell\u003e` | Generate shell autocompletion |\n\nSee [Command Reference](docs/user-guide/commands.md) for all options.\n\n## Example Workflow\n\n```yaml\nname: code-review\nversion: \"1.0.0\"\n\ninputs:\n  - name: file\n    type: string\n    required: true\n    validation:\n      file_exists: true\n\nstates:\n  initial: read\n\n  read:\n    type: step\n    command: cat \"{{.inputs.file}}\"\n    on_success: analyze\n    on_failure: {message: \"File not found: {{.inputs.file}}\", status: 1}\n\n  analyze:\n    type: agent\n    provider: claude\n    prompt: |\n      Review this code for bugs, security issues, and improvements:\n      {{.states.read.Output}}\n    output_format: json\n    options:\n      model: claude-sonnet-4-20250514\n    timeout: 120\n    on_success: report\n    on_failure: {message: \"Analysis failed: {{.states.analyze.Output}}\"}\n\n  report:\n    type: step\n    command: echo \"Severity: {{.states.analyze.JSON.severity}} — {{.states.analyze.JSON.summary}}\"\n    on_success: done\n\n  done:\n    type: terminal\n    status: success\n```\n\n```bash\nawf run code-review --input file=main.go\n```\n\nSee [Examples](docs/user-guide/examples.md) for more workflows.\n\n## Documentation\n\n📖 **[Browse the documentation site](https://awf-project.github.io/cli/)** — searchable, with dark mode.\n\nOr read locally:\n\n| Section | Description |\n|---------|-------------|\n| [Getting Started](docs/getting-started/) | Installation and first steps |\n| [User Guide](docs/user-guide/) | Commands, workflow syntax, templates |\n| [Reference](docs/reference/) | Exit codes, error codes, interpolation, validation |\n| [Development](docs/development/) | Architecture, contributing, testing |\n\n## Architecture\n\nAWF follows hexagonal (clean) architecture:\n\n```\nInterfaces (CLI) → Application (Services) → Domain (Entities, Ports)\n                                                    ↑\n                        Infrastructure (YAML, JSON, Shell) ─┘\n```\n\nSee [Architecture](docs/development/architecture.md) for details.\n\n## Development\n\n```bash\nmake build          # Build binary\nmake test           # Run all tests\nmake lint           # Run linter\nmake lint-arch      # Check architecture constraints\nmake test-coverage  # Generate coverage report\nmake quality        # Run all quality checks\nmake proto-gen      # Regenerate protobuf Go code\nmake docs           # Build documentation site\nmake docs-serve     # Serve documentation site locally\nmake docs-clean     # Clean documentation build artifacts\n```\n\nSee [Testing Guide](docs/development/testing.md) for conventions.\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for your changes\n4. Submit a Pull Request\n\n## Support the Project\n\nAWF is maintained by [Alexandre Balmes](https://github.com/pocky) and relies on community support to ensure continued development, maintenance, and reliability.\n\n### Why Sponsor?\n\nYour support helps:\n- **Maintenance**: Bug fixes, security updates, dependency upgrades\n- **Improvements**: New features, performance optimizations\n- **Quality**: Documentation, testing, code reviews\n- **Reliability**: CI/CD, release management, long-term support\n\n### How to Support\n\n**Direct sponsorship:**\n- [GitHub Sponsors](https://github.com/sponsors/pocky)\n\n**Commercial engagement:**\n\nHiring services from the author's companies directly funds AWF development:\n- [Vanoix](https://vanoix.com) - Tech Consulting\n- [d11n Studio](https://d11n.studio) - AI Solutions\n- [akawaka](https://akawaka.fr) - Web Development\n\nAll commercial clients receive a free commercial license for AWF.\n\n## License\n\n### Open Source License\n\nThis project is licensed under the [EUPL-1.2](LICENSE) (European Union Public License).\n\n- **Individuals**: Free to use, modify, and distribute\n- **Companies**: Free to use under EUPL-1.2 terms (copyleft - modifications must be shared)\n- **GPL Compatibility**: EUPL-1.2 is [compatible with GPL](https://joinup.ec.europa.eu/collection/eupl/matrix-eupl-compatible-open-source-licences)\n\n### Commercial License\n\nCompanies seeking exemption from copyleft obligations can obtain a commercial license.\n\n**Free commercial license for:**\n- [Project sponsors](https://github.com/sponsors/pocky)\n- Active contributors\n- Clients of [Vanoix](https://vanoix.com), [akawaka](https://akawaka.fr), [d11n Studio](https://d11n.studio) (author's company)\n\n**Contact:** awf@alexandre.vanoix.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawf-project%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawf-project%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawf-project%2Fcli/lists"}