On this page
- Overview
- Global Flags
- Output Formats
- awf init
- awf run
- awf resume
- awf list
- awf list prompts
- awf status
- awf tui
- awf validate
- awf diagram
- awf error
- awf history
- awf plugin
- awf plugin list
- awf plugin install
- awf plugin update
- awf plugin verify
- awf plugin remove
- awf plugin search
- awf plugin enable
- awf plugin disable
- awf workflow
- awf workflow list
- awf workflow info
- awf workflow update
- awf workflow install
- awf workflow remove
- awf workflow search
- awf config show
- awf version
- awf completion
CLI Commands
Overview
| Command | Description |
|---|---|
awf init | Initialize AWF in current directory |
awf init --global | Initialize global prompts and scripts directories |
awf run <workflow> | Execute a local workflow |
awf run <pack/workflow> | Execute a workflow from an installed pack |
awf resume [workflow-id] | Resume an interrupted workflow (--from to resume from a specific step) |
awf list | List available workflows |
awf list prompts | List available prompt files |
awf status <id> | Show execution status |
awf tui | Open interactive terminal user interface |
awf validate <workflow> | Validate workflow syntax |
awf diagram <workflow> | Generate workflow diagram (DOT format) |
awf error [code] | Look up error code documentation |
awf history | Show workflow execution history |
awf plugin list | List installed plugins |
awf plugin install <owner/repo> | Install a plugin from GitHub releases |
awf plugin update [name] | Update an installed plugin |
awf plugin verify [name] | Verify plugin binary integrity (check/update SHA-256 checksums) |
awf plugin remove <name> | Remove an installed plugin |
awf plugin search [query] | Search for plugins on GitHub |
awf plugin enable <name> | Enable a plugin |
awf plugin disable <name> | Disable a plugin |
awf workflow list | List installed workflow packs |
awf workflow info <name> | Display detailed pack information |
awf workflow install <owner/repo> | Install a workflow pack from GitHub Releases |
awf workflow update [name] | Update an installed workflow pack |
awf workflow remove <name> | Remove an installed workflow pack |
awf workflow search [query] | Search for workflow packs on GitHub |
awf config show | Display project configuration |
awf upgrade | Upgrade AWF to the latest version |
awf upgrade --check | Check for available updates without installing |
awf upgrade --version <tag> | Install a specific version |
awf version | Show version info |
awf completion <shell> | Generate shell autocompletion |
Global Flags
These flags work with all commands:
| Flag | Description |
|---|---|
--verbose, -v | Enable verbose output (displays tool-use markers during agent execution) |
--quiet, -q | Suppress non-error output |
--no-color | Disable colored output |
--no-hints | Disable error hint suggestions |
--format, -f | Output format (text, json, table, quiet) |
--config | Path to config file |
--storage | Path to storage directory |
--log-level | Log level (debug, info, warn, error) |
Output Formats
| Format | Description | Use case |
|---|---|---|
text | Human-readable with colors (default) | Interactive terminal |
json | Structured JSON | Scripting, pipes, CI/CD |
table | Aligned columns with headers | Lists, reports |
quiet | Minimal output (IDs, exit codes only) | Silent scripts |
# JSON output for scripting
awf list -f json
awf status abc123 -f json
# Quiet mode for pipelines
WORKFLOW_ID=$(awf run deploy -f quiet)
awf status $WORKFLOW_ID -f quietawf init
Initialize AWF in the current directory or global prompts and scripts directories.
awf init [flags]Flags
| Flag | Description |
|---|---|
--force | Overwrite existing configuration files |
--global | Initialize global prompts and scripts directories at $XDG_CONFIG_HOME/awf/ |
Examples
# Initialize a new project (local)
awf init
# Reinitialize (recreate config and example workflow)
awf init --force
# Initialize global prompts directory
awf init --globalCreated Structure (Local)
.awf.yaml # Configuration file
.awf/
├── config.yaml # Project configuration (inputs, telemetry, plugins)
├── workflows/
│ └── example.yaml # Sample workflow
├── prompts/
│ └── example.md # Example prompt file
├── scripts/
│ └── example.sh # Example script file (executable)
├── templates/ # Reusable workflow templates
└── storage/
├── states/ # State persistence
└── logs/ # Log filesSee
Project Configuration for details on .awf/config.yaml.
Created Structure (Global)
$XDG_CONFIG_HOME/awf/
├── prompts/
│ └── example.md # Example prompt file
└── scripts/
└── example.sh # Example script file (executable)awf run
Execute a workflow.
⚠️ Security Warning: This command executes arbitrary shell commands on your system. Only run workflows from trusted sources. Use
--dry-runor--interactiveto audit execution plans from untrusted workflows.
awf run <workflow> [flags]Flags
| Flag | Description |
|---|---|
--help, -h | Show workflow-specific help with input parameters |
--input, -i | Input parameter (key=value), can be repeated |
--output, -o | Output mode: silent (default), streaming, buffered |
--step, -s | Execute only a specific step from the workflow |
--mock, -m | Mock state values for single step execution (key=value) |
--dry-run | Show execution plan without running commands |
--interactive | Enable step-by-step mode with prompts |
--breakpoint, -b | Pause only at specific steps (requires –interactive) |
--skip-plugins | Skip plugin step type resolution (fails if workflow uses custom step types) |
--otel-exporter | OTLP gRPC endpoint for distributed tracing (e.g., localhost:4317); overrides telemetry.exporter in .awf/config.yaml; omit to use project config or disable |
--otel-service-name | OpenTelemetry service name resource attribute (default: awf); overrides telemetry.service_name in .awf/config.yaml |
Output Modes
| Mode | Description |
|---|---|
silent | No command output displayed (default) |
streaming | Real-time output with [OUT]/[ERR] prefixes; for agent steps, displays human-readable text (or raw NDJSON if output_format: json) |
buffered | Show output after each step completes; for agent steps, displays filtered text in post-execution summary (or raw NDJSON if output_format: json) |
Note: For agent steps, the output_format field controls display filtering: text or omitted (default) shows human-readable output; json shows raw NDJSON. See
Output Formatting for details.
Execution Summary
After a workflow completes, AWF displays an execution summary with step statuses, durations, and output. Steps are always displayed in workflow-defined order — following the Initial state through default transitions and on_success references — regardless of actual execution timing or internal map ordering. This ensures consistent, readable output across runs:
--- Execution Details ---
Status: completed
Steps executed:
init completed (12ms)
build completed (1.234s)
test completed (856ms)
deploy completed (3.012s)
done completed (0ms)Steps that were not executed (e.g., because the workflow branched to a different path) are omitted from the summary. Step stdout/stderr blocks follow the same ordering.
Examples
# Basic execution
awf run deploy
# With inputs
awf run deploy --input env=prod --input version=1.2.3
# Interactive input collection (prompted for missing required inputs)
awf run deploy
# Prompts: Enter value for 'env' (string, required): _
# With streaming output
awf run deploy -o streaming
# Dry run to see execution plan
awf run deploy --dry-run
# Interactive step-by-step
awf run deploy --interactive
# Pause only at specific steps
awf run deploy --interactive --breakpoint build,deploy
# Execute single step with mocked dependencies
awf run deploy --step deploy_step --mock states.build.Output="build-123"
# Enable distributed tracing via CLI flags (or configure in .awf/config.yaml)
awf run deploy --otel-exporter=localhost:4317 --otel-service-name=my-app
# View workflow help with input parameters
awf run deploy --helpRunning Pack Workflows
Installed workflow packs provide namespaced workflows accessible via pack/workflow syntax:
# Run a workflow from an installed pack
awf run speckit/specify --input file=main.go
# Pack workflows resolve prompts and scripts from the pack's embedded files
# User overrides in .awf/prompts/<pack>/ and .awf/scripts/<pack>/ take precedence
# Dry-run a pack workflow
awf run speckit/specify --dry-run
# Local workflows (no namespace) are unaffected
awf run my-local-workflowResolution order for pack resources:
.awf/prompts/<pack>/...— user override (highest priority).awf/workflow-packs/<pack>/prompts/...— pack embedded~/.config/awf/prompts/...— global XDG (lowest priority)
Interactive Input Collection
When required workflow inputs are missing and stdin is connected to a terminal, AWF automatically prompts for missing values:
Behavior:
- Terminal environment: Prompts interactively for each missing required input
- Non-terminal environment (pipes, scripts): Returns error with message to use
--inputflags - All inputs provided: Executes immediately without prompts
Prompt display:
- Input name, type, and required/optional status
- Description and help text from workflow definition
- Enum options as numbered list (1-9) for constrained inputs
- Default value shown for optional inputs
Validation:
- Type checking (string, integer, boolean)
- Enum constraint validation
- Pattern matching (regex)
- Immediate error feedback with retry on invalid input
- Empty input accepted for optional parameters (uses default)
See Interactive Input Collection Guide for detailed examples.
Workflow-Specific Help
View input parameters and details for a specific workflow before running it:
awf run <workflow> --helpThis displays:
- Workflow description (if defined)
- All input parameters with their types (string, integer, boolean)
- Required/optional status for each input
- Default values for optional inputs
- Input descriptions
Example Output
Execute a workflow by name with optional input parameters.
Description: Deploy application to specified environment
Input Parameters:
NAME TYPE REQUIRED DEFAULT DESCRIPTION
env string yes - Target environment (dev, staging, prod)
version string yes - Version tag to deploy
dry_run boolean no false Run deployment checks without applying
timeout integer no 300 Deployment timeout in seconds
Usage:
awf run deploy [flags]
Flags:
-h, --help help for run
-i, --input strings Input parameter (key=value)
...Help for Non-Existent Workflow
awf run unknown-workflow --help
# Error: workflow "unknown-workflow" not found
# exit code 1Interactive Input Collection
When you run a workflow with missing required inputs from a terminal, AWF automatically prompts you for each missing value instead of failing immediately.
How It Works
- Detection: AWF detects missing required inputs not provided via
--inputflags - Terminal Check: If stdin is connected to a terminal, AWF enters interactive mode
- Prompting: You are prompted for each missing required input in order
- Validation: Invalid input values are rejected with error messages; you can retry
- Execution: Once all required inputs are provided, the workflow executes
Examples
Without Interactive Input Collection (Non-Interactive Context):
# In a script or piped context:
awf run deploy < /dev/null
# Error: required input "env" not provided
# exit code 1With Interactive Input Collection (Terminal):
# From your terminal:
awf run deploy
# Output:
# env (string, required):
# > prod
#
# version (string, required):
# > 1.2.3
#
# Workflow started...Enum Constraints
When an input has enum constraints, AWF displays numbered options:
awf run deploy
# Output:
# env (string, required):
# Available options:
# 1) dev
# 2) staging
# 3) prod
# Select option (1-3):
# > 2
#
# Workflow started...Optional Inputs
Optional inputs can be skipped by pressing Enter without providing a value:
awf run deploy
# Output:
# env (string, required):
# > prod
#
# timeout (integer, optional, default: 300):
# >
#
# Using default value for timeout: 300
# Workflow started...When Interactive Mode Is NOT Available
Interactive input collection requires:
- ✅ Running in a terminal (stdin connected to TTY)
- ✅ Workflow has required inputs
- ❌ Not available in scripts (
< file, pipes|) - ❌ Not available in CI/CD pipelines
- ❌ Not available with
--inputproviding all required values
In non-interactive contexts, you must provide all required inputs via --input flags:
# Provide all required inputs explicitly
awf run deploy --input env=prod --input version=1.2.3
# Or in a script
awf run deploy --input env=prod --input version=1.2.3 < /dev/nullInteractive Mode Actions
When running with --interactive, you can choose at each step:
| Action | Key | Description |
|---|---|---|
| Continue | c | Execute the current step |
| Skip | s | Skip this step and continue |
| Abort | a | Stop workflow execution |
| Inspect | i | Show step details |
| Edit | e | Modify step parameters |
| Retry | r | Retry the last step |
awf resume
Resume an interrupted workflow.
awf resume [workflow-id] [flags]Flags
| Flag | Description |
|---|---|
--list, -l | List resumable workflows |
--from | Resume from step: current (default), previous (last completed step), or explicit <step-name> |
--input, -i | Override input parameter on resume (key=value) |
--output, -o | Output mode: silent (default), streaming, buffered |
--from Flag Values
| Value | Description | Use Case |
|---|---|---|
current | Resume from the current (failed) step | Default behavior; backward compatible with pre-F093 awf resume |
previous | Resume from the last completed step before the failure | Recover from upstream issues without re-running the current step |
<step-name> | Resume from a specific named step | Jump back multiple steps to the root cause |
State Cleanup Behavior
When using --from previous or --from <step-name>:
- All step states completed after the target step are removed from execution history
- The workflow re-executes from the target step with the cleaned state
- Interpolation references to cleaned steps (e.g.,
{{states.removed_step.output}}) will fail with “unknown state”
Examples
# List all resumable (interrupted) workflows
awf resume --list
# Resume a specific workflow (default: resume from current step)
awf resume abc123-def456
# Resume from the previous (last completed) step
awf resume abc123-def456 --from previous
# Resume from a specific step by name
awf resume abc123-def456 --from build_step
# Resume with input override and from flag
awf resume abc123-def456 --from previous --input max_tokens=5000Error Handling
| Error | When | Resolution |
|---|---|---|
| “no prior completed step” | Using --from previous on a workflow that hasn’t completed any steps | Use --from <explicit-step-name> or re-run with awf run |
| “step not found” | Using --from <step-name> where the step never executed | List completed steps with awf status <id> to find valid step names |
awf list
List available workflows, including pack workflows.
awf list [flags]Description
Displays all workflows from local (.awf/workflows/), global (~/.config/awf/workflows/), and installed pack directories. Pack workflows appear with pack/workflow namespace prefix and pack source label.
Subcommands
| Subcommand | Description |
|---|---|
prompts | List available prompt files |
Examples
# List all workflows (local, global, and pack)
awf list
# JSON output
awf list -f json
# Table format
awf list -f tableawf list prompts
List available prompt files from local and global directories.
awf list prompts [flags]Description
Displays all prompt files discovered from:
.awf/prompts/(local project)$XDG_CONFIG_HOME/awf/prompts/(global, default:~/.config/awf/prompts/)
Local prompts override global prompts with the same name. The output shows the source (local/global) for each prompt.
Examples
# List all prompts
awf list prompts
# JSON output
awf list prompts -f json
# Table format
awf list prompts -f tableOutput Fields
| Field | Description |
|---|---|
| Name | Relative path from prompts directory |
| Source | Origin: local or global |
| Path | Absolute file path |
| Size | File size in bytes |
| ModTime | Last modification time |
Using Prompts
Reference prompts in workflow inputs using the @prompts/ prefix:
awf run my-workflow --input prompt=@prompts/system.md
awf run ai-task --input context=@prompts/ai/agents/analyzer.mdThe @prompts/ prefix searches local directory first, then global.
awf status
Show execution status of a workflow.
awf status <workflow-id> [flags]Examples
# Check status
awf status abc123-def456
# JSON output for scripting
awf status abc123-def456 -f jsonawf tui
Open an interactive terminal user interface for browsing, executing, and monitoring workflows.
awf tui [flags]Description
Launches a full-screen Bubble Tea terminal UI with tab-based navigation providing:
- Workflows Tab: Filterable list of available workflows with launch and validation actions
- Monitoring Tab: Real-time execution tree visualization with step statuses, durations, and live log streaming
- History Tab: Browse past execution records with filtering by workflow name, status, and date range
- Agent Conversations Tab: View multi-turn agent interactions with Markdown-formatted responses
- External Logs Tab: Live tail of Claude Code JSONL session files for monitoring development sessions
The TUI bridges to existing CLI workflows while providing enhanced visibility into real-time execution and historical data without requiring raw command-line interaction.
Keyboard Navigation
| Key | Action |
|---|---|
Tab | Cycle through tabs (next) |
Shift+Tab | Cycle through tabs (previous) |
q / Ctrl+C | Quit the TUI (prompts for confirmation if workflow is running) |
↑ / ↓ | Navigate list items |
Enter | Select/activate item, launch workflow, or open details |
f | Filter list (Workflows/History tabs) |
v | Validate selected workflow |
| Space | Toggle selection in multi-select lists |
Features
Workflow Filtering
In the Workflows tab, use the search filter to quickly find workflows:
- Filter by workflow name or description
- Sub-second response time
- Match highlighting in results
Real-Time Monitoring
In the Monitoring tab while a workflow is running:
- Tree visualization with status icons (⏳ pending, ▶ running, ✓ success, ✗ failed)
- Auto-scrolling log viewport showing real-time step output
- Manual scroll-lock to pause auto-scroll
- Step duration tracking
- Auto-selection of failed steps in the tree for immediate error visibility
History Exploration
In the History tab:
- Chronologically sorted execution records from
history.db - Filter by workflow name, execution status (success/failed/cancelled), and date range
- Inspect past execution details including full tree state, timing breakdown, and step outputs
Agent Conversations
In the Agent Conversations tab:
- View multi-turn agent interactions during workflow execution
- Markdown-formatted responses with proper heading, code block, and list rendering
- Approval prompts (if applicable) with keyboard shortcuts
External Logs
In the External Logs tab:
- Live tailing of Claude Code JSONL session files
- Automatic detection of latest session file in
~/.claude/projects/... - Formatted message display with timestamps
- Graceful fallback if no session is active
Examples
# Open the TUI
awf tui
# Launch from a script or CI/CD (non-interactive)
# Note: TUI requires a terminal; use `awf run` or `awf history` in non-interactive contexts
awf tuiEnvironment
| Variable | Description |
|---|---|
AWF_CONFIG | Path to project configuration file (default: .awf/config.yaml) |
AWF_STORAGE | Path to storage directory (default: .awf/storage/) |
Notes
- Terminal requirements: Minimum 80x24 character dimensions recommended
- Color support: Automatically detects terminal color capabilities (true color, 256-color, basic ANSI)
- Terminal state: TUI restores terminal state cleanly on exit, panic recovery, or signal termination (SIGINT/SIGTERM)
- Secret masking: All sensitive values (variables starting with
SECRET_,API_KEY,PASSWORD) are automatically masked in TUI views - Non-interactive contexts: TUI requires a terminal with TTY support. Use
awf run,awf history, andawf statuscommands for non-interactive automation
See Also
- Workflow Execution - Workflow syntax and configuration
- Commands - Full command reference
- Interactive Inputs - Terminal-based input prompting
awf validate
Validate workflow syntax without executing.
awf validate <workflow> [flags]Flags
| Flag | Description |
|---|---|
--skip-plugins | Skip plugin validators |
--validator-timeout | Per-plugin validation timeout (default 5s, e.g., 10s, 2m) |
Validates
- YAML syntax
- State references (no missing states)
- Transition graph (no cycles, no unreachable states)
- Terminal states exist
- Template references valid
- Input definitions valid
- Parallel strategy valid
- Plugin validators (custom rules from enabled validator plugins, skipped with
--skip-plugins)
Examples
# Validate a workflow
awf validate deploy
# Validate with verbose output
awf validate deploy -v
# Skip plugin validators
awf validate deploy --skip-plugins
# Custom validator timeout
awf validate deploy --validator-timeout 10sawf diagram
Generate a visual diagram of a workflow in DOT format (Graphviz).
awf diagram <workflow> [flags]Flags
| Flag | Description |
|---|---|
--output, -o | Output file path (format detected from extension: .dot, .png, .svg, .pdf) |
--direction | Graph layout direction: TB (top-bottom, default), LR (left-right), BT, RL |
--highlight | Step name to visually emphasize |
Output Formats
| Extension | Description | Requires |
|---|---|---|
.dot | DOT source format | Nothing |
.png | PNG image | Graphviz |
.svg | SVG vector image | Graphviz |
.pdf | PDF document | Graphviz |
Without --output, DOT format is printed to stdout.
Step Shapes
Each step type renders with a distinct shape:
| Step Type | Shape | Description |
|---|---|---|
command | Box | Standard command execution |
parallel | Diamond | Parallel branch point |
terminal | Oval | Workflow end (doubleoval for failure) |
for_each | Hexagon | Loop iteration |
while | Hexagon | Conditional loop |
operation | Box3D | Plugin operation |
call_workflow | Folder | Sub-workflow invocation |
Edge Styles
| Transition | Style |
|---|---|
on_success | Solid line |
on_failure | Dashed red line |
Examples
# Output DOT to stdout
awf diagram deploy
# Pipe to graphviz
awf diagram deploy | dot -Tpng -o workflow.png
# Direct image export (requires graphviz)
awf diagram deploy --output workflow.png
# Left-to-right layout
awf diagram deploy --direction LR
# Highlight a specific step
awf diagram deploy --highlight build_step
# Save DOT file
awf diagram deploy --output workflow.dot
# Combined flags
awf diagram deploy -o diagram.svg --direction LR --highlight deployGraphviz Installation
For image export (PNG, SVG, PDF), install Graphviz:
# macOS
brew install graphviz
# Ubuntu/Debian
apt install graphviz
# Fedora
dnf install graphvizDOT format output works without Graphviz.
awf error
Look up error code documentation and display detailed information.
awf error [code] [flags]Arguments
| Argument | Description |
|---|---|
code | Error code or prefix to look up (optional) |
Description
Without arguments, lists all available error codes with descriptions and resolutions. With a code argument, displays detailed information for that specific error code. Supports prefix matching to show all codes in a category.
Error codes follow a three-level hierarchy: CATEGORY.SUBCATEGORY.SPECIFIC
Examples
# List all error codes
awf error
# Look up a specific error code
awf error USER.INPUT.MISSING_FILE
# Prefix match - show all workflow validation errors
awf error WORKFLOW.VALIDATION
# JSON output for programmatic use
awf error EXECUTION.COMMAND.FAILED -f jsonOutput Fields
| Field | Description |
|---|---|
| Code | Error code identifier (e.g., USER.INPUT.MISSING_FILE) |
| Description | What the error means |
| Resolution | How to fix the error |
| Related Codes | Other related error codes |
See Also
- Error Codes Reference - Complete error code taxonomy
- Exit Codes - Exit code categories
awf history
Show workflow execution history. IDs and workflow names are displayed in full (no truncation), so IDs can be copied directly into commands like awf status <id>.
awf history [flags]Flags
| Flag | Description |
|---|---|
--workflow, -w | Filter by workflow name |
--status, -s | Filter by status (success, failed, cancelled) |
--since | Show executions since date (YYYY-MM-DD) |
--limit, -n | Maximum entries to show (default: 20) |
--stats | Show statistics only |
Examples
# List recent executions
awf history
# Filter by workflow
awf history --workflow deploy
# Filter by status
awf history --status failed
# Show executions since date
awf history --since 2025-12-01
# Show statistics only
awf history --stats
# JSON output for scripting
awf history -f json
# Combined filters
awf history -w deploy -s success --since 2025-12-01 -n 50awf plugin
Manage AWF plugins.
awf plugin <subcommand> [flags]Subcommands
| Subcommand | Description |
|---|---|
list | List all plugins (use --operations to show provided operations) |
install <owner/repo> | Install a plugin from GitHub releases |
update [name] | Update an installed plugin to the latest version |
verify [name] | Verify plugin binary integrity (check/update SHA-256 checksums) |
remove <name> | Remove an installed plugin |
search [query] | Search for available plugins on GitHub |
enable <name> | Enable a disabled plugin |
disable <name> | Disable an enabled plugin |
awf plugin list
List all installed plugins with their status.
awf plugin list [flags]Flags
| Flag | Description |
|---|---|
-f, --format | Output format (text, json) |
--operations | List operations provided by each plugin |
--step-types | List step types provided by each plugin |
--validators | List validator plugins |
--details | List all capabilities (operations, step types, validators) |
Flags
--operations,--step-types,--validators, and--detailsare mutually exclusive.
Output Columns
| Column | Description |
|---|---|
| Name | Plugin identifier |
| Type | builtin or external |
| Version | Semantic version |
| Status | builtin, enabled, disabled, or error |
| Source | GitHub owner/repo for installed plugins, - for built-in |
| Description | Brief plugin description |
| Capabilities | Plugin features: operations, step_types, validators |
Examples
# List all plugins
awf plugin list
# JSON output for scripting
awf plugin list -f json
# Show operations provided by each plugin
awf plugin list --operations
# Show step types provided by plugins
awf plugin list --step-types
# Show validator plugins
awf plugin list --validators
# Show all capabilities in unified view
awf plugin list --detailsawf plugin install
Install a plugin from a GitHub repository.
awf plugin install <owner/repo> [flags]Arguments
| Argument | Description |
|---|---|
owner/repo | GitHub repository in owner/repo format (not a URL) |
Flags
| Flag | Description |
|---|---|
--version | Version constraint (e.g. ">=1.0.0 <2.0.0") |
--pre-release | Include pre-release versions (alpha, beta, rc) |
--force | Overwrite existing installation |
Description
Downloads the latest compatible release from the GitHub repository, verifies the SHA-256 checksum, extracts the .tar.gz archive, validates the plugin manifest, and installs atomically. The plugin is enabled automatically after installation.
Release assets must follow the naming convention: awf-plugin-<name>_<os>_<arch>.tar.gz with a corresponding checksums.txt file.
Examples
# Install a plugin
awf plugin install myorg/awf-plugin-jira
# Install with version constraint
awf plugin install myorg/awf-plugin-jira --version ">=1.0.0 <2.0.0"
# Include pre-release versions
awf plugin install myorg/awf-plugin-jira --pre-release
# Force reinstall over existing
awf plugin install myorg/awf-plugin-jira --forceErrors
| Error | Cause |
|---|---|
invalid format: use owner/repo | A URL was provided instead of owner/repo |
invalid format: expected owner/repo | Missing owner or repo component |
already installed | Plugin exists (use --force to overwrite) |
checksum mismatch | Downloaded archive failed SHA-256 verification |
no compatible asset | No release asset matches the current platform |
awf plugin update
Update an installed plugin to the latest compatible version.
awf plugin update [plugin-name] [flags]Arguments
| Argument | Description |
|---|---|
plugin-name | Name of the plugin to update (optional with --all) |
Flags
| Flag | Description |
|---|---|
--all | Update all externally installed plugins |
Description
Fetches the latest release from the plugin’s source repository and performs an atomic replacement. Built-in plugins cannot be updated. Requires either a plugin name or the --all flag.
Examples
# Update a specific plugin
awf plugin update jira
# Update all external plugins
awf plugin update --allErrors
| Error | Cause |
|---|---|
requires a plugin name or --all flag | No plugin name and --all not specified |
plugin "<name>" is not installed | Plugin name not found in installed plugins |
awf plugin verify
Verify the integrity of plugin binaries using SHA-256 checksums.
awf plugin verify [plugin-names...] [flags]Arguments
| Argument | Description |
|---|---|
plugin-names | One or more plugin names to verify (optional; omit to verify all plugins) |
Flags
| Flag | Description |
|---|---|
--update | Recompute and update stored checksums for the specified plugins |
-f, --format | Output format (text, json) |
Description
Verifies that installed plugin binaries have not been modified or corrupted by comparing their SHA-256 checksums against stored values. Checksums are recorded automatically during awf plugin install. For manually placed or locally-built plugins, use --update to compute and store checksums.
Without arguments: Verifies all installed plugins.
With plugin names: Verifies only the named plugins.
Without --update: Read-only verification; reports pass/fail/missing status.
With --update: Recomputes checksums for the named plugins and updates the stored values. Useful for locally-built or manually installed plugins.
Output
Each plugin is reported with one of three statuses:
| Status | Symbol | Meaning |
|---|---|---|
| Pass | ✓ | Binary matches the stored checksum |
| Fail | ✗ | Binary does NOT match the stored checksum (possible tampering or corruption) |
| Missing | ! | No stored checksum (plugin will launch without verification) |
Output includes: plugin name, status, expected hash, and actual hash.
Examples
# Verify all plugins
awf plugin verify
# Verify a specific plugin
awf plugin verify jira
# Verify multiple plugins
awf plugin verify jira metrics custom
# Verify and update checksums for a locally-built plugin
awf plugin verify custom --update
# Verify all and update a specific plugin's checksum
awf plugin verify --update jira
# JSON output for scripting
awf plugin verify -f jsonErrors
| Error | Cause |
|---|---|
plugin "<name>" is not installed | Named plugin not found in installed plugins |
checksum mismatch | Plugin binary does not match the stored checksum (possible corruption or tampering) |
awf plugin remove
Remove an installed plugin.
awf plugin remove <plugin-name> [flags]Arguments
| Argument | Description |
|---|---|
plugin-name | Name of the plugin to remove |
Flags
| Flag | Description |
|---|---|
--keep-data | Preserve plugin configuration and state |
Description
Removes the plugin binary and manifest from the plugins directory. Plugin state is also cleared unless --keep-data is specified. Built-in plugins cannot be removed — use awf plugin disable instead.
Examples
# Remove a plugin
awf plugin remove jira
# Remove but keep configuration
awf plugin remove jira --keep-dataErrors
| Error | Cause |
|---|---|
plugin "<name>" is not installed | Plugin name not found |
built-in provider cannot be removed | Attempted to remove a built-in plugin (use disable instead) |
awf plugin search
Search for available AWF plugins on GitHub.
awf plugin search [query] [flags]Arguments
| Argument | Description |
|---|---|
query | Optional keyword to filter results |
Description
Discovers AWF plugins on GitHub by searching repositories tagged with the awf-plugin topic. Without a query, lists the full catalog. Results can be output as JSON for scripting.
Examples
# List all available plugins
awf plugin search
# Search by keyword
awf plugin search jira
# JSON output for scripting
awf plugin search --output=jsonawf plugin enable
Enable a disabled plugin. Works with both built-in and external plugins.
awf plugin enable <name>Arguments
| Argument | Description |
|---|---|
name | Plugin name to enable |
Examples
# Enable an external plugin
awf plugin enable awf-plugin-github
# Enable a built-in plugin
awf plugin enable httpErrors
| Error | Cause |
|---|---|
unknown plugin "<name>" | Plugin name is not registered (typo or not installed) |
awf plugin disable
Disable an enabled plugin. Works with both built-in and external plugins.
awf plugin disable <name>Arguments
| Argument | Description |
|---|---|
name | Plugin name to disable |
Examples
# Disable an external plugin
awf plugin disable awf-plugin-github
# Disable a built-in plugin
awf plugin disable httpErrors
| Error | Cause |
|---|---|
unknown plugin "<name>" | Plugin name is not registered (typo or not installed) |
awf workflow
Manage workflow packs installed from GitHub Releases.
awf workflow <subcommand> [flags]Subcommands
| Subcommand | Description |
|---|---|
list | List installed workflow packs with version, source, and workflows |
info <name> | Display detailed information about an installed pack |
install <owner/repo> | Install a workflow pack from GitHub Releases |
update [name] | Update an installed workflow pack to the latest version |
remove <name> | Remove an installed workflow pack |
search [query] | Search for available workflow packs on GitHub |
awf workflow list
List all installed workflow packs with their version, source, and available workflows.
awf workflow listAliases
awf workflow ls
Description
Discovers packs from local (.awf/workflow-packs/) and global (~/.local/share/awf/workflow-packs/) directories, deduplicating by name (local takes precedence). Includes a (local) pseudo-entry when .awf/workflows/ contains local workflow files.
Examples
# List all installed packs
awf workflow list
# Using alias
awf wf lsOutput
Each pack entry shows:
- Name — Pack identifier
- Version — Semantic version from manifest
- Source — GitHub
owner/repoorlocal - Workflows — Public workflow names defined in the pack
The (local) entry shows the count of workflow files in .awf/workflows/.
awf workflow info
Display detailed information about an installed workflow pack.
awf workflow info <pack-name>Arguments
| Argument | Description |
|---|---|
pack-name | Name of the installed workflow pack |
Description
Shows manifest fields (name, version, description, author, license), workflow list, plugin install status with actionable install commands, and embedded README content. Searches local then global workflow-packs directories.
Plugin dependency warnings are emitted to stderr when the pack declares required plugins.
Examples
# Show pack details
awf workflow info speckit
# Using workflow alias
awf wf info speckitErrors
| Error | Cause |
|---|---|
pack "<name>" not found | Pack name not found in local or global directories |
awf workflow update
Update an installed workflow pack to the latest version from GitHub Releases.
awf workflow update [pack-name] [flags]Arguments
| Argument | Description |
|---|---|
pack-name | Name of the pack to update (optional with --all) |
Flags
| Flag | Description |
|---|---|
--all | Update all installed workflow packs |
Description
Loads the pack’s state.json to find the source repository, fetches the latest release via GitHubReleaseClient, compares versions, and performs an atomic replacement using forced reinstall. User overrides in .awf/prompts/<pack>/ and .awf/scripts/<pack>/ are preserved (they live outside the pack directory).
After a successful update, state.json is written with the new version and an updated_at timestamp.
Examples
# Update a specific pack
awf workflow update speckit
# Update all installed packs
awf workflow update --allOutput
# When newer version exists
Updated speckit to version 1.3.0
# When already at latest
speckit is already at the latest version (1.2.0)
# When updating all
Updated 2 pack(s).
# When all are current
All packs are at their latest versions.
# When no packs installed
No installed workflow packs to update.Errors
| Error | Cause |
|---|---|
pack name required (or use --all) | Neither pack name nor --all provided |
cannot specify a pack name with --all | Both pack name and --all provided |
workflow pack "<name>" not found | Pack not found in local or global directories |
awf workflow install
Install a workflow pack from a GitHub repository.
awf workflow install <owner/repo> [flags]Arguments
| Argument | Description |
|---|---|
owner/repo | GitHub repository in owner/repo format (not a URL) |
Flags
| Flag | Description |
|---|---|
--version | Version constraint (e.g., ">=1.0.0 <2.0.0" or "1.2.0" for exact version) |
--global | Install to global user-level directory (~/.local/share/awf/workflow-packs/) instead of local project |
--force | Overwrite existing installation |
Description
Downloads the latest compatible release from the GitHub repository, verifies the SHA-256 checksum, extracts the .tar.gz archive, validates the manifest.yaml, checks AWF version compatibility, and installs atomically. The pack directory structure is created with source metadata.
Release assets must include a single .tar.gz archive (e.g., awf-workflow-<name>_<version>.tar.gz) with a corresponding checksums.txt file. Workflow packs are platform-independent — no OS/architecture suffix is needed.
Pack manifest validation:
name: Must match^[a-z][a-z0-9-]*$(lowercase, hyphens)version: Must be valid semverawf_version: Version constraint must be satisfied by current AWF CLI versionworkflows/: All referenced workflow files must exist in the pack
Installation locations:
- Local (default):
.awf/workflow-packs/<name>/(project-level) - Global (
--global):~/.local/share/awf/workflow-packs/<name>/(user-level, applies to all projects)
Plugin dependencies:
If the manifest declares required plugins via the plugins: field, warnings are emitted during installation (non-blocking). Install missing plugins separately with awf plugin install.
Examples
# Install a workflow pack (latest version)
awf workflow install myorg/awf-workflow-speckit
# Install with specific version
awf workflow install myorg/awf-workflow-speckit --version "1.2.0"
# Install with version constraint
awf workflow install myorg/awf-workflow-speckit --version ">=1.0.0 <2.0.0"
# Install globally (available to all projects)
awf workflow install myorg/awf-workflow-speckit --global
# Force reinstall over existing
awf workflow install myorg/awf-workflow-speckit --forceErrors
| Error | Cause |
|---|---|
invalid format: use owner/repo | A URL was provided instead of owner/repo |
invalid format: expected owner/repo | Missing owner or repo component |
already installed | Pack exists (use --force to overwrite) |
checksum mismatch | Downloaded archive failed SHA-256 verification |
no .tar.gz archive found | Release has no .tar.gz asset |
manifest validation failed | Pack manifest is invalid or missing required fields |
AWF version not compatible | Current AWF CLI version does not satisfy the pack’s awf_version constraint |
awf workflow remove
Remove an installed workflow pack.
awf workflow remove <pack-name> [flags]Arguments
| Argument | Description |
|---|---|
pack-name | Name of the workflow pack to remove |
Description
Removes the workflow pack directory and all its contents (workflows, prompts, scripts, state.json). Deletion is immediate — no confirmation prompt is required.
Examples
# Remove a locally installed pack
awf workflow remove speckit
# Remove a globally installed pack
awf workflow remove speckitThe command automatically detects whether the pack is installed locally or globally and removes it from the appropriate location.
Errors
| Error | Cause |
|---|---|
pack "<name>" is not installed | Pack name not found in local or global directories |
awf workflow search
Search for available AWF workflow packs on GitHub.
awf workflow search [query] [flags]Arguments
| Argument | Description |
|---|---|
query | Optional keyword to filter results |
Flags
| Flag | Description |
|---|---|
--output | Output format (json) |
Description
Discovers AWF workflow packs on GitHub by searching repositories tagged with the awf-workflow topic. Without a query, lists the full catalog sorted by stars. Results show the repository name, star count, and description.
Examples
# List all available workflow packs
awf workflow search
# Search by keyword
awf workflow search speckit
# JSON output for scripting
awf workflow search --output=jsonErrors
| Error | Cause |
|---|---|
GitHub API rate limit exceeded | Too many unauthenticated requests; set GITHUB_TOKEN for higher limits |
awf config show
Display project configuration values from .awf/config.yaml.
awf config show [flags]Description
Shows all configured input values from the project configuration file. If no configuration file exists, displays a message suggesting to run awf init.
Flags
| Flag | Description |
|---|---|
-f, --format | Output format: text (default), json, quiet |
Output Formats
| Format | Description |
|---|---|
text | Human-readable table with keys and values |
json | Structured JSON with path, exists flag, and inputs |
quiet | Keys only, one per line (sorted alphabetically) |
Examples
# Display configuration in default format
awf config show
# JSON output for scripting
awf config show --format json
# List just the configured input keys
awf config show --format quietExample Output
Text format:
Project Configuration (.awf/config.yaml)
project: my-project
env: staging
count: 42JSON format:
{
"path": ".awf/config.yaml",
"exists": true,
"inputs": {
"project": "my-project",
"env": "staging",
"count": 42
}
}See Also
- Project Configuration - Configuration file reference
awf version
Show version information.
awf versionawf completion
Generate shell autocompletion scripts.
awf completion <shell>Supported Shells
bashzshfishpowershell
Examples
# Bash
awf completion bash > /etc/bash_completion.d/awf
# Zsh
awf completion zsh > "${fpath[1]}/_awf"
# Fish
awf completion fish > ~/.config/fish/completions/awf.fish
# PowerShell
awf completion powershell > awf.ps1