{"id":48963671,"url":"https://github.com/paperfoot/invoice-cli","last_synced_at":"2026-04-18T03:01:45.504Z","repository":{"id":352057589,"uuid":"1213650337","full_name":"paperfoot/invoice-cli","owner":"paperfoot","description":"Beautiful invoices from the CLI — international, stateful, agent-friendly","archived":false,"fork":false,"pushed_at":"2026-04-17T19:29:47.000Z","size":133,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T22:29:22.233Z","etag":null,"topics":["agent-cli-framework","agent-friendly","billing","cli","gst","invoice","multi-currency","pdf","rust","sqlite","typst","vat"],"latest_commit_sha":null,"homepage":"https://github.com/199-biotechnologies/invoice-cli","language":"Rust","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/paperfoot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T15:59:11.000Z","updated_at":"2026-04-17T19:29:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paperfoot/invoice-cli","commit_stats":null,"previous_names":["199-biotechnologies/invoice-cli","paperfoot/invoice-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/paperfoot/invoice-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Finvoice-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Finvoice-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Finvoice-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Finvoice-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paperfoot","download_url":"https://codeload.github.com/paperfoot/invoice-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Finvoice-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"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":["agent-cli-framework","agent-friendly","billing","cli","gst","invoice","multi-currency","pdf","rust","sqlite","typst","vat"],"created_at":"2026-04-18T03:01:44.645Z","updated_at":"2026-04-18T03:01:45.497Z","avatar_url":"https://github.com/paperfoot.png","language":"Rust","readme":"# invoice-cli\n\n\u003e Beautiful invoices from the CLI — international, stateful, agent-friendly.\n\nA stateful, single-binary CLI for generating, tracking, and rendering invoices.\nBuilt for humans who want a clean terminal workflow *and* for AI agents that\nneed a deterministic JSON interface to bill clients on their owner's behalf.\n\n## Why\n\nMost invoice tools fall into two camps:\n\n- **Full accounting suites** (Xero, Wave, QuickBooks) — powerful but overkill if\n  you just need to send a beautifully-branded invoice.\n- **Static generators** (typst templates, LaTeX invoices) — gorgeous output but\n  no state: you re-type client details every time, numbering drifts, and an\n  agent can't \"render last month's invoice\".\n\n`invoice-cli` sits between them: a stateful SQLite store of issuers, clients,\nproducts and invoices, a small set of beautiful Typst templates, and a JSON\ninterface built for agents.\n\n## Features\n\n- **Multi-issuer first-class.** Run several companies (SG Pte. Ltd., UK Ltd.,\n  US LLC, …) from one binary. Each issuer has its own jurisdiction, tax\n  profile, default template, numbering series, and logo.\n- **Per-client defaults.** Pin a default issuer and/or template per client —\n  then just `invoice invoices new --client meridian --item design` and the\n  right entity + branding lights up automatically.\n- **International tax profiles.** Built-in: Singapore GST 9%, UK VAT 20%,\n  US (state-variable), EU VAT, plus a `custom` profile. Reverse-charge flag\n  for EU cross-border B2B — rendered on the PDF with the legally-required\n  callout.\n- **Precise money math.** Amounts stored as `i64` minor units; tax math uses\n  `rust_decimal` — no float rounding artefacts. Discount math clamped at\n  zero so a mis-sized fixed discount can't flip totals negative.\n- **Discounts** at line or invoice level (rate or fixed amount).\n- **Five polished Typst templates** out of the box: `vienna`, `helvetica-nera`,\n  `tiefletter-gold`, `monoline`, `boutique`. Self-contained — single binary,\n  templates are embedded and extracted on first use.\n- **Logos per issuer.** Attach a PNG/SVG/JPG and each template renders it in\n  the header at the appropriate size for its design language.\n- **Credit notes.** Issue against any existing invoice with `credit-note\n  --full` (full reversal) or `--item ...` (specific refund lines). Independent\n  `CN-YYYY-NNNN` numbering series so credit notes don't collide with invoices.\n- **Draft-only editing.** Amend a draft's metadata with `invoices edit` or\n  its line items with `invoices items add|remove|edit`. Once issued, invoices\n  are immutable — the correct path for corrections is a credit note, which\n  preserves the audit trail and number-sequence integrity required by\n  SG/EU/UK regulations.\n- **QR pay-links.** Set `--pay-link https://buy.stripe.com/...` on an invoice\n  and the renderer stamps a scan-to-pay QR on the PDF.\n- **Lifecycle timestamps.** `mark issued` / `mark paid` auto-stamp\n  `issued_at` / `paid_at` (idempotent, first-transition-only).\n- **Aging + CSV export.** `invoices aging` buckets unpaid invoices into\n  0-30/31-60/61-90/90+ days overdue. `invoices export --from X --to Y\n  --format csv` gives you a clean accountant handoff.\n- **Agent-friendly.** Every command emits a JSON envelope when piped or\n  `--json`; `invoice agent-info` returns a capability manifest; structured\n  error codes with suggestions; exit codes distinguish transient vs permanent\n  failures. Install the embedded Claude/Codex/Gemini skill with\n  `invoice skill install`.\n\n## Install\n\n### Homebrew (macOS / Linux)\n\n```\nbrew tap 199-biotechnologies/tap\nbrew install invoice\n```\n\n### Cargo\n\n```\ncargo install invoice-cli\n```\n\n### From source\n\n```\ngit clone https://github.com/paperfoot/invoice-cli\ncd invoice-cli\ncargo install --path .\n```\n\nAll install paths produce a single `invoice` binary. Typst is the only runtime\ndependency (`brew install typst` on macOS).\n\n## Quick start\n\n```\n# 1. Register your billing entity (with logo + bank details)\ninvoice issuer add acme \\\n    --name \"Acme Studio\" --jurisdiction sg --tax-registered \\\n    --tax-id \"M2-1234567-8\" --address \"1 Marina Bay\\nSingapore 018989\" \\\n    --template boutique --logo ~/Pictures/acme.png \\\n    --bank-name \"DBS\" --bank-iban \"SG11DBSS...\" --bank-bic \"DBSSSGSG\"\n\n# 2. Add a client, pinning acme as their default issuer\ninvoice clients add meridian \\\n    --name \"Meridian \u0026 Co.\" --country US \\\n    --address \"530 5th Ave\\nNew York, NY 10036\" \\\n    --default-issuer acme --default-template boutique\n\n# 3. Register a reusable line item\ninvoice products add design \\\n    --description \"Creative direction\" --unit project \\\n    --price 8400 --currency SGD --tax-rate 9\n\n# 4. Create an invoice — no --as needed, uses client's default issuer\ninvoice invoices new --client meridian --item design --due 30d\n\n# 5. Render + open\ninvoice invoices render 2026-0001 --open\n\n# 6. Later: mark paid, clone for next month\ninvoice invoices mark 2026-0001 paid\ninvoice invoices duplicate 2026-0001\n\n# 7. Need a refund? Credit note against the original:\ninvoice invoices credit-note 2026-0001 --item \"Refund:1:500\" --notes \"Goodwill credit\"\n\n# 8. Month-end accountant handoff\ninvoice invoices export --from 2026-01-01 --to 2026-03-31 --format csv --out q1.csv\n```\n\n## Core commands\n\n| Command | Purpose |\n|---|---|\n| `issuer add\\|edit\\|list\\|show\\|delete` | Manage billing entities (your companies) |\n| `issuer set-template \u003cslug\u003e \u003ctmpl\u003e` | Shorthand to change an issuer's default template |\n| `clients add\\|edit\\|list\\|show\\|delete` | Manage clients (who you bill) |\n| `clients set-issuer \u003cslug\u003e \u003cissuer\u003e` | Pin default issuer for a client |\n| `clients set-template \u003cslug\u003e \u003ctmpl\u003e` | Pin default template for a client |\n| `products add\\|edit\\|list\\|show\\|delete` | Manage reusable line items |\n| `invoices new --client X --item Y` | Create a new invoice |\n| `invoices edit \u003cnumber\u003e` | Edit draft metadata (due, terms, notes, discount…) |\n| `invoices items add\\|remove\\|edit \u003cnumber\u003e` | Mutate line items on a draft invoice |\n| `invoices duplicate \u003cnumber\u003e` | Clone an invoice as a fresh draft (recurring billing) |\n| `invoices credit-note \u003cnumber\u003e` | Issue a credit note against an existing invoice |\n| `invoices render \u003cnumber\u003e [--template T] [--open]` | Generate PDF |\n| `invoices mark \u003cnumber\u003e draft\\|issued\\|paid\\|void` | Update status (auto-stamps timestamps) |\n| `invoices list [--status X] [--as Y] [--overdue]` | List invoices with totals |\n| `invoices aging [--as Y]` | Aging buckets for unpaid invoices |\n| `invoices export --from X --to Y --format csv\\|json` | Accountant handoff |\n| `invoices delete \u003cnumber\u003e [--force]` | Delete an invoice (`--force` for non-draft) |\n| `template list\\|preview \u003cname\u003e` | Inspect available templates |\n| `doctor` | Diagnose typst install, DB, templates |\n| `agent-info` | Full JSON capability manifest |\n| `skill install` | Install embedded Claude/Codex/Gemini skill |\n| `update [--check]` | Self-update via brew or cargo |\n\nRun `invoice --help` for the full reference or `invoice \u003csubcommand\u003e --help`\nfor any subcommand.\n\n## Template resolution\n\nAt render time, the template chain is:\n\n```\n--template flag  \u003e  client.default_template  \u003e  issuer.default_template  \u003e  \"vienna\"\n```\n\nSo pinning a template on a client gives them consistent branding without you\nhaving to pass `--template` every time.\n\n## Item specs\n\nOn `invoices new`, each `--item` is one of:\n\n- `product-slug` — uses the product's price, unit, and tax rate\n- `product-slug:qty` — e.g. `design:2` for two units\n- `\"Description:qty:price\"` — ad-hoc item with default tax rate from jurisdiction\n- `\"Description:qty:price:rate\"` — ad-hoc item with explicit tax rate\n\n## State \u0026 privacy\n\n- **Config:** `~/.config/invoice/config.toml` (Linux) or\n  `~/Library/Application Support/com.199-biotechnologies.invoice/` (macOS)\n- **Database:** `~/.local/share/invoice/invoice.db` (SQLite, WAL mode)\n- **Templates:** extracted once to the state dir, refreshed on upgrade\n\nNothing ever leaves your machine unless you choose to — no telemetry, no\nphone-home, no cloud sync.\n\n## Agent usage\n\nThis CLI is designed to be driven by AI agents as well as humans. The\ncontract:\n\n- Every command emits a `{version, status, data|error}` envelope when piped.\n- `invoice agent-info` returns a full capability + exit-code manifest.\n- `invoice skill install` drops a ready-to-use skill file into\n  `~/.claude/skills/invoice-cli/SKILL.md` (and the Codex/Gemini equivalents).\n\nTypical agent workflow:\n\n```\nUSER:  \"Bill Meridian for last month's design work\"\nAGENT: invoice invoices duplicate $(invoice invoices list --json | jq -r '.data[0].number')\n```\n\n## Architecture\n\n- **Rust** binary via `cargo` / single-binary distribution.\n- **SQLite** via `rusqlite` with `refinery` migrations (`migrations/V*.sql`).\n- **Typst** for PDF rendering — templates live in `typst/`, embedded via\n  `rust-embed` and extracted to the user's state dir.\n- **Money** as `i64` minor units; tax with `rust_decimal`. No floats in\n  financial paths.\n- **Built on** [`agent-cli-framework`](https://github.com/199-biotechnologies/agent-cli-framework)\n  (ACF) conventions for agent ergonomics.\n\n## Scope\n\nThis is an **invoicing tool**, not an accounting suite. In scope:\n\n- Clean, branded invoice generation across multiple entities\n- Multi-currency, multi-jurisdiction tax handling\n- Lifecycle tracking (draft → issued → paid → void)\n- Recurring billing via `duplicate`\n\nExplicitly out of scope:\n\n- Double-entry bookkeeping\n- Bills payable / accounts payable\n- Bank reconciliation\n- GST/VAT filing reports\n- Chart of accounts, P\u0026L, balance sheet\n- Payroll, inventory, expense tracking\n\nFor those, reach for Xero, Wave, or QuickBooks.\n\n## License\n\nMIT © 199 Biotechnologies\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Finvoice-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaperfoot%2Finvoice-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Finvoice-cli/lists"}