{"id":15590736,"url":"https://github.com/timrogers/formanator","last_synced_at":"2026-04-21T21:01:24.219Z","repository":{"id":184874911,"uuid":"672323348","full_name":"timrogers/formanator","owner":"timrogers","description":"Submit Forma (https://joinforma.com) claims from the command line 🤖","archived":false,"fork":false,"pushed_at":"2025-08-28T22:08:37.000Z","size":1032,"stargazers_count":66,"open_issues_count":8,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-29T01:12:11.183Z","etag":null,"topics":["cli","forma"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timrogers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"timrogers"}},"created_at":"2023-07-29T17:19:43.000Z","updated_at":"2025-08-28T21:12:56.000Z","dependencies_parsed_at":"2023-09-28T11:03:30.795Z","dependency_job_id":"25540120-6b8e-499e-8ee7-6dcc8bdd91d5","html_url":"https://github.com/timrogers/formanator","commit_stats":{"total_commits":134,"total_committers":2,"mean_commits":67.0,"dds":"0.32835820895522383","last_synced_commit":"e1bedd9b5ebd5449f7174e4f3eeb08a80c3e0bdf"},"previous_names":["timrogers/formanator"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/timrogers/formanator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timrogers%2Fformanator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timrogers%2Fformanator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timrogers%2Fformanator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timrogers%2Fformanator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timrogers","download_url":"https://codeload.github.com/timrogers/formanator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timrogers%2Fformanator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272880964,"owners_count":25008929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","forma"],"created_at":"2024-10-02T23:28:14.469Z","updated_at":"2026-04-21T21:01:24.214Z","avatar_url":"https://github.com/timrogers.png","language":"TypeScript","funding_links":["https://github.com/sponsors/timrogers"],"categories":[],"sub_categories":[],"readme":"# Formanator 🤖\n\n\u003e [!NOTE]\n\u003e 🦀 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).\n\nFormanator allows you to:\n\n* **Submit benefit claims to [Forma](https://www.joinforma.com/) and track progress from the command line**, either one-by-one or in bulk\n* **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)\n\nWith the power of large language models 🧠👀 - free of charge thanks to [GitHub Models](https://docs.github.com/en/github-models/use-github-models/prototyping-with-ai-models) - it can even **analyse your receipts and generate your claims automatically**.\n\n![Screenshot of running `formanator` from a terminal](https://github.com/user-attachments/assets/e053efc8-f4cb-4ea1-8850-6c82d668bf29)\n\n## Installation\n\n### macOS or Linux via [Homebrew](https://brew.sh/)\n\n```bash\nbrew tap timrogers/tap \u0026\u0026 brew install formanator\n```\n\n### macOS, Linux, or Windows via [Cargo](https://doc.rust-lang.org/cargo/), Rust's package manager\n\n1. Install [Rust](https://www.rust-lang.org/tools/install) on your machine, if it isn't already installed.\n1. Install the `formanator` crate by running `cargo install formanator`.\n1. Run `formanator --help` to check that everything is working and see the available commands.\n\n### macOS, Linux, or Windows via direct binary download\n\n1. Download the [latest release](https://github.com/timrogers/formanator/releases/latest) for your platform. macOS, Linux, and Windows devices are supported.\n1. 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).\n1. Run `formanator --help` to check that everything is working.\n\n### From source\n\n```bash\ngit clone https://github.com/timrogers/formanator\ncd formanator\ncargo install --path .\n```\n\n### Optional: PDF receipt support\n\nTo infer claim details for PDF receipts, you need to have [GraphicsMagick](http://www.graphicsmagick.org/) and [Ghostscript](https://www.ghostscript.com/) installed.\n\n```bash\n# macOS\nbrew install graphicsmagick ghostscript\n```\n\n## Usage\n\n### Connecting to your Forma account\n\nTo get started, you'll need to connect Formanator to your Forma account:\n\n1. Run `formanator login`.\n2. Press Enter to open your browser to the Forma login page.\n3. Enter your email address and request a magic link.\n4. Copy the magic link from your email and paste it into the terminal.\n5. You're logged in 🥳\n\nThe access token is stored in `~/.formanatorrc.json` (the same location used by the original Node.js implementation, so the two clients can share state).\n\n### Configuring an LLM provider (optional, but recommended)\n\nWhen submitting a claim you can either provide every detail manually or let an LLM infer them. Two providers are supported:\n\n- **GitHub Models** — free, with a generous quota. Set the `GITHUB_TOKEN` environment variable to a GitHub Personal Access Token with **read access to GitHub Models**, or pass `--github-token`.\n- **OpenAI** — billed to your OpenAI account. Set the `OPENAI_API_KEY` environment variable, or pass `--openai-api-key`.\n\nIf both are configured, Formanator prefers OpenAI.\n\n### Submitting claims in bulk\n\n#### Automatically submitting all receipts in a directory (recommended)\n\n```bash\nformanator submit-claims-from-directory --directory input/\n```\n\nAll `.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.\n\n#### Manually submitting receipts using a CSV template\n\n1. Generate a template: `formanator generate-template-csv` (writes `claims.csv`).\n2. 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.\n3. Optionally validate up-front: `formanator validate-csv --input-path claims.csv`.\n4. Submit: `formanator submit-claims-from-csv --input-path claims.csv`.\n\n### Submitting a single claim\n\n#### Option 1: Infer all claim details from the receipt (recommended)\n\n```bash\nformanator submit-claim --receipt-path receipt.jpg\n```\n\nFormanator 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.\n\n#### Option 2: Provide details manually, infer benefit and category\n\n```bash\nformanator submit-claim \\\n  --amount 2.28 \\\n  --merchant Amazon \\\n  --description \"USB cable\" \\\n  --purchase-date 2024-01-15 \\\n  --receipt-path USB.pdf\n```\n\n#### Option 3: Provide every detail manually\n\n```bash\nformanator submit-claim \\\n  --amount 2.28 \\\n  --merchant Amazon \\\n  --description \"USB cable\" \\\n  --purchase-date 2024-01-15 \\\n  --receipt-path USB.pdf \\\n  --benefit \"Remote Life\" \\\n  --category \"Cables \u0026 Cords\"\n```\n\nUse `formanator benefits` and `formanator categories --benefit \u003cbenefit\u003e` to discover the valid values.\n\n### Listing claims\n\n```bash\nformanator list-claims\nformanator list-claims --filter in_progress\n```\n\n## Model Context Protocol (MCP) usage\n\nFormanator can run as an MCP server over stdio so AI assistants can interact with your Forma account programmatically.\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"formanator\": {\n      \"command\": \"/path/to/formanator\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThe server exposes three tools:\n\n- `list_benefits_with_categories` — list all benefits with their categories and remaining balances.\n- `list_claims` — list claims, with optional filtering (currently only `in_progress`).\n- `create_claim` — create a new claim.\n\nYou must be logged in (`formanator login`) before starting the MCP server.\n\nTo build a binary without MCP support (smaller binary, fewer dependencies):\n\n```bash\ncargo install formanator --no-default-features\n```\n\n## Development\n\n```bash\ncargo build              # build with default features (CLI + MCP)\ncargo test --all-features\ncargo clippy --all-features --all-targets -- -D warnings\ncargo fmt --all\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimrogers%2Fformanator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimrogers%2Fformanator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimrogers%2Fformanator/lists"}