Firefly III CLI

CLI-Anything仕様に基づいたFirefly IIIコマンドラインインターフェース。MCPモードをステートレスなCLIモードに変換し、Nodeの残留プロセスの問題を回避します。

インストール

pip install cli-anything-firefly-iii

前提条件

• Python 3.10以上
• 実行中のFirefly IIIインスタンス
• Personal Access Token (PAT)

設定

環境変数（推奨）

export FIREFLY_III_BASE_URL="https://firefly.yourdomain.com"
export FIREFLY_III_PAT="your-personal-access-token"

コマンドライン引数

cli-anything-firefly-iii --base-url https://firefly.yourdomain.com --pat your-token

コマンドグループ

コマンドグループ	説明	対応API
accounts	アカウント管理	/api/v1/accounts
transactions	トランザクション管理	/api/v1/transactions
budgets	予算管理	/api/v1/budgets
categories	カテゴリ管理	/api/v1/categories
tags	タグ管理	/api/v1/tags
bills	請求書管理	/api/v1/bills
piggy-banks	貯金箱	/api/v1/piggy-banks
insights	インサイトとレポート	/api/v1/insight/*
search	検索	/api/v1/search/*
export	データエクスポート	/api/v1/data/export/*
info	システム情報	/api/v1/about

使用例

アカウント管理

# すべてのアカウントをリスト表示
cli-anything-firefly-iii --json accounts list

# 資産アカウントをリスト表示
cli-anything-firefly-iii --json accounts list --type asset

# アカウント詳細を取得
cli-anything-firefly-iii --json accounts get --id 123

# アカウントを作成
cli-anything-firefly-iii --json accounts create --name "Cash" --type asset --currency-code USD

# アカウントを削除
cli-anything-firefly-iii accounts delete --id 123

トランザクション管理

# トランザクションをリスト表示
cli-anything-firefly-iii --json transactions list --limit 10

# トランザクションを作成
cli-anything-firefly-iii --json transactions create \
  --description "Grocery" \
  --amount 50.00 \
  --source-account 1 \
  --category "Food"

# トランザクション詳細を取得
cli-anything-firefly-iii --json transactions get --id 456

# トランザクションを削除
cli-anything-firefly-iii transactions delete --id 456

インサイトとレポート

# 支出レポート（カテゴリ別）
cli-anything-firefly-iii --json insights expense \
  --start 2024-01-01 \
  --end 2024-01-31 \
  --group-by category

# 収入レポート
cli-anything-firefly-iii --json insights income \
  --start 2024-01-01 \
  --end 2024-01-31

# アカウント概要
cli-anything-firefly-iii --json insights overview \
  --start 2024-01-01 \
  --end 2024-01-31

検索

# トランザクションを検索
cli-anything-firefly-iii --json search transactions --query "grocery"

データエクスポート

# トランザクションをエクスポート
cli-anything-firefly-iii --json export transactions \
  --start 2024-01-01 \
  --end 2024-01-31

# アカウントをエクスポート
cli-anything-firefly-iii --json export accounts

システム情報

# システム情報
cli-anything-firefly-iii --json info about

# 接続ステータス
cli-anything-firefly-iii info status

プリセットフィルタリング

--presetパラメータを使用して利用可能なコマンドをフィルタリングします：

# デフォルトプリセット
cli-anything-firefly-iii --preset default accounts list

# フルプリセット
cli-anything-firefly-iii --preset full accounts list

# 予算プリセット
cli-anything-firefly-iii --preset budget budgets list

# レポートプリセット
cli-anything-firefly-iii --preset reporting insights expense --start 2024-01-01 --end 2024-01-31

利用可能なプリセット：

• default: コア機能（accounts、transactions、categories、tags、bills、search）
• full: すべての機能
• basic: 基本機能（accounts、transactions、categories、tags、search）
• budget: 予算関連（accounts、budgets、transactions、summary、insight）
• reporting: レポート関連（accounts、transactions、categories、insight、summary、search）
• admin: 管理機能（about、configuration、currencies、users、preferences）
• automation: オートメーション（rules、recurrences、webhooks、transactions）

エージェントガイドライン

基本的な使用方法

1. 構造化された出力には--jsonを使用: すべてのコマンドが--jsonフラグをサポートし、JSON形式のデータを返します
2. 操作実行前にinfo statusを呼び出して接続を確認: Firefly IIIへの接続が正常であることを確認してから操作を実行します
3. プリセットを使用してコマンド数を削減: --presetで不要なコマンドをフィルタリングします

一般的なワークフロー

アカウント残高を表示

# 1. 接続を確認
cli-anything-firefly-iii info status

# 2. 資産アカウントをリスト表示
cli-anything-firefly-iii --json accounts list --type asset

# 3. アカウント詳細を表示（残高を取得）
cli-anything-firefly-iii --json accounts get --id <account_id>

支出を記録

# 1. 支出アカウントを検索
cli-anything-firefly-iii --json accounts list --type expense

# 2. トランザクションを作成
cli-anything-firefly-iii --json transactions create \
  --description "Lunch" \
  --amount 15.50 \
  --source-account <asset_account_id> \
  --destination-account <expense_account_id> \
  --category "Food"

月次レポート

# 1. 支出レポート
cli-anything-firefly-iii --json insights expense \
  --start 2024-01-01 \
  --end 2024-01-31 \
  --group-by category

# 2. 収入レポート
cli-anything-firefly-iii --json insights income \
  --start 2024-01-01 \
  --end 2024-01-31

# 3. データをエクスポート
cli-anything-firefly-iii --json export transactions \
  --start 2024-01-01 \
  --end 2024-01-31

エラーハンドリング

一般的なエラーとその解決方法：

1. 接続失敗: FIREFLY_III_BASE_URLが正しいか確認してください
2. 認証失敗: FIREFLY_III_PATが有効か確認してください
3. リソースが見つからない: IDが正しいか確認してください
4. パラメータエラー: 必須パラメータが提供されているか確認してください

ベストプラクティス

1. 認証情報には環境変数を使用: コマンドラインでPATを公開しないようにしてください
2. スクリプト作成には--jsonを使用: 出力の解析と処理が容易になります
3. プリセットを使用して権限を制御: シナリオに応じた適切なプリセットを選択してください
4. 修正前にクエリを実行: 誤った操作を回避してください

トラブルシューティング

接続の問題

Error: Cannot connect to Firefly III instance

• Firefly IIIインスタンスが実行中か確認してください
• ネットワーク接続を確認してください
• ベースURLが正しいか確認してください

認証の問題

Error: Authentication failed: Personal Access Token is invalid

• PATが正しいか確認してください
• Firefly III Options > Profile > OAuthで新しいPATを生成してください
• PATの有効期限が切れていないか確認してください

MCP版との比較

機能	MCP版	CLI-Anything版
プロセスライフサイクル	長時間実行	単一呼び出し、即座に終了
メモリ使用量	継続的	オンデマンド、終了後に解放
通信方法	Stdio/SSE	コマンド引数 + stdout
状態管理	ステートフル	ステートレス
プリセットフィルタリング	サポート	サポート
JSON出力	組み込み	--jsonフラグ

ライセンス

MIT License