Formanator 🤖

[!NOTE] 🦀 Formanator is now built with Rust and distributed through Homebrew and Crates.io! v2.x, built in TypeScript and distributed through npm, is still available.

Formanator allows you to:

• Submit benefit claims to Forma and track progress from the command line, either one-by-one or in bulk
• Understand your Forma benefits and track and submit claims from any Model Context Protocol (MCP) client, for example Copilot CLI, Visual Studio Code or Claude Code

With the power of large language models 🧠👀 - free of charge thanks to GitHub Models - it can even analyse your receipts and generate your claims automatically.

Installation

macOS or Linux via Homebrew

brew tap timrogers/tap && brew install formanator

macOS, Linux, or Windows via Cargo, Rust's package manager

1. Install Rust on your machine, if it isn't already installed.
2. Install the formanator crate by running cargo install formanator.
3. Run formanator --help to check that everything is working and see the available commands.

macOS, Linux, or Windows via direct binary download

1. Download the latest release for your platform. macOS, Linux, and Windows devices are supported.
2. Add the binary to your PATH (or $PATH on Unix-like systems), so you can execute it from your shell/terminal. For the best experience, call it formanator (or formanator.exe on Windows).
3. Run formanator --help to check that everything is working.

From source

git clone https://github.com/timrogers/formanator
cd formanator
cargo install --path .

Optional: PDF receipt support

To infer claim details for PDF receipts, you need to have GraphicsMagick and Ghostscript installed.

# macOS
brew install graphicsmagick ghostscript

Usage

Connecting to your Forma account

To get started, you'll need to connect Formanator to your Forma account:

1. Run formanator login.
2. Press Enter to open your browser to the Forma login page.
3. Enter your email address and request a magic link.
4. Copy the magic link from your email and paste it into the terminal.
5. You're logged in 🥳

The access token is securely stored in the system Keychain on macOS. On other platforms, it's stored in ~/.formanator.toml.

Automatic update checks

Once a day, Formanator checks GitHub for a newer release. When one is available, it prints a yellow notice to stderr before running your command. The check is throttled by recording the last check timestamp in ~/.formanator.toml, only considers releases that are at least 72 hours old, and times out after 2 seconds so it can't slow the CLI down. To disable the check entirely, set the FORMANATOR_DISABLE_UPDATE_CHECK environment variable to any value.

Configuring an LLM provider (optional, but recommended)

When submitting a claim you can either provide every detail manually or let an LLM infer them. Three providers are supported:

• GitHub Copilot CLI — the default. If you don't configure OpenAI or GitHub Models, Formanator uses the GitHub Copilot CLI for inference. Formanator detects the copilot binary on your PATH automatically; if it lives elsewhere, set the COPILOT_CLI_PATH environment variable or pass --copilot-cli-path with the path to the binary.
• OpenAI — billed to your OpenAI account. Set the OPENAI_API_KEY environment variable, or pass --openai-api-key.
• GitHub Models — deprecated; may be removed in a future release. Free, with a generous quota. Set the GITHUB_MODELS_TOKEN environment variable to a GitHub Personal Access Token with read access to GitHub Models, or pass --github-models-token. When this provider is used, Formanator prints a deprecation warning to stderr.

If multiple are configured, Formanator prefers OpenAI, then GitHub Models, and otherwise falls back to the GitHub Copilot CLI.

Submitting claims in bulk

Automatically submitting all receipts in a directory (recommended)

formanator submit-claims-from-directory --directory input/

All .jpg, .jpeg, .png, .pdf and .heic receipts in the directory will be analysed by the LLM. You'll be asked to confirm the inferred claim details for each receipt before it's submitted, and successfully-submitted receipts are moved into a processed/ subdirectory.

Manually submitting receipts using a CSV template

1. Generate a template: formanator generate-template-csv (writes claims.csv).
2. Fill in one row per claim. If you've configured an LLM, you can leave benefit and category blank to have them inferred from the other fields, or leave every column except receiptPath blank to have all claim details inferred from the receipt. Comma-separate paths in the receiptPath column to attach multiple receipts.
3. Optionally validate up-front: formanator validate-csv --input-path claims.csv.
4. Submit: formanator submit-claims-from-csv --input-path claims.csv.

Submitting a single claim

Option 1: Infer all claim details from the receipt (recommended)

formanator submit-claim --receipt-path receipt.jpg

Formanator will ask the LLM to extract the amount, merchant, purchase date, description, benefit and category, show you the result and ask you to confirm before submitting.

Option 2: Provide details manually, infer benefit and category

formanator submit-claim \
  --amount 2.28 \
  --merchant Amazon \
  --description "USB cable" \
  --purchase-date 2024-01-15 \
  --receipt-path USB.pdf

Option 3: Provide every detail manually

formanator submit-claim \
  --amount 2.28 \
  --merchant Amazon \
  --description "USB cable" \
  --purchase-date 2024-01-15 \
  --receipt-path USB.pdf \
  --benefit "Remote Life" \
  --category "Cables & Cords"

Use formanator benefits and formanator categories --benefit <benefit> to discover the valid values.

Listing claims

formanator list-claims
formanator list-claims --filter in_progress

Model Context Protocol (MCP) usage

Formanator can run as an MCP server over stdio so AI assistants can interact with your Forma account programmatically.

{
  "mcpServers": {
    "formanator": {
      "command": "/path/to/formanator",
      "args": ["mcp"]
    }
  }
}

The server exposes six tools:

• auth_status — check whether Formanator is logged in to Forma.
• login_start — request a Forma magic link by email.
• login_complete — complete login by pasting the emailed magic link.
• list_benefits_with_categories — list all benefits with their categories and remaining balances.
• list_claims — list claims, with optional filtering (currently only in_progress).
• create_claim — create a new claim.

If you are not already logged in, use login_start and login_complete from your MCP client. You can still log in ahead of time with formanator login.

To build a binary without MCP support (smaller binary, fewer dependencies):

cargo install formanator --no-default-features

Development

cargo build              # build with default features (CLI + MCP)
cargo test --all-features
cargo clippy --all-features --all-targets -- -D warnings
cargo fmt --all