Overview

CommandDescription
awf initInitialize AWF in current directory
awf init --globalInitialize 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 listList available workflows
awf list promptsList available prompt files
awf status <id>Show execution status
awf tuiOpen 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 historyShow workflow execution history
awf plugin listList 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 listList 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 showDisplay project configuration
awf upgradeUpgrade AWF to the latest version
awf upgrade --checkCheck for available updates without installing
awf upgrade --version <tag>Install a specific version
awf versionShow version info
awf completion <shell>Generate shell autocompletion

Global Flags

These flags work with all commands:

FlagDescription
--verbose, -vEnable verbose output (displays tool-use markers during agent execution)
--quiet, -qSuppress non-error output
--no-colorDisable colored output
--no-hintsDisable error hint suggestions
--format, -fOutput format (text, json, table, quiet)
--configPath to config file
--storagePath to storage directory
--log-levelLog level (debug, info, warn, error)

Output Formats

FormatDescriptionUse case
textHuman-readable with colors (default)Interactive terminal
jsonStructured JSONScripting, pipes, CI/CD
tableAligned columns with headersLists, reports
quietMinimal 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 quiet

awf init

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

awf init [flags]

Flags

FlagDescription
--forceOverwrite existing configuration files
--globalInitialize 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 --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

FlagDescription
--help, -hShow workflow-specific help with input parameters
--input, -iInput parameter (key=value), can be repeated
--output, -oOutput mode: silent (default), streaming, buffered
--step, -sExecute only a specific step from the workflow
--mock, -mMock state values for single step execution (key=value)
--dry-runShow execution plan without running commands
--interactiveEnable step-by-step mode with prompts
--breakpoint, -bPause only at specific steps (requires –interactive)
--skip-pluginsSkip plugin step type resolution (fails if workflow uses custom step types)
--otel-exporterOTLP 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-nameOpenTelemetry service name resource attribute (default: awf); overrides telemetry.service_name in .awf/config.yaml

Output Modes

ModeDescription
silentNo command output displayed (default)
streamingReal-time output with [OUT]/[ERR] prefixes; for agent steps, displays human-readable text (or raw NDJSON if output_format: json)
bufferedShow 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 --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:

ActionKeyDescription
ContinuecExecute the current step
SkipsSkip this step and continue
AbortaStop workflow execution
InspectiShow step details
EditeModify step parameters
RetryrRetry the last step

awf resume

Resume an interrupted workflow.

awf resume [workflow-id] [flags]

Flags

FlagDescription
--list, -lList resumable workflows
--fromResume from step: current (default), previous (last completed step), or explicit <step-name>
--input, -iOverride input parameter on resume (key=value)
--output, -oOutput mode: silent (default), streaming, buffered

--from Flag Values

ValueDescriptionUse Case
currentResume from the current (failed) stepDefault behavior; backward compatible with pre-F093 awf resume
previousResume from the last completed step before the failureRecover from upstream issues without re-running the current step
<step-name>Resume from a specific named stepJump 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=5000

Error Handling

ErrorWhenResolution
“no prior completed step”Using --from previous on a workflow that hasn’t completed any stepsUse --from <explicit-step-name> or re-run with awf run
“step not found”Using --from <step-name> where the step never executedList 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

SubcommandDescription
promptsList available prompt files

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

FieldDescription
NameRelative path from prompts directory
SourceOrigin: local or global
PathAbsolute file path
SizeFile size in bytes
ModTimeLast 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.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 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

KeyAction
TabCycle through tabs (next)
Shift+TabCycle through tabs (previous)
q / Ctrl+CQuit the TUI (prompts for confirmation if workflow is running)
/ Navigate list items
EnterSelect/activate item, launch workflow, or open details
fFilter list (Workflows/History tabs)
vValidate selected workflow
SpaceToggle 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 tui

Environment

VariableDescription
AWF_CONFIGPath to project configuration file (default: .awf/config.yaml)
AWF_STORAGEPath 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, and awf status commands for non-interactive automation

See Also


awf validate

Validate workflow syntax without executing.

awf validate <workflow> [flags]

Flags

FlagDescription
--skip-pluginsSkip plugin validators
--validator-timeoutPer-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 10s

awf diagram

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

awf diagram <workflow> [flags]

Flags

FlagDescription
--output, -oOutput file path (format detected from extension: .dot, .png, .svg, .pdf)
--directionGraph layout direction: TB (top-bottom, default), LR (left-right), BT, RL
--highlightStep name to visually emphasize

Output Formats

ExtensionDescriptionRequires
.dotDOT source formatNothing
.pngPNG imageGraphviz
.svgSVG vector imageGraphviz
.pdfPDF documentGraphviz

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

Step Shapes

Each step type renders with a distinct shape:

Step TypeShapeDescription
commandBoxStandard command execution
parallelDiamondParallel branch point
terminalOvalWorkflow end (doubleoval for failure)
for_eachHexagonLoop iteration
whileHexagonConditional loop
operationBox3DPlugin operation
call_workflowFolderSub-workflow invocation

Edge Styles

TransitionStyle
on_successSolid line
on_failureDashed 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 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

