finance-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

finance-cli

Personal finance management from the terminal. Track accounts, transactions, budgets, savings goals, and generate reports. Designed for both human use and AI agent operation.

一款可在终端使用的个人财务管理工具。支持追踪账户、交易记录、预算、储蓄目标，并生成报表。同时适配人工操作与AI Agent运行。

Quick Start

快速开始

bash

undefined

bash

undefined

Install and verify

安装并验证版本

npx finance-cli --version

Check database status

检查数据库状态

npx finance-cli status --json

undefined

npx finance-cli status --json

undefined

Global Flags

全局参数

Flag	Description
`--json`	Output structured JSON instead of human-readable tables
`--db-path <path>`	Use a specific SQLite database file (default: `~/.finance-cli/finance.db` )

Environment variable

FINANCE_CLI_DB

can also set the database path.

参数	说明
`--json`	输出结构化JSON数据，而非易读的表格形式
`--db-path <path>`	使用指定的SQLite数据库文件（默认路径： `~/.finance-cli/finance.db` ）

也可通过环境变量

FINANCE_CLI_DB

设置数据库路径。

JSON Response Envelope

JSON响应格式

All

--json

responses follow this structure:

json

{
  "status": "success",
  "data": { ... },
  "message": "Human-readable description"
}

On error:

json

{
  "status": "error",
  "message": "What went wrong"
}

Important: All monetary amounts in JSON are stored as integer cents (e.g.,

= $1,500.00). Divide by 100 for display.

所有带

--json

参数的响应均遵循以下结构：

json

{
  "status": "success",
  "data": { ... },
  "message": "Human-readable description"
}

错误时的响应：

json

{
  "status": "error",
  "message": "What went wrong"
}

重要提示：JSON中的所有金额均以整数分存储（例如：

= 1500.00美元）。如需显示为元，需除以100。

Commands Overview

命令概览

Command	Alias	Description
`account create`	`acc create`	Create a new account (bank, cash, credit)
`account list`	`acc list`	List all accounts with balances
`account edit <id>`	`acc edit`	Edit account name or type
`account delete <id>`	`acc delete`	Delete an account
`account balance <id>`	`acc balance`	Show computed balance for an account
`account transfer`	`acc transfer`	Transfer between accounts
`category create`	`cat create`	Create a spending category
`category list`	`cat list`	List all categories
`category edit <id>`	`cat edit`	Edit a category name
`category delete <id>`	`cat delete`	Delete a category
`transaction add`	`tx add`	Add income or expense transaction
`transaction list`	`tx list`	List transactions with filters
`transaction edit <id>`	`tx edit`	Edit a transaction
`transaction delete <id>`	`tx delete`	Delete a transaction
`budget set`		Set monthly budget for a category
`budget status`		Show budget vs actual spending
`budget compare`		Compare budget vs actual (detailed)
`budget list`		List all budgets
`budget delete`		Delete a budget
`goal create`		Create a savings goal
`goal list`		List all goals with progress
`goal status <id>`		Detailed goal status
`goal contribute <id>`		Contribute to a goal (creates real transaction)
`goal edit <id>`		Edit a savings goal
`goal delete <id>`		Delete a savings goal
`recurring create`	`rec create`	Create a recurring transaction
`recurring list`	`rec list`	List recurring transactions
`recurring edit <id>`	`rec edit`	Edit a recurring transaction
`recurring delete <id>`	`rec delete`	Delete a recurring transaction
`recurring process`	`rec process`	Process all due recurring transactions
`report summary`		Monthly financial summary
`report categories`		Category spending breakdown
`report balances`		All account balances overview
`import csv`		Import transactions from CSV file
`export csv`		Export transactions to CSV
`export json`		Export all data as structured JSON
`backup create`		Create SQLite database backup
`backup restore`		Restore database from backup
`status`		Show CLI and database status

