CLI Commands

Overview#

Global Flags#

These flags work with all commands:

Output Formats#

# 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 quiet

awf init#

Initialize AWF in the current directory or global prompts and scripts directories.

awf init [flags]

Flags#

Examples#

# Initialize a new project (local)
awf init

# Reinitialize (recreate config and example workflow)
awf init --force

# Initialize global prompts directory
awf init --global

Created 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 files

See 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-run or --interactive to audit execution plans from untrusted workflows.

awf run <workflow> [flags]

Flags#

Output Modes#

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 --help

Running 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-workflow

Resolution order for pack resources:

1. .awf/prompts/<pack>/... — user override (highest priority)
2. .awf/workflow-packs/<pack>/prompts/... — pack embedded
3. ~/.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 --input flags
• 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> --help

This 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 1

Interactive 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#

1. Detection: AWF detects missing required inputs not provided via --input flags
2. Terminal Check: If stdin is connected to a terminal, AWF enters interactive mode
3. Prompting: You are prompted for each missing required input in order
4. Validation: Invalid input values are rejected with error messages; you can retry
5. 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 1

With 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 --input providing 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/null

Interactive Mode Actions#

When running with --interactive, you can choose at each step:

awf resume#

Resume an interrupted workflow.

awf resume [workflow-id] [flags]

Flags#

--from Flag Values#

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=5000

Error Handling#

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#

Examples#

# List all workflows (local, global, and pack)
awf list

# JSON output
awf list -f json

# Table format
awf list -f table

awf list prompts#

List available prompt files from local and global directories.

awf list prompts [flags]

Description#

Displays all prompt files discovered from:

1. .awf/prompts/ (local project)
2. $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 table

Output Fields#

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.md

The @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 json

awf serve#

Start an HTTP API server for remote workflow execution and monitoring.

awf serve [flags]

Flags#

Description#

Launches an HTTP API server exposing REST endpoints and Server-Sent Events (SSE) streaming for:

• Workflow discovery — list and fetch workflow definitions
• Workflow validation — statically validate workflows before execution
• Async execution — start workflows and receive execution_id immediately
• Real-time monitoring — stream step-by-step progress via SSE
• Execution history — query historical executions and aggregated statistics

The server generates an auto-synced OpenAPI 3.1 specification served at /openapi.json with interactive Swagger UI at /docs.

Default binding is 127.0.0.1:2511 (localhost only) — use --host 0.0.0.0 at your own risk in production without authentication.

Graceful Shutdown#

The server listens for SIGINT (Ctrl+C) and SIGTERM signals. On shutdown:

1. New HTTP requests return 503
2. Active SSE streams drain within 30 seconds
3. Running workflows continue (separate from the HTTP server lifecycle)
4. Server exits cleanly

Examples#

# Start on localhost (default)
awf serve

# Start on a custom port
awf serve --port 8080

# Bind to all interfaces
awf serve --host 0.0.0.0 --port 8080

# Access the API
curl http://localhost:2511/api/workflows

# Open interactive API docs
open http://localhost:2511/docs

Security Considerations#

• Default localhost binding prevents accidental network exposure
• No authentication in v1 — requires running in isolated network or behind a reverse proxy with auth
• For production: use reverse proxy (nginx, HAProxy) with HTTPS, authentication, and rate limiting
• Monitor /api/executions for long-running or stuck workflows

See HTTP API Documentation for endpoint reference, client libraries, and integration examples.

awf 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#

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 tui

Environment#

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, and awf status commands 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#

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 --verbose

# Skip plugin validators
awf validate deploy --skip-plugins

# Custom validator timeout
awf validate deploy --validator-timeout 10s

awf diagram#

Generate a visual diagram of a workflow in DOT format (Graphviz).

awf diagram <workflow> [flags]

Flags#

Output Formats#

Without --output, DOT format is printed to stdout.

Step Shapes#

Each step type renders with a distinct shape:

Edge Styles#

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 deploy

Graphviz Installation#

For image export (PNG, SVG, PDF), install Graphviz:

# macOS
brew install graphviz

# Ubuntu/Debian
apt install graphviz

# Fedora
dnf install graphviz

DOT format output works without Graphviz.

awf error#

Look up error code documentation and display detailed information.

awf error [code] [flags]

Arguments#

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 json

Output Fields#

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#

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 50

awf plugin#

Manage AWF plugins.

awf plugin <subcommand> [flags]

Subcommands#

awf plugin init#

Scaffold an AWF plugin repository.

awf plugin init <name> [flags]

Arguments#

Flags#

Description#

Generates a Go operation plugin repository with go.mod, main.go, tests, plugin.yaml, README.md, Makefile, examples/demo.yaml, and a GitHub Actions release workflow.

The command treats <name> as the distribution name used for the repository, binary, directory, and release assets. The runtime plugin id is derived by stripping the awf-plugin- prefix, so awf-plugin-example creates a manifest named example and workflow operations use example.echo.

