mfk-usage

name	mfk-usage
description	Work with Money Forward Kessai (マネーフォワードケッサイ) through the mfk CLI — look up customers and credit examinations, fetch billings and invoices, check transactions, payouts and destinations. Use when the user asks about their MFK account, an invoice or 請求書 issued through Money Forward Kessai, a customer's credit line, or a payout.
license	MIT
compatibility	Requires the `mfk` binary on PATH — run the mfk-install skill if it is missing. Needs MFK_API_KEY (or MFK_SANDBOX_API_KEY with --sandbox). Operates on live billing and credit data for real customers; create and update methods have real financial consequences.
allowed-tools	Bash(mfk:*) Bash(jq:*) Bash(command:*) Read Write

mfk-usage

Drive the Money Forward Kessai API v2 through the mfk CLI. Every command has the shape mfk <resource> <method> [flags] and prints JSON by default.

1. Confirm the tool and the environment

command -v mfk && mfk --version

Missing? Run the mfk-install skill.

MFK_API_KEY must be set for production; --sandbox switches to the sandbox base URL and prefers MFK_SANDBOX_API_KEY. The environment is decided by --sandbox → MFK_ENV → production. Check which one you are about to hit before running anything that writes — the same command against production touches real customers.

2. The mistake that wastes the most time: billings

Money Forward Kessai split invoice retrieval in two when the Japanese invoice system (インボイス制度, 適格請求書等保存方式) started in October 2023:

Command	Returns	Period
mfk billings qualified	invoice-system billings	October 2023 onwards — current
mfk billings list	old-format (区分記載請求書) billings	roughly before October 2023

Use mfk billings qualified for anything current. If a user says "I can only get data up to 2023", the cause is almost always billings list being used instead of qualified. Both take the same query parameters and return the same Billing shape.

3. Paginate deliberately

Lists return the 20 most recent records by default, newest first. Without --page-all you are looking at a truncated view — which silently produces wrong totals.

mfk billings qualified --page-all | jq '.items | length'
mfk billings qualified --customer-id cust_xxx --page-all

--limit sets the page size (1–200). --page-all follows pagination.has_next internally and merges every page into {"items":[...]}.

4. Read the reference for anything else

mfk llm | head -60
mfk llm | grep -i 'customers'

Embedded in the binary (~520 lines), so it matches the installed version.

5. Treat writes as financial actions

Creating a customer, requesting a credit examination, issuing or reissuing a billing, and anything touching payouts affect a real business relationship and real money. Before any non-read method:

mfk <resource> <method> --json '{...}' --dry-run

--dry-run prints the request without sending it. Show the user what will be sent, to which customer, in which environment, and get their agreement. Then run it for real.

6. Report

Give back the identifiers (billing id, customer id) and the amounts and statuses that the user needs. When you paginated, say how many records the number covers and over what period.

Failure modes

Symptom	Cause	Fix
command not found: mfk	not installed	run the mfk-install skill
authentication errors	MFK_API_KEY unset or wrong environment	check the variable and whether --sandbox is intended
only pre-2023 invoices come back	used billings list	use mfk billings qualified
totals look too small	default 20-record page	add --page-all
unexpected write against production	--sandbox omitted	verify the environment before every write; use --dry-run first