Skip to content

Installation

This guide will walk you through installing and setting up the WireFlow CLI tool.

Prerequisites

Before installing WireFlow, ensure you have the following:

  • Bash 4.0+: The tool is written as a bash script
  • curl: For downloading files and making API calls
  • jq: For JSON processing
  • LLM API access: Either an Anthropic API key OR an OpenAI-compatible local server

API Provider Options

WireFlow supports two API providers:

Option 1: Anthropic Claude API (Default)

If you don't have an Anthropic API key yet:

  1. Visit the Anthropic Console
  2. Sign up or log in to your account
  3. Navigate to API Keys section
  4. Create a new API key
  5. Save it securely - you'll need it for configuration

Keep Your API Key Secure

Never commit your API key to version control or share it publicly. Use environment variables or the global configuration file to store it securely.

Option 2: OpenAI-Compatible Local Server

WireFlow works with any OpenAI API-compatible endpoint, including:

  • LM Studio: Run local LLMs with OpenAI-compatible API
  • ollama: Local LLM runner with API server
  • vLLM: High-throughput LLM serving
  • Any OpenAI-compatible server: Self-hosted or cloud

No API key required for most local servers. See Provider Configuration below.

Optional Dependencies

WireFlow supports various document types with optional dependencies:

PDF Documents

Built-in support: PDF files are automatically processed using the Claude API, which jointly analyzes both the text content and visual elements (diagrams, charts, images) from each page of the PDF. No additional dependencies required.

Microsoft Office Files (.docx, .pptx)

Requires LibreOffice: Office files are automatically converted to PDF for processing. This requires the soffice command-line tool from LibreOffice.

Installing LibreOffice

macOS: 

brew install --cask libreoffice

Linux (Ubuntu/Debian): 

sudo apt-get install libreoffice

Linux (Fedora/RHEL): 

sudo dnf install libreoffice

Or download directly: https://www.libreoffice.org/download/download-libreoffice/

After installing LibreOffice, you need to create a symlink to the soffice command so it's available on your PATH:

macOS: 

# Create symlink in user bin directory
ln -s /Applications/LibreOffice.app/Contents/MacOS/soffice ~/.local/bin/soffice

# Or if LibreOffice is in ~/Applications
ln -s ~/Applications/LibreOffice.app/Contents/MacOS/soffice ~/.local/bin/soffice

# Verify it works
soffice --version

Linux:

On most Linux distributions, the soffice command is automatically added to PATH during installation. Verify with:

soffice --version

If not found, create a symlink:

ln -s /usr/bin/soffice ~/.local/bin/soffice

Graceful Degradation

If LibreOffice is not installed, WireFlow will skip Office files with a warning message and continue processing other documents. The tool will work fine without it if you only use PDF, text, and image files.

Image Files (.jpg, .png, .gif, .webp)

Built-in support: Images are automatically processed using the Claude Vision API. No additional dependencies required, though ImageMagick is recommended for optimal image resizing:

macOS: 

brew install imagemagick

Linux: 

sudo apt-get install imagemagick  # Ubuntu/Debian
sudo dnf install imagemagick      # Fedora/RHEL

PDF to Image Conversion (OpenAI Provider)

Requires poppler-utils: When using the OpenAI provider (local LLMs), PDF files are automatically converted to page images since OpenAI API doesn't support native PDFs. This requires pdftoppm:

macOS: 

brew install poppler

Linux: 

sudo apt-get install poppler-utils  # Ubuntu/Debian
sudo dnf install poppler-utils      # Fedora/RHEL

Anthropic Provider

If using the default Anthropic provider, pdftoppm is not required - PDFs are processed natively.

Enhanced Output Display

WireFlow can use enhanced pagers for better output display. These are optional but recommended for the best experience:

glow - Renders markdown beautifully in the terminal (charmbracelet/glow):

# macOS
brew install glow

# Linux
# See https://github.com/charmbracelet/glow#installation

gum - Enhanced text paging for all file types (charmbracelet/gum):

# macOS
brew install gum