kind selects the scaffold shape. Runtime capabilities stay in plugin.yaml; the generated operation scaffold advertises operations. Future scaffold kinds such as canonical-port, adapter, direct-integration, hybrid, validator, step-type, event-listener, and full are listed in help output but return unsupported-kind errors until implemented.

Examples#

# Create an operation plugin in ./awf-plugin-example
awf plugin init awf-plugin-example --kind operation

# Use the default operation kind
awf plugin init awf-plugin-example

# Write to a custom directory
awf plugin init awf-plugin-example --output /tmp/awf-plugin-example

# Overwrite existing generated files
awf plugin init awf-plugin-example --force

First Run#

awf plugin init awf-plugin-example --kind operation
cd awf-plugin-example
make test
make build
make install-local
awf plugin enable awf-plugin-example
awf plugin list --operations
awf run examples/demo.yaml

Errors#

awf plugin list#

List all installed plugins with their status.

awf plugin list [flags]

Flags#

Flags --operations, --step-types, --validators, and --details are mutually exclusive.

Output Columns#

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 --details

awf plugin install#

Install a plugin from a GitHub repository.

awf plugin install <owner/repo[@version]> [flags]

Arguments#

Flags#

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.

Explicit versions use owner/repo@version syntax and must be exact SemVer values. Both 1.2.3 and v1.2.3 are accepted; ranges such as >=1.0.0 are rejected.

Release assets must follow the naming convention: awf-plugin-<name>_<version>_<os>_<arch>.tar.gz with a corresponding checksums.txt file.

Examples#

# Install a plugin
awf plugin install myorg/awf-plugin-jira

# Install an exact version
awf plugin install myorg/awf-plugin-jira@v1.2.3

# Include pre-release versions
awf plugin install myorg/awf-plugin-jira --pre-release

# Force reinstall over existing
awf plugin install myorg/awf-plugin-jira --force

Errors#

awf plugin update#

Update an installed plugin to the latest compatible version.

awf plugin update [plugin-name] [flags]

Arguments#

Flags#

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 --all

Errors#

awf plugin verify#

Verify the integrity of plugin binaries using SHA-256 checksums.

awf plugin verify [plugin-names...] [flags]

Arguments#

Flags#

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:

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 json

Errors#

awf plugin remove#

Remove an installed plugin.

awf plugin remove <plugin-name> [flags]

Arguments#

Flags#

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-data

Errors#

awf plugin search#

Search for available AWF plugins on GitHub.

awf plugin search [query] [flags]

Arguments#

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=json

awf plugin enable#

Enable a disabled plugin. Works with both built-in and external plugins.

awf plugin enable <name>

Arguments#

Examples#

# Enable an external plugin
awf plugin enable awf-plugin-github

# Enable a built-in plugin
awf plugin enable http

Errors#

awf plugin disable#

Disable an enabled plugin. Works with both built-in and external plugins.

awf plugin disable <name>

Arguments#

Examples#

# Disable an external plugin
awf plugin disable awf-plugin-github

# Disable a built-in plugin
awf plugin disable http

Errors#

awf workflow#

Manage workflow packs installed from GitHub Releases.

awf workflow <subcommand> [flags]

Subcommands#

awf workflow list#

List all installed workflow packs with their version, source, and available workflows.

awf workflow list

Aliases#

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 ls

Output#

Each pack entry shows:

• Name — Pack identifier
• Version — Semantic version from manifest
• Source — GitHub owner/repo or local
• 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#

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 speckit

Errors#

awf workflow update#

Update an installed workflow pack to the latest version from GitHub Releases.

awf workflow update [pack-name] [flags]

Arguments#

Flags#

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 --all

Output#

# 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#

awf workflow install#

Install a workflow pack from a GitHub repository.

awf workflow install <owner/repo[@version]> [flags]

Arguments#

Flags#

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.

Explicit versions use owner/repo@version syntax and must be exact SemVer values. Both 1.2.3 and v1.2.3 are accepted; ranges such as >=1.0.0 are rejected.

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 semver
• awf_version: Version constraint must be satisfied by current AWF CLI version
• workflows/: 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 an exact version
awf workflow install myorg/awf-workflow-speckit@v1.2.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 --force

Errors#

awf workflow remove#

Remove an installed workflow pack.

awf workflow remove <pack-name> [flags]

Arguments#

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 speckit

The command automatically detects whether the pack is installed locally or globally and removes it from the appropriate location.

Errors#

awf workflow search#

Search for available AWF workflow packs on GitHub.

awf workflow search [query] [flags]

Arguments#

Flags#

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=json

Errors#

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#

Output Formats#

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 quiet

Example Output#

Text format:

Project Configuration (.awf/config.yaml)

  project: my-project
  env: staging
  count: 42

JSON 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 binary version information.

awf --version

awf completion#

Generate shell autocompletion scripts.

awf completion <shell>

Supported Shells#

• bash
• zsh
• fish
• powershell

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