Getting Started

This guide walks through installing FlowState, creating a workflow, and running it.

Installation

Prerequisites

• .NET 9.0 SDK or later
• macOS or Linux (Windows support is experimental)

Build from Source

# Clone the repository
git clone https://github.com/your-org/flowstate.git
cd flowstate

# Build the project
dotnet build -c Release

# Install globally
./install.sh

The install script copies the binary to ~/.local/bin/fs. Ensure this directory is in your PATH.

Verify Installation

fs --help

You should see available commands: run, list, resume.

Workflow Discovery

FlowState searches for workflows in these locations (in order):

1. Project directory: ./.flowstate/
2. User directory: ~/.flowstate/

Workflows can be defined as:

• Folder-based: .flowstate/my-workflow/index.yaml (recommended for complex workflows with bundled files)
• File-based: .flowstate/my-workflow.yaml (simpler, single-file workflows)

Project workflows take precedence over user workflows with the same name.

Your First Workflow

Create a simple workflow that demonstrates core concepts.

Create the Workflow

mkdir -p .flowstate/hello-world

Create .flowstate/hello-world/index.yaml:

name: hello-world
start-at: greet

states:
  greet:
    tool: bash
    arguments:
      command: echo "Hello from FlowState!"
    next: ask-name

  ask-name:
    tool: ask-user
    arguments:
      question: "What is your name?"
    output: var(name)
    next: personalize

  personalize:
    tool: bash
    arguments:
      command: 'echo "Nice to meet you, {{ name }}!"'

Run the Workflow

fs run hello-world

FlowState will:

1. Prompt for an instance name (or generate one)
2. Execute greet - prints “Hello from FlowState!”
3. Execute ask-name - prompts for your name, stores in name variable
4. Execute personalize - greets you by name
5. Complete and optionally clean up the instance

Examine the Instance

Before the workflow completes, the instance directory at .flowstate/instances/<instance-name>/ contains:

workflow/
  index.yaml      # Copy of the workflow definition
context.json      # Execution state and variables

The context.json tracks the current state, variables, and status.

Running Workflows

Interactive Mode

fs run my-workflow

If instances exist, you can choose to resume one or create new.

Create Named Instance

fs run my-workflow --name my-instance

Creates a new instance with the specified name. Fails if the name already exists.

Resume Existing Instance

fs run my-workflow --resume my-instance

Continues execution from where the instance left off.

Non-Interactive Mode

For CI/CD or scripts, always specify --name or --resume:

fs run my-workflow --name build-$(date +%Y%m%d)

Cleanup on Completion

fs run my-workflow --clean-on-end

Automatically deletes the instance directory on successful completion.

Listing Workflows

See all available workflows:

fs list

Output shows workflow names and inheritance relationships:

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

Next Steps

• States - Deep dive into state definitions
• Variables - Variable substitution and output capture
• Error Handling - Graceful failure recovery