# Linux
# See https://github.com/charmbracelet/gum#installation

Without these tools, WireFlow falls back to $PAGER (if set) or less.

Request Inspection

yq - Enables JSON to XML conversion for easier request file inspection:

# macOS
brew install yq

# Linux
# See https://github.com/mikefarah/yq#install

Without yq, request files are saved as JSON only.

Installation Methods

Clone the repository and use the built-in installer:

# Clone the repository
git clone https://github.com/jdmonaco/wireflow.git
cd wireflow

# Install using shell integration (creates symlinks automatically)
./wireflow.sh shell install

# Verify installation
wfw help

The shell install command creates symlinks to:

  • ~/.local/bin/wfw - Binary symlink
  • ~/.local/share/bash-completion/completions/wfw - Tab completion
  • ~/.local/share/wireflow/wfw-prompt.sh - Prompt helper (optional)

Add to PATH

If ~/.local/bin is not in your PATH, add to ~/.bashrc or ~/.zshrc: 

export PATH="$HOME/.local/bin:$PATH"

Shell Integration Commands

The wfw shell subcommand provides three actions:

Action Description
install Create symlinks (skips if already installed)
doctor Force reinstall symlinks + diagnose setup issues
uninstall Remove symlinks and check for config references

Use wfw shell doctor after moving the repository or to diagnose bash-completion issues.

Manual Installation (Alternative)

If you prefer manual control over symlink locations:

# Clone the repository
git clone https://github.com/jdmonaco/wireflow.git
cd wireflow

# Create symlink to add to PATH
# Option A: User-local installation (~/.local/bin)
ln -s "$(pwd)/wireflow.sh" ~/.local/bin/wfw

# Option B: User bin directory (~/bin)
ln -s "$(pwd)/wireflow.sh" ~/bin/wfw

# Verify installation
wfw help

Method 2: System-Wide Installation

For system-wide installation (requires sudo):

# Clone the repository
git clone https://github.com/jdmonaco/wireflow.git
cd wireflow

# Create symlink in system directory
sudo ln -s "$(pwd)/wireflow.sh" /usr/local/bin/wfw

Why Clone Instead of Single-File Download?

WireFlow is a modular tool that includes:

  • wireflow.sh - Main script
  • lib/ - Library modules (core, config, help, task, utils, api)
  • tests/ - Test suite

All components are needed for the tool to function properly.

Bash Completions

If you used wfw shell install, bash completions are installed automatically. They load in new shells that use bash-completion.

To enable completions in your current shell:

source ~/.local/share/bash-completion/completions/wfw

Tab completion works for:

  • Subcommands: wfw <tab>
  • Workflow names: wfw run <tab>, wfw edit <tab>
  • Task templates: wfw task <tab>, wfw new myflow --from-task <tab>
  • Options: wfw run myworkflow --<tab>
  • File paths: wfw run myworkflow -cx <tab>

Troubleshooting Completions

If completions aren't working, run wfw shell doctor to diagnose. It checks whether the bash-completion package is installed and provides OS-specific setup instructions.

Prompt Integration (Optional)

WireFlow provides a __wfw_ps1() function for including the current project name in your shell prompt, similar to __git_ps1() from git.

To enable, add to your ~/.bashrc:

# Source the prompt helper
source ~/.local/share/wireflow/wfw-prompt.sh

# Add project indicator to your prompt
export PS1='\w$(__wfw_ps1 " (%s)")\$ '

When inside a WireFlow project, your prompt will show the project name:

~/projects/my-app (my-app)$

The function accepts an optional format string (default: " (%s)"). Outside a project, it outputs nothing.

Environment Setup

Required: API Key Configuration

You have two options for configuring your API key:

Option 1: Environment Variable

Set the API key as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."

To make it permanent, add to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc

On first use, WireFlow automatically creates ~/.config/wireflow/config where you can store your API key:

# Run any wireflow command to trigger auto-creation
wfw help

# Edit the global config (opens in $EDITOR)
"${EDITOR:-nano}" ~/.config/wireflow/config

Add your API key to the config file:

