Quick Start

Get AWF running in 5 minutes.

⚠️ Security & Risk Disclaimer: AWF executes real shell commands and interacts with non-deterministic AI agents. Always audit workflows from untrusted sources. It is recommended to use awf run --dry-run or awf run --interactive when testing new or external workflows.

1. Initialize AWF#

awf init

This creates the following structure:

.awf.yaml              # Configuration file
.awf/
├── config.yaml        # Project configuration with input templates
├── workflows/
│   └── example.yaml   # Sample workflow
├── prompts/
│   └── example.md     # Sample prompt template
└── scripts/
    └── example.sh     # Sample script file

2. Run the Example Workflow#

awf run example

Output:

Hello from AWF!
Workflow completed successfully

3. Create Your First Workflow#

Create a new file .awf/workflows/hello.yaml:

name: hello
version: "1.0.0"
description: A simple hello world workflow

states:
  initial: greet
  greet:
    type: step
    command: echo "Hello, {{.inputs.name}}!"
    on_success: done
  done:
    type: terminal

Run it with an input:

awf run hello --input name=World

Output:

Hello, World!
Workflow completed successfully

4. Interactive Input Collection#

If you run a workflow with missing required inputs, AWF will automatically prompt you for them (when running from a terminal):

awf run hello
# Output:
# name (string, required):

Just enter a value and press Enter. AWF will execute the workflow with your input.

Note: Interactive prompting only works in terminal sessions. In scripts or piped contexts, you must provide inputs via --input flags.

6. Validate Your Workflow#

Check your workflow for errors before running:

awf validate hello

7. List Available Workflows#

See all workflows AWF can find:

awf list

Workflow Discovery#

AWF discovers workflows from multiple locations (priority high to low):

1. AWF_WORKFLOWS_PATH environment variable
2. ./.awf/workflows/ (local project)
3. $XDG_CONFIG_HOME/awf/workflows/ (global, default: ~/.config/awf/workflows/)

Local workflows override global ones with the same name.

Prompt Discovery#

AWF discovers prompts from multiple locations (priority high to low):

1. ./.awf/prompts/ (local project)
2. $XDG_CONFIG_HOME/awf/prompts/ (global, default: ~/.config/awf/prompts/)

Local prompts override global ones with the same name.

# List all prompts
awf list prompts

# Initialize global prompts directory
awf init --global

Using Prompts#

Reference prompts in workflow inputs using the @prompts/ prefix:

awf run my-workflow --input prompt=@prompts/system.md

The @prompts/ prefix loads the file content and passes it as the input value.

Storage Locations#

AWF follows the XDG Base Directory Specification for storing runtime data:

Custom storage path:

awf run example --storage-path /custom/path

This will store state files in /custom/path/states/ and history in /custom/path/history.db.

Common Flags#

Example: Code Analysis#

name: analyze-code
version: "1.0.0"

inputs:
  - name: file
    type: string
    required: true

states:
  initial: read_file
  read_file:
    type: step
    command: cat "{{.inputs.file}}"
    on_success: analyze
    on_failure: error
  analyze:
    type: step
    command: |
      claude -c "Review this code:
      {{.states.read_file.Output}}"
    timeout: 120
    on_success: done
    on_failure: error
  done:
    type: terminal
  error:
    type: terminal
    status: failure

awf run analyze-code --input file=main.go

Next Steps#

• Commands - Full command reference
• Workflow Syntax - Complete YAML syntax
• Examples - More workflow examples