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 pre-population)
├── 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#

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"

# View workflow help with input parameters
awf run deploy --help

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#

Examples#

# List all resumable (interrupted) workflows
awf resume --list

# Resume a specific workflow
awf resume abc123-def456

# Resume with input override
awf resume abc123-def456 --input max_tokens=5000

awf list#

List available workflows.

awf list [flags]

Subcommands#

Examples#

# List all workflows
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 validate#

Validate workflow syntax without executing.

awf validate <workflow> [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

Examples#

# Validate a workflow
awf validate deploy

# Validate with verbose output
awf validate deploy -v

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.

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

List all installed plugins with their status.

awf plugin list [flags]

Flags#

Output Columns#

Examples#

# List all plugins
awf plugin list

# JSON output for scripting
awf plugin list -f json

awf plugin enable#

Enable a disabled plugin.

awf plugin enable <name>

Arguments#

Examples#

# Enable a plugin
awf plugin enable awf-plugin-github

awf plugin disable#

Disable an enabled plugin.

awf plugin disable <name>

Arguments#

Examples#

# Disable a plugin
awf plugin disable awf-plugin-github

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