命令	别名	说明
`account create`	`acc create`	创建新账户（银行账户、现金账户、信用卡账户）
`account list`	`acc list`	列出所有账户及余额
`account edit <id>`	`acc edit`	编辑账户名称或类型
`account delete <id>`	`acc delete`	删除账户
`account balance <id>`	`acc balance`	显示指定账户的结算余额
`account transfer`	`acc transfer`	账户间转账
`category create`	`cat create`	创建支出分类
`category list`	`cat list`	列出所有分类
`category edit <id>`	`cat edit`	编辑分类名称
`category delete <id>`	`cat delete`	删除分类
`transaction add`	`tx add`	添加收入或支出交易记录
`transaction list`	`tx list`	按筛选条件列出交易记录
`transaction edit <id>`	`tx edit`	编辑交易记录
`transaction delete <id>`	`tx delete`	删除交易记录
`budget set`		设置分类月度预算
`budget status`		显示预算与实际支出对比
`budget compare`		详细对比预算与实际支出
`budget list`		列出所有预算
`budget delete`		删除预算
`goal create`		创建储蓄目标
`goal list`		列出所有储蓄目标及进度
`goal status <id>`		查看储蓄目标的详细状态
`goal contribute <id>`		向储蓄目标缴款（会创建真实交易记录）
`goal edit <id>`		编辑储蓄目标
`goal delete <id>`		删除储蓄目标
`recurring create`	`rec create`	创建定期交易记录
`recurring list`	`rec list`	列出所有定期交易记录
`recurring edit <id>`	`rec edit`	编辑定期交易记录
`recurring delete <id>`	`rec delete`	删除定期交易记录
`recurring process`	`rec process`	处理所有到期的定期交易记录
`report summary`		月度财务汇总报表
`report categories`		支出分类明细报表
`report balances`		全账户余额概览
`import csv`		从CSV文件导入交易记录
`export csv`		将交易记录导出为CSV文件
`export json`		将所有数据导出为结构化JSON
`backup create`		创建SQLite数据库备份
`backup restore`		从备份恢复数据库
`status`		查看CLI及数据库状态

Common Workflows

常见工作流

1. Set Up Accounts and Track First Expense

1. 创建账户并记录首笔支出

bash

undefined

bash

undefined

Create a checking account

创建支票账户

npx finance-cli account create --name "Checking" --type bank --balance 2500.00 --json

Create a spending category

创建支出分类

npx finance-cli category create --name "Groceries" --json

Record an expense (use account ID and category ID from above)

记录一笔支出（使用上述步骤得到的账户ID和分类ID）

npx finance-cli transaction add --type expense --amount 45.50 --account 1 --category 1 --note "Weekly groceries" --json

undefined

npx finance-cli transaction add --type expense --amount 45.50 --account 1 --category 1 --note "Weekly groceries" --json

undefined

2. Monthly Budget Check

2. 月度预算检查

bash

undefined

bash

undefined

Set a budget for a category

设置分类预算

npx finance-cli budget set --category 1 --limit 500.00 --month 2026-03 --json

Check budget status

查看预算状态

npx finance-cli budget status --month 2026-03 --json

Get full monthly summary

获取完整月度汇总

npx finance-cli report summary --month 2026-03 --json

undefined

npx finance-cli report summary --month 2026-03 --json

undefined

3. Import Bank Data

3. 导入银行数据

bash

undefined

bash

undefined

Preview import (dry run)

预览导入（试运行）

npx finance-cli import csv --file bank-export.csv --date-col 0 --amount-col 2 --note-col 1 --default-account 1 --dry-run --json

Execute import

执行导入

npx finance-cli import csv --file bank-export.csv --date-col 0 --amount-col 2 --note-col 1 --default-account 1 --json

undefined

npx finance-cli import csv --file bank-export.csv --date-col 0 --amount-col 2 --note-col 1 --default-account 1 --json

undefined

4. Savings Goal Tracking

4. 储蓄目标追踪

bash

undefined

bash

undefined

Create a savings goal linked to an account

创建关联账户的储蓄目标

npx finance-cli goal create --name "Emergency Fund" --target 10000.00 --deadline 2026-12-31 --account 2 --json

Contribute to goal (creates a real expense transaction)

向储蓄目标缴款（创建真实支出交易记录）

npx finance-cli goal contribute 1 --amount 500.00 --json

Check progress

查看进度

npx finance-cli goal status 1 --json

undefined

npx finance-cli goal status 1 --json

undefined

Reference

参考文档

For full parameter details, JSON response schemas, and all flag options for every command, see references/commands.md.

如需了解所有命令的完整参数说明、JSON响应格式及全部参数选项，请查看references/commands.md。