CLI Reference

FlowState provides three main commands: run, list, and resume.

fs run

Execute a workflow, creating a new instance or resuming an existing one.

Synopsis

fs run <workflow> [options]

Arguments

Argument	Description
workflow	Name of the workflow to run

Options

Option	Short	Description
--name <name>	-n	Create a new instance with this name
--resume <name>	-r	Resume an existing instance
--clean-on-end		Delete instance on successful completion

Behavior

Interactive mode (no options):

1. If instances exist, prompt to select one or create new
2. If no instances, prompt for new instance name
3. Run the workflow

With --name:

1. Create new instance with specified name
2. Fail if instance already exists
3. Run from start

With --resume:

1. Load existing instance
2. Fail if instance doesn’t exist
3. Continue from saved state

Non-interactive mode (stdin redirected):

Requires either --name or --resume. Fails otherwise.

Examples

# Interactive - choose or create instance
fs run my-workflow

# Create named instance
fs run my-workflow --name feature-123

# Resume existing instance
fs run my-workflow --resume feature-123

# CI mode - clean up on success
fs run my-workflow --name build-$(date +%s) --clean-on-end

Exit Codes

Code	Meaning
0	Workflow completed successfully
1	Workflow error or validation failure
130	User cancelled
Other	Propagated from failed tool

fs list

List available workflows or paused instances.

Synopsis

fs list [options]

Options

Option	Description
--paused	List paused instances instead of workflows

Listing Workflows

fs list

Output:

Workflows:
  code-review (extends new-feature)
  hello-world
  new-feature

Shows:

• Workflow names (sorted alphabetically)
• Inheritance relationships
• Warning if parent workflow not found

Listing Paused Instances

fs list --paused

Output:

Paused Instances:
┌───────────────┬─────────────┬───────────────┬───────────┬─────────────────────┐
│ Instance      │ Workflow    │ State         │ Paused At │ Reason              │
├───────────────┼─────────────┼───────────────┼───────────┼─────────────────────┤
│ feature-123   │ code-review │ await-review  │ 2h ago    │ Waiting for review  │
│ deploy-prod   │ deploy      │ approval-gate │ 5m ago    │ Needs manager sign… │
└───────────────┴─────────────┴───────────────┴───────────┴─────────────────────┘

fs resume

Resume paused workflow instances.

Synopsis

fs resume [instance] [options]

Arguments

Argument	Description
instance	Name of instance to resume (optional in interactive mode)

Options

Option	Description
--all	Resume all paused instances
--workflow <name>	Resume all paused instances for a workflow
--force	Skip condition check and force resume

Behavior

Interactive mode (no arguments):

1. Show menu of paused instances
2. User selects which to resume
3. Check pause condition if present
4. Continue workflow execution

With instance name:

1. Load specified instance
2. Verify it’s paused
3. Check condition, resume if met

With --all:

Resume every paused instance. Each is processed independently.

With --workflow:

Resume all paused instances belonging to that workflow.

With --force:

Skip condition checking. The workflow advances to its next state regardless.

Condition Checking

When resuming an instance with a pause condition:

1. Execute the condition command
2. If exit code 0, condition is met - resume
3. If non-zero, condition not met - stay paused

# Normal resume - checks condition
fs resume my-instance

# Force resume - skips condition
fs resume my-instance --force

Examples

# Interactive selection
fs resume

# Resume specific instance
fs resume feature-123

# Resume all paused
fs resume --all

# Resume workflow's paused instances
fs resume --workflow code-review

# Force resume (skip condition)
fs resume feature-123 --force

Exit Codes

Code	Meaning
0	All instances resumed successfully
1	One or more instances failed to resume

Instance Management

Instances are stored in .flowstate/instances/<name>/.

Instance Directory Structure

.flowstate/instances/feature-123/
├── workflow/
│   ├── index.yaml          # Workflow definition
│   └── helper-workflow.yaml # Referenced sub-flows
└── context.json            # Execution state

context.json

{
  "workflowName": "code-review",
  "currentState": "await-approval",
  "status": "Paused",
  "createdAt": "2024-01-15T10:30:00Z",
  "lastRunAt": "2024-01-15T10:35:00Z",
  "pausedAt": "2024-01-15T10:35:00Z",
  "pauseReason": "Waiting for approval",
  "variables": {
    "branch": "feature-123",
    "reviewer": "alice"
  }
}

Status Values

Status	Description
Running	Currently executing
Paused	Awaiting resume
Halted	Stopped due to error
Completed	Finished successfully

Manual Instance Cleanup

Delete an instance directory to remove it:

rm -rf .flowstate/instances/old-instance

Or let FlowState prompt on completion, or use --clean-on-end.

Environment

FlowState respects these environment variables:

Variable	Description
HOME	User home directory for ~/.flowstate/

Tool-specific variables (e.g., GEMINI_API_KEY) are passed through to tool execution.