ArgumentDescription
codeError 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 json

Output Fields

FieldDescription
CodeError code identifier (e.g., USER.INPUT.MISSING_FILE)
DescriptionWhat the error means
ResolutionHow to fix the error
Related CodesOther related error codes

See Also


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

FlagDescription
--workflow, -wFilter by workflow name
--status, -sFilter by status (success, failed, cancelled)
--sinceShow executions since date (YYYY-MM-DD)
--limit, -nMaximum entries to show (default: 20)
--statsShow 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 50

awf plugin

Manage AWF plugins.

awf plugin <subcommand> [flags]

Subcommands

SubcommandDescription
listList 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

FlagDescription
-f, --formatOutput format (text, json)
--operationsList operations provided by each plugin
--step-typesList step types provided by each plugin
--validatorsList validator plugins
--detailsList all capabilities (operations, step types, validators)

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

Output Columns

ColumnDescription
NamePlugin identifier
Typebuiltin or external
VersionSemantic version
Statusbuiltin, enabled, disabled, or error
SourceGitHub owner/repo for installed plugins, - for built-in
DescriptionBrief plugin description
CapabilitiesPlugin 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 --details

awf plugin install

Install a plugin from a GitHub repository.

awf plugin install <owner/repo> [flags]

Arguments

ArgumentDescription
owner/repoGitHub repository in owner/repo format (not a URL)

Flags

FlagDescription
--versionVersion constraint (e.g. ">=1.0.0 <2.0.0")
--pre-releaseInclude pre-release versions (alpha, beta, rc)
--forceOverwrite 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 --force

Errors

ErrorCause
invalid format: use owner/repoA URL was provided instead of owner/repo
invalid format: expected owner/repoMissing owner or repo component
already installedPlugin exists (use --force to overwrite)
checksum mismatchDownloaded archive failed SHA-256 verification
no compatible assetNo 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

ArgumentDescription
plugin-nameName of the plugin to update (optional with --all)

Flags

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

Errors

ErrorCause
requires a plugin name or --all flagNo plugin name and --all not specified
plugin "<name>" is not installedPlugin 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

ArgumentDescription
plugin-namesOne or more plugin names to verify (optional; omit to verify all plugins)

Flags

FlagDescription
--updateRecompute and update stored checksums for the specified plugins
-f, --formatOutput 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:

StatusSymbolMeaning
PassBinary matches the stored checksum
FailBinary 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 json

Errors

ErrorCause
plugin "<name>" is not installedNamed plugin not found in installed plugins
checksum mismatchPlugin 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

ArgumentDescription
plugin-nameName of the plugin to remove

Flags

FlagDescription
--keep-dataPreserve 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-data

Errors

ErrorCause
plugin "<name>" is not installedPlugin name not found
built-in provider cannot be removedAttempted to remove a built-in plugin (use disable instead)

Search for available AWF plugins on GitHub.

awf plugin search [query] [flags]

Arguments

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

awf plugin enable

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

awf plugin enable <name>

Arguments

ArgumentDescription
namePlugin name to enable

Examples

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

# Enable a built-in plugin
awf plugin enable http

Errors

ErrorCause
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

ArgumentDescription
namePlugin name to disable

Examples

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

# Disable a built-in plugin
awf plugin disable http

Errors

ErrorCause
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

SubcommandDescription
listList 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 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

ArgumentDescription
pack-nameName 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 speckit

Errors

ErrorCause
pack "<name>" not foundPack 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

ArgumentDescription
pack-nameName of the pack to update (optional with --all)

Flags

FlagDescription
--allUpdate 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 --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

ErrorCause
pack name required (or use --all)Neither pack name nor --all provided
cannot specify a pack name with --allBoth pack name and --all provided
workflow pack "<name>" not foundPack 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

ArgumentDescription
owner/repoGitHub repository in owner/repo format (not a URL)

Flags

FlagDescription
--versionVersion constraint (e.g., ">=1.0.0 <2.0.0" or "1.2.0" for exact version)
--globalInstall to global user-level directory (~/.local/share/awf/workflow-packs/) instead of local project
--forceOverwrite 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 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 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 --force

Errors

ErrorCause
invalid format: use owner/repoA URL was provided instead of owner/repo
invalid format: expected owner/repoMissing owner or repo component
already installedPack exists (use --force to overwrite)
checksum mismatchDownloaded archive failed SHA-256 verification
no .tar.gz archive foundRelease has no .tar.gz asset
manifest validation failedPack manifest is invalid or missing required fields
AWF version not compatibleCurrent 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

ArgumentDescription
pack-nameName 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 speckit

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

Errors

ErrorCause
pack "<name>" is not installedPack name not found in local or global directories

Search for available AWF workflow packs on GitHub.

awf workflow search [query] [flags]

Arguments

ArgumentDescription
queryOptional keyword to filter results

Flags

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

Errors

ErrorCause
GitHub API rate limit exceededToo 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

FlagDescription
-f, --formatOutput format: text (default), json, quiet

Output Formats

FormatDescription
textHuman-readable table with keys and values
jsonStructured JSON with path, exists flag, and inputs
quietKeys 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 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


awf version

Show 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