mf-cli

mf - MoneyForward 会計 / 請求書 CLI

マネーフォワード クラウド会計 と マネーフォワード クラウド請求書 のAPIを操作するコマンドラインツールです。

Note: リポジトリ名は mf-cli ですが、インストールされるバイナリ名は mf です。

特徴

• OAuth 2.0 + PKCE による認証
• 仕訳帳・勘定科目・取引先・部門・税区分などのCRUD操作（クラウド会計）
• 請求書の作成・更新・削除と取引先 / 部署 / 品目の参照（クラウド請求書）
• 試算表・推移表などの財務レポート取得
• JSON / テーブル形式での出力切替
• --dry-run による安全な事前確認
• --fields によるJSONフィールドフィルタリング
• 組み込みOpenAPIスキーマブラウザ（mf describe）
• AIエージェントとの連携に最適化されたJSON出力

インストール

go install

go install github.com/beatinaniwa/mf-cli@latest

バイナリダウンロード

GitHub Releases から各プラットフォーム向けのバイナリをダウンロードできます。

対応プラットフォーム: Linux / macOS / Windows（amd64 / arm64）

ソースからビルド

git clone https://github.com/beatinaniwa/mf-cli.git
cd mf-cli
make build  # ./mf が生成されます

クイックスタート

1. APIクレデンシャルの取得

マネーフォワード クラウド API でアプリケーションを登録し、クライアントIDを取得してください。

リダイレクトURIの登録が必要です:

http://127.0.0.1:8089/callback

MF_AUTH_PORT を変更する場合は、リダイレクトURIのポート番号も合わせて変更してください。

2. 環境変数の設定

export MF_CLIENT_ID=your_client_id
export MF_CLIENT_SECRET=your_client_secret  # 公開クライアントの場合は省略可

3. 認証

# ブラウザで認証（デフォルト）
mf auth login

# 書き込み権限も含める場合（クラウド請求書APIを使う場合は必須）
mf auth login --scopes all

# ブラウザを使わずに認証（SSHセッション等）
mf auth login --no-browser

# 認証状態の確認
mf auth status

4. 基本的な使い方

# 事業所情報を表示
mf office

# 勘定科目一覧をテーブル形式で表示
mf accounts --format table

# 仕訳帳を取得
mf journals list --start-date 2025-01-01 --end-date 2025-03-31

# 仕訳を新規作成（dry-run で事前確認）
mf journals create --json '{"..."}' --dry-run

# 試算表（P/L）を取得
mf reports trial-balance-pl --fiscal-year 2024

# APIスキーマを確認（会計）
mf describe --list          # 利用可能なリソース一覧
mf describe journals        # journals の詳細

# 請求書APIスキーマを確認
mf describe --api invoice --list
mf describe --api invoice invoices

# 請求書ドラフトを作成（dry-run で事前確認）
mf invoices create --dry-run --json '{"department_id":"...","billing_date":"2026-05-08","title":"請求書","items":[{"name":"作業費","price":10000,"quantity":1,"excise":"ten_percent"}]}'

# 請求書一覧
mf invoices list --per-page 5

# 取引先・部署・品目の参照
mf invoice-partners list
mf invoice-departments list --partner-id <partner_id>
mf invoice-items list

コマンド一覧

入出力

出力形式

# JSON出力（デフォルト）
mf accounts

# テーブル出力（対応コマンドのみ）
mf accounts --format table

# 特定フィールドのみ出力（JSONモードのみ有効）
mf accounts --fields id,display_name

# デバッグ出力（HTTPリクエスト/レスポンス詳細）
mf accounts --debug

--fields はJSON出力時のみフィルタリングが適用されます。テーブルモードでは無視されます。 reports trial-balance-pl は --fields 指定時、テーブルの代わりにJSON出力にフォールバックします。

JSON入力

書き込みコマンドでは --json フラグでリクエストボディを指定します。

# 直接指定
mf journals create --json '{"description": "test"}'

# 標準入力から読み込み
cat request.json | mf journals create --json -

dry-run

書き込みコマンドでは --dry-run で実行前にリクエスト内容を確認できます。

mf journals create --json '{"..."}' --dry-run

設定

環境変数

環境変数は設定ファイルの値を上書きします。

設定ファイル

設定ファイルの保存場所は XDG Base Directory に準拠します:

config.json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "base_url": "https://api-accounting.moneyforward.com",
  "invoice_base_url": "https://invoice.moneyforward.com",
  "auth_port": 8089
}

invoice_base_url は origin のみを指定してください（末尾の /api/v3 は不要）。/api/v3 付きで設定された場合や末尾スラッシュは自動でトリムされ、それ以外の不正値は invoice 系コマンド実行時にエラーになります。

token.json

認証トークンは同ディレクトリ内の token.json に自動保存されます。

AIエージェント向け

mf-cli はAIエージェント（Claude Code、Codex等）からの利用に適した設計です。

• リソースコマンド（accounts, journals, reports 等）と auth status はデフォルトでJSON出力
• auth login/logout、version は平文出力
• --fields でJSON出力から必要なフィールドのみ抽出可能
• --dry-run で安全にリクエスト内容を事前確認
• --json - で標準入力からJSONを渡せる
• エラーは構造化JSONとしてstderrに出力（cobra/pflagの未定義フラグや型不正のみ平文で stderr に出力されます）
• 請求書APIを使うには mf auth login --scopes all で再認可が必要です（MF_SCOPES を設定中の場合は unset MF_SCOPES してから実行してください）

開発

make build      # バイナリをビルド
make test       # テスト実行（-race付き）
make lint       # golangci-lint実行
make coverage   # カバレッジレポート
make clean      # 成果物を削除

詳細は CONTRIBUTING.md を参照してください。

ライセンス

MIT License