| name | koban |
| description | Read and write Invoice Ninja billing data (clients, invoices, quotes, payments, products, expenses, projects, and more) from the terminal with the koban CLI. Use this whenever the user wants to look up, create, update, send, or report on Invoice Ninja records, or script accounting workflows that need stable JSON output. |
| allowed-tools | Bash(koban:*) |
| license | MIT |
| metadata | {"openclaw":{"emoji":"🧾","requires":{"bins":["koban"]}}} |
koban — Invoice Ninja CLI
koban is a command-line client for the Invoice Ninja API, built for humans and AI agents. It emits stable JSON for agents and readable tables for humans.
Quick reference
koban auth status
koban clients list --output json
koban invoices list --filter client_status=unpaid --output json
koban invoices show <id> --output json
koban invoices create --client-id <id> --line-item product_key=Consulting,quantity=1,cost=100 --dry-run
koban invoices create --client-id <id> --line-item product_key=Consulting,quantity=1,cost=100 --yes
koban payments list --output json
koban reports run --endpoint reports/invoices --dry-run
koban skill install
koban skill install --project
koban skill list
When to use this skill
Use koban whenever the user's work should be reflected in Invoice Ninja:
- look up clients, invoices, quotes, payments, products, expenses, projects, tasks, and related records;
- log billable work as tasks and time entries when you finish a unit of work;
- draft, update, and send invoices or quotes;
- record expenses and connect them to clients or projects;
- report on outstanding balances, payments, and quote/invoice status.
Prefer --output json for agent workflows so results can be parsed reliably.
Auth and setup
koban needs an Invoice Ninja API token. Either:
- run
koban auth login once, optionally with --keychain, or
- set
INVOICE_NINJA_API_TOKEN and optional INVOICE_NINJA_BASE_URL in the environment.
Environment variables always win over stored credentials. Confirm the active source with koban auth status; it never prints the token.
If koban is not on PATH, install it with the repository installer:
curl -fsSL https://raw.githubusercontent.com/jamesbrink/koban/main/install.sh | sh
It is also available as cargo install koban-cli and as prebuilt binaries on GitHub releases.
Safety rules
Mutating or externally visible commands require an explicit confirmation gate:
- Preview with
--dry-run and inspect the JSON request.
- Execute only after the preview is correct by re-running with
--yes.
Read-only commands do not need confirmation, including list, show, template, edit-template, statics, auth status, and safe utility endpoints such as ping and health_check.
search, reports, and charts POST to Invoice Ninja, so koban treats their runners as mutations. Use --dry-run first, then --yes only when execution is intended.
Filters and status pitfalls
--filter key=value is forwarded to Invoice Ninja. Unknown filter keys and values are silently ignored and can return the full unfiltered set, so always sanity-check row counts.
- Outstanding invoices: use
--filter client_status=unpaid, optionally with overdue; do not use outstanding.
- "Outstanding balance" means
balance > 0; confirm by summing .data[].balance with jq.
- List rows carry numeric
status_id values that are not in statics.
Invoice status_id values:
| status_id | meaning |
|---|
| 1 | draft |
| 2 | sent |
| 3 | partial |
| 4 | paid |
| 5 | cancelled |
| 6 | reversed |
Quotes, purchase orders, and other documents use their own status codes; verify against actual data.
Common commands
koban statics — reference data such as countries, currencies, and statuseskoban clients — list, show, and inspect clientskoban invoices — list, show, create, update, and manage invoiceskoban payments — list, show, and inspect paymentskoban quotes — list, show, and inspect quoteskoban credits — list, show, and inspect creditskoban vendors — list, show, and inspect vendorskoban expenses — list, show, and inspect expenseskoban projects — list, show, and inspect projectskoban tasks — list, show, and inspect taskskoban products — list, show, and manage productskoban reports — query reports with confirmation gateskoban charts — query charts with confirmation gateskoban search — search across Invoice Ninja records with confirmation gateskoban utility — utility endpoints such as ping, health-check, refresh, and previewkoban auth — store, inspect, and remove credentialskoban skill — install, list, show, and uninstall this agent skillkoban update — check or install GitHub release updates
Run koban --help or koban <command> --help for the full command surface and flags.
Skill management
The koban binary embeds this SKILL.md and can install it where supported agents look:
koban skill install
koban skill install --project
koban skill install claude codex
koban skill install --all
koban skill install copilot --dir ~/repo
koban skill list
koban skill show
koban skill uninstall --project
Supported agent names: claude, codex, pi, openclaw, copilot, cursor, gemini, amp, goose, and agents. Explicit project installs for openclaw use the repository skills/koban/SKILL.md workspace path.
Install overwrites only koban/SKILL.md in the target skill directory and never touches sibling files. Uninstall removes only that file and removes the now-empty koban/ directory when possible.
Agent patterns
Always ask for JSON when reading data:
koban clients list --output json | jq '.data[] | {id, name}'
koban invoices list --filter client_status=unpaid --output json | jq '[.data[].balance] | add'
For writes, preview first:
koban invoices update <invoice_id> --public-notes "Thanks!" --dry-run
koban invoices update <invoice_id> --public-notes "Thanks!" --yes
Do not print, log, or store API tokens. Redact credentials from errors, traces, fixtures, and docs.
