Documentation

Everything you need to start automating with Floma

Installation

Choose your platform and get started in seconds:

macOS / Linux

brew tap getfloma/floma && brew install floma

Windows

winget install getfloma.floma

Don't have Homebrew or Winget installed?
→ Install Homebrew: brew.sh
→ Winget comes pre-installed on Windows 10/11
→ Or use the Alternative Installation Methods below

Alternative Installation Methods

Direct Download (macOS/Linux)

# macOS (Apple Silicon)
mkdir -p ~/.local/bin
curl -L https://pub-3da12ce477ba4b969191f6514d7505ff.r2.dev/floma-macos-arm64 -o ~/.local/bin/floma
chmod +x ~/.local/bin/floma

# macOS (Intel)
curl -L https://pub-3da12ce477ba4b969191f6514d7505ff.r2.dev/floma-macos-x86_64 -o ~/.local/bin/floma

# Linux (x86_64)
curl -L https://pub-3da12ce477ba4b969191f6514d7505ff.r2.dev/floma-linux-x86_64 -o ~/.local/bin/floma

# Linux (ARM64)
curl -L https://pub-3da12ce477ba4b969191f6514d7505ff.r2.dev/floma-linux-arm64 -o ~/.local/bin/floma

Windows (PowerShell)

Invoke-WebRequest -Uri "https://pub-3da12ce477ba4b969191f6514d7505ff.r2.dev/floma-windows-x86_64.exe" -OutFile "floma.exe"
Move-Item floma.exe C:\Windows\System32\floma.exe

Updating: Use brew update && brew upgrade floma or winget upgrade getfloma.floma to get the latest version.

Quick Start

Create your first workflow in seconds:

floma new "organize Downloads by file type into folders (Images, Documents, Videos, etc.)"
✓ Created: organize-downloads
  Trigger: Manual
  Actions: File organization by type

Run it immediately:

floma run organize-downloads
✓ Organized 47 files into 5 categories
  Images/     → 23 files
  Documents/  → 12 files
  Videos/     → 8 files
  Archives/   → 4 files

Creating Your First Workflow

Describe what you want to automate in plain English. Floma's AI will generate the workflow for you:

Natural Language Examples

"Extract PDFs from downloads every friday at 9am"
"In Documents, move all files not in folders to a misc folder"
"Watch ~/app/logs for ERROR and alert me immediately"
"Extract receipt totals from ~/receipts and update expenses.xlsx weekly"
"Backup ~/Projects to USB every night at 2am"

floma new

Create a new workflow from natural language:

floma new "your instruction here"

Example:

floma new "extract invoice totals from PDFs in ~/Invoices and append to expenses.xlsx every Friday at 9am"
✓ Created: extract-invoice-totals
  Schedule: Fridays at 9:00 AM
  Actions: PDF extraction → Excel update

floma list

View all your workflows and their schedules:

floma list
extract-invoice-totals   Fridays 9am      last: 2 days ago
backup-projects          Daily 2am        last: 8 hours ago

floma run

Execute a workflow manually:

floma run extract-invoice-totals
Running...
✓ Extracted totals from 12 invoices
✓ Appended 12 rows to expenses.xlsx
  Total: $4,873.92

floma view

Inspect a specific workflow:

floma view extract-invoice-totals
Name: extract-invoice-totals
Schedule: Fridays at 9:00 AM
Trigger: cron
Actions: PDF extraction → Excel update

Workflow Templates

NEW in v0.3.17: Use pre-built workflow templates to get started quickly.

List Templates

floma templates
📚 Available Workflow Templates:
  invoice-processor
    Extract invoice totals from PDFs and append to Excel
    Category: Finance

  daily-backup
    Backup important folders with compression
    Category: Backup

Use a Template

floma templates use invoice-processor
📋 Using template: Invoice Processor
Configure template variables:
  invoices_folder [~/Invoices]: ~/Documents/Invoices
  output_file [~/invoices-summary.xlsx]: 
✓ Created workflow: invoice-processor

Export & Import Workflows

Share workflows with others or backup your automation:

Export

# Export to file
floma export my-workflow --output backup.json
✓ Exported workflow to: backup.json

# Or print to stdout
floma export my-workflow

Import

floma import backup.json
✓ Imported workflow: my-workflow
  Run with: floma run my-workflow

Scheduler Daemon

The daemon runs workflows automatically based on their schedules:

Start the Daemon

floma start-daemon
✓ Scheduler daemon started
  3 workflows scheduled

Check Status

floma status
Scheduler: running
Next runs:
  extract-invoice-totals   Fri 9:00 AM (in 2 days)
  backup-projects          Sat 2:00 AM (in 8 hours)

Stop the Daemon

floma stop-daemon
✓ Scheduler stopped

Explain Workflows

Get a detailed explanation of what a workflow does:

floma explain extract-invoice-totals
Every Friday at 9:00 AM:
  1. Scan ~/Invoices folder for PDF files
  2. Extract total amounts using AI
  3. Append invoice data to expenses.xlsx

Auto-Repair Errors

Let AI diagnose and fix workflow issues:

floma ai-repair extract-invoice-totals
Analyzing workflow errors...
✓ Issue identified: expenses.xlsx doesn't exist
✓ Repaired workflow
  Created: ~/expenses.xlsx with headers

Get Improvement Suggestions

Optimize your workflows with AI recommendations:

floma improve extract-invoice-totals
Suggestions:
  • Add email notification with weekly summary
  • Archive processed invoices to ~/Invoices/Processed
  • Track invoice numbers to avoid duplicates

What Can Floma Do?

Floma has 59+ built-in actions for file organization, document processing, monitoring, notifications, and more. The AI figures out which actions to use - you just describe what you want in plain English.

Examples of what people use it for:

"Extract totals from PDFs and append to Excel"
"Organize downloads by file type weekly"
"Resize all images to 1200px wide"
"Backup my projects folder every night at 2am"
"Alert me when disk space is low"
"Merge all monthly PDFs into one report"
"Find and delete duplicate files"
"Watch logs for errors and send Slack alerts"

Don't see your use case? Just ask - Floma combines actions intelligently to handle complex workflows.

Workflow Chaining

NEW in v0.3.16: Chain workflows together to build complex automation pipelines. Execute workflows sequentially with conditional logic.

Features:

Execute workflows in sequence
Conditional chaining: run on success, failure, or always
Pass data between workflows
Circular dependency detection (prevents infinite loops)
Max chain depth limit (10 levels)

Example: Chain workflows based on conditions

# In your workflow JSON, add a chain_workflow action:
{
  "type": "chain_workflow",
  "workflow_id": "send-email-report",
  "condition": "on_success",
  "pass_data": false
}

Conditions:

"always" - Always chain to the next workflow
"on_success" - Chain only if previous action succeeded
"on_failure" - Chain only if previous action failed

Real-world example:

# Analyze disk → Clean files if needed → Email report
floma new "analyze disk space"
floma new "clean old files from downloads"
floma new "send disk usage report"

# Then manually edit the workflow to add chaining

Configuration

Floma stores its data in your home directory:

Workflows: ~/.floma/workflows/
Configuration: ~/.floma/config.json
State: ~/.floma/state/
Logs: ~/.floma/logs/

Troubleshooting

Get Help

Use the built-in help for any command:

floma --help
floma new --help

View Logs

Check logs for debugging:

cat ~/.floma/logs/floma.log
cat ~/.floma/logs/daemon.log

Daemon Won't Start

# Check if already running
floma status

# Remove stale PID file if needed
rm ~/.floma/daemon.pid

# Try foreground mode for debugging
floma start-daemon --foreground