Skip to content
Back to search

formanator

Submit Forma <https://joinforma.com> benefit claims from the command line and Model Context Protocol (MCP) clients, with support for AI-powered receipt analysis with an LLM or Jev

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/timrogers--formanator/badge.svg)](/listings/timrogers--formanator)

HTML

<a href="/listings/timrogers--formanator"><img src="/api/listings/timrogers--formanator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

macOS or Linux via [Homebrew](https://brew.sh/)

brew tap timrogers/tap && brew install formanator

macOS, Linux, or Windows via [Cargo](https://doc.rust-lang.org/cargo/), Rust's package manager

1. Install [Rust](https://www.rust-lang.org/tools/install) on your machine, if it isn't already installed. 1. Install the `formanator` crate by running `cargo install formanator`. 1. 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](https://github.com/timrogers/formanator/releases/latest) for your platform. macOS, Linux, and Windows devices are supported. 1. 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). 1. 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](http://www.graphicsmagick.org/) and [Ghostscript](https://www.ghostscript.com/) installed.

# macOS
brew install graphicsmagick ghostscript

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 211 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Formanator 🤖
  2. > [!NOTE]
  3. > 🦀 Formanator is now built with Rust and distributed through Homebrew and Crates.io! [v2.x](https://github.com/timrogers/formanator/releases/tag/v2.2.0), built in TypeScript and distributed through npm, is [still available](https://github.com/timrogers/formanator/releases/tag/v2.2.0).
  4. Formanator allows you to:
  5. * **Submit benefit claims to [Forma](https://www.joinforma.com/) and track progress from the command line**, either one-by-one or in bulk
  6. * **Understand your Forma benefits and track and submit claims from any Model Context Protocol (MCP) client**, for example [Copilot CLI](https://github.com/features/copilot/cli), [Visual Studio Code](https://code.visualstudio.com/) or [Claude Code](https://code.claude.com/docs/en/overview)
  7. With the power of large language models 🧠👀 - via the [GitHub Copilot CLI](https://github.com/features/copilot/cli) (free, no extra configuration needed) or [OpenAI](https://openai.com/) - it can even **analyse your receipts and generate your claims automatically**.
  8. ![Screenshot of running `formanator` from a terminal](https://github.com/user-attachments/assets/e053efc8-f4cb-4ea1-8850-6c82d668bf29)
  9. ## Installation
  10. ### macOS or Linux via [Homebrew](https://brew.sh/)
  11. ```bash
  12. brew tap timrogers/tap && brew install formanator
  13. ```
  14. ### macOS, Linux, or Windows via [Cargo](https://doc.rust-lang.org/cargo/), Rust's package manager
  15. 1. Install [Rust](https://www.rust-lang.org/tools/install) on your machine, if it isn't already installed.
  16. 1. Install the `formanator` crate by running `cargo install formanator`.
  17. 1. Run `formanator --help` to check that everything is working and see the available commands.
  18. ### macOS, Linux, or Windows via direct binary download
  19. 1. Download the [latest release](https://github.com/timrogers/formanator/releases/latest) for your platform. macOS, Linux, and Windows devices are supported.
  20. 1. 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).
  21. 1. Run `formanator --help` to check that everything is working.
  22. ### From source
  23. ```bash
  24. git clone https://github.com/timrogers/formanator
  25. cd formanator
  26. cargo install --path .
  27. ```
  28. ### Optional: PDF receipt support
  29. To infer claim details for PDF receipts, you need to have [GraphicsMagick](http://www.graphicsmagick.org/) and [Ghostscript](https://www.ghostscript.com/) installed.
  30. ```bash
  31. # macOS
  32. brew install graphicsmagick ghostscript
  33. ```
  34. ## Usage
  35. ### Connecting to your Forma account
  36. To get started, you'll need to connect Formanator to your Forma account:
  37. 1. Run `formanator login`.
  38. 2. Press Enter to open your browser to the Forma login page.
  39. 3. Enter your email address and request a magic link.
  40. 4. Copy the magic link from your email and paste it into the terminal. Formanator accepts either the full `joinforma.page.link` URL or its decoded `client.joinforma.com/auth/magic` target.
  41. 5. You're logged in 🥳
  42. The access token is securely stored in the system Keychain on macOS. On other platforms, it's stored in `~/.formanator.toml`.
  43. ### Automatic update checks
  44. 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.
  45. ### Configuring inference providers (optional, but recommended)
  46. When submitting a claim you can either provide every detail manually or let an LLM infer them. Three providers are supported:
  47. - **GitHub Copilot CLI** — _the default._ If you don't configure an OpenAI-compatible API key, Formanator uses the [GitHub Copilot CLI](https://github.com/features/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.
  48. - **OpenAI** — billed to your OpenAI account. Set the `OPENAI_API_KEY` environment variable, or pass `--openai-api-key`. You can also customise the model with `OPENAI_MODEL` / `--openai-model` (default: `gpt-5.4-mini`).
  49. - **Other OpenAI-compatible inference providers** — any provider with an OpenAI-compatible API (e.g. Azure OpenAI, Ollama, or a local model server). Set `OPENAI_API_KEY` / `--openai-api-key` to your API key and `OPENAI_BASE_URL` / `--openai-base-url` to the provider's base URL (default: `https://api.openai.com/v1`). Set the model with `OPENAI_MODEL` / `--openai-model`.
  50. If both an OpenAI-compatible API key and the GitHub Copilot CLI are available, Formanator prefers the OpenAI-compatible API.
  51. #### Using Jev for benefit and category selection
  52. [Jev](https://docs.typesafe.ai/introduction) is TypeSafe's System One decision model. Instead of generating free-form text, it answers narrowly defined questions with typed choices and calibrated probabilities that application code can validate and act on.
  53. When you provide the amount, merchant, purchase date and description yourself, Jev can select the most appropriate benefit and category instead of using the configured LLM:
  54. ```bash
  55. export TYPESAFE_API_KEY="..."
  56. formanator submit-claim \
  57. --amount 1000 \
  58. --merchant "Open University" \
  59. --description "MBA tuition fee" \
  60. --purchase-date 2026-09-20 \
  61. --receipt-path receipt.pdf \
  62. --category-provider jev
  63. ```
  64. You can also pass the key with `--typesafe-api-key`, or set `FORMANATOR_CATEGORY_PROVIDER=jev` instead of passing `--category-provider` each time.
  65. Jev receives only the merchant, description and the valid benefit/category pairs returned by Forma. It does not receive receipt images. If Jev's confidence is below 0.5 or it determines that none of the available categories match, Formanator visibly falls back to the configured OpenAI-compatible provider or GitHub Copilot CLI. TypeSafe authentication and API errors are reported directly rather than silently falling back.
  66. Full inference from a receipt, including benefit and category selection, continues to use the configured vision-capable LLM.
  67. ### Submitting claims in bulk
  68. #### Automatically submitting all receipts in a directory (recommended)
  69. ```bash
  70. formanator submit-claims-from-directory --directory input/
  71. ```
  72. 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.
  73. Every receipt is analysed up front, with a progress bar, so you can walk away while that runs and then confirm all of them back to back. If the LLM provider itself can't be reached — bad API key, missing model, Copilot CLI that won't start — Formanator stops straight away instead of failing its way through the rest of the directory.
  74. If you trust the LLM and don't want to confirm anything, add `--yolo` to submit every receipt as soon as it's been analysed:
  75. ```bash
  76. formanator submit-claims-from-directory --directory input/ --yolo
  77. ```
  78. #### Manually submitting receipts using a CSV template
  79. 1. Generate a template: `formanator generate-template-csv` (writes `claims.csv`).
  80. 2. Fill in one row per claim. You can leave `benefit` and `category` blank to have them inferred from the other fields, optionally using `--category-provider jev`, or leave every column except `receiptPath` blank to have all claim details inferred from the receipt using the configured LLM. Comma-separate paths in the `receiptPath` column to attach multiple receipts.
  81. 3. Optionally validate up-front: `formanator validate-csv --input-path claims.csv`.
  82. 4. Submit: `formanator submit-claims-from-csv --input-path claims.csv`.
  83. ### Submitting a single claim
  84. #### Option 1: Infer all claim details from the receipt (recommended)
  85. ```bash
  86. formanator submit-claim --receipt-path receipt.jpg
  87. ```
  88. 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. Pass `--yolo` to skip the confirmation and submit straight away.
  89. #### Option 2: Provide details manually, infer benefit and category
  90. ```bash
  91. formanator submit-claim \
  92. --amount 2.28 \
  93. --merchant Amazon \
  94. --description "USB cable" \
  95. --purchase-date 2024-01-15 \
  96. --receipt-path USB.pdf
  97. ```
  98. #### Option 3: Provide every detail manually
  99. ```bash
  100. formanator submit-claim \
  101. --amount 2.28 \
  102. --merchant Amazon \
  103. --description "USB cable" \
  104. --purchase-date 2024-01-15 \
  105. --receipt-path USB.pdf \
  106. --benefit "Remote Life" \
  107. --category "Cables & Cords"
  108. ```
  109. Use `formanator benefits` and `formanator categories --benefit <benefit>` to discover the valid values.
  110. ### Listing claims
  111. ```bash
  112. formanator list-claims
  113. formanator list-claims --filter in_progress
  114. ```
  115. ## Model Context Protocol (MCP) usage
  116. Formanator can run as an MCP server over stdio so AI assistants can interact with your Forma account programmatically.
  117. ```jsonc
  118. {
  119. "mcpServers": {
  120. "formanator": {
  121. "command": "/path/to/formanator",
  122. "args": ["mcp"]
  123. }
  124. }
  125. }
  126. ```
  127. The server exposes six tools:
  128. - `auth_status` — check whether Formanator is logged in to Forma.
  129. - `login_start` — request a Forma magic link by email.
  130. - `login_complete` — complete login by pasting the emailed magic link.
  131. - `list_benefits_with_categories` — list all benefits with their categories and remaining balances.
  132. - `list_claims` — list claims, with optional filtering (currently only `in_progress`).
  133. - `create_claim` — create a new claim.
  134. 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`.
  135. To build a binary without MCP support (smaller binary, fewer dependencies):
  136. ```bash
  137. cargo install formanator --no-default-features
  138. ```
  139. ## Development
  140. ```bash
  141. cargo build # build with default features (CLI + MCP)
  142. cargo test --all-features
  143. cargo clippy --all-features --all-targets -- -D warnings
  144. cargo fmt --all
  145. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.