ANTHROPIC_API_KEY=sk-ant-...

Environment Variables Take Precedence

If you set the API key in both places, the environment variable will take precedence over the config file.

Provider Configuration

To use an OpenAI-compatible local server instead of Anthropic:

# Edit global config
"${EDITOR:-nano}" ~/.config/wireflow/config

Add provider settings:

# Use OpenAI-compatible API (e.g., LM Studio)
PROVIDER="openai"
OPENAI_BASE_URL="http://localhost:1234"

# Model profiles for local models
OPENAI_MODEL_FAST="phi-4-mini"
OPENAI_MODEL_BALANCED="qwen2.5-14b"
OPENAI_MODEL_DEEP="qwen2.5-72b"

LM Studio Setup

  1. Download and install LM Studio
  2. Download models (e.g., Qwen 2.5, Phi-4)
  3. Open Settings (Cmd/Ctrl + ,) and configure:
    • Serve on Local Network: Enable to access from other machines
    • Just-in-Time Model Loading: Enable so /v1/models returns all downloaded models
    • Auto Unload Unused Models: Set idle TTL (e.g., 60 min) to free memory
    • Only Keep Last JIT Loaded Model: Enable to avoid memory issues with multiple models
  4. Start the local server (default: http://localhost:1234)
  5. Configure WireFlow with the server URL and model names

Optional: Run as headless service

  • Enable "Run LLM server on login" in Settings for background operation
  • Or start programmatically: lms server start
  • Exiting the app minimizes to system tray while server continues running

Optional: Custom System Prompts

By default, WireFlow creates a base system prompt at ~/.config/wireflow/prompts/base.txt. If you want to use a custom prompt directory:

export WIREFLOW_PROMPT_PREFIX="$HOME/custom/prompts"

You can also set this in the global config file:

WIREFLOW_PROMPT_PREFIX=$HOME/custom/prompts

Optional: Task Prefix Directory

If you plan to use named tasks (see Execution Guide), set a directory for task templates:

export WIREFLOW_TASK_PREFIX="$HOME/.config/wireflow/tasks"

Or in the global config:

WIREFLOW_TASK_PREFIX=$HOME/.config/wireflow/tasks

First-Run Auto-Configuration

The first time you run any wireflow command, it will automatically:

  1. Create ~/.config/wireflow/ directory
  2. Create a default config file with sensible defaults
  3. Create prompts/ subdirectory
  4. Create a default prompts/base.txt system prompt

This means you can start using WireFlow immediately after setting your API key!

Verification

Verify your installation is working:

# Check help works
wfw help

# Verify global config was created
ls ~/.config/wireflow/

# Check API key is configured
wfw config  # Run from any directory

You should see your global configuration values displayed.

Next Steps

Now that WireFlow is installed, you're ready to:

  1. Follow the Quick Start Guide for a 5-minute introduction
  2. Create your First Workflow with detailed walkthrough
  3. Explore the User Guide for comprehensive usage

Troubleshooting

Command Not Found

If you get wfw: command not found, ensure:

  • The script is executable: chmod +x ~/bin/wfw
  • ~/bin is in your PATH: echo $PATH
  • You've reloaded your shell: source ~/.bashrc

If you moved the WireFlow repository after installation, run wfw shell doctor to fix broken symlinks.

Completions Not Working

If tab completion isn't working:

  1. Run wfw shell doctor to diagnose the issue
  2. Ensure bash-completion package is installed:
    • macOS: brew install bash-completion@2
    • Linux: sudo apt install bash-completion
  3. Verify bash-completion is sourced in your ~/.bashrc
  4. Start a new shell or run source ~/.bashrc

jq Not Found

Install jq using your package manager:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# CentOS/RHEL
sudo yum install jq

API Key Issues

If you get API authentication errors:

  • Verify your key is set: echo $ANTHROPIC_API_KEY
  • Check the global config: cat ~/.config/wireflow/config
  • Ensure the key starts with sk-ant-
  • Verify the key is active in the Anthropic Console

For more troubleshooting, see the Troubleshooting Guide.