Command Reference

Every fscl command with flags and output columns.

Entity resolution: Commands that accept account, category, or category group IDs also accept names. The CLI resolves names to IDs using exact case-insensitive matching. Example: fscl month set 2026-02 "Groceries" 500.00.

Global Options

Connection and auth resolution

server_url is resolved in order (first wins):

1. CLI flag (--server-url)
2. Environment variable (FISCAL_SERVER_URL)
3. Config file (~/.config/fiscal/config.json)

Authentication uses a session token saved by fscl login (config.token). If a server is configured and no valid token is available, commands return:

{ "status": "err", "message": "Not logged in. Run 'fscl login' to authenticate.", "code": "not-logged-in" }

Output format

Default: human-readable tables. --json for machine-readable output. Agents should always use --json.

Amounts in output: integer cents (-4599 = -$45.99). Amounts in input: decimal notation (--amount -45.99).

Row responses (list, query, report commands):

{ "status": "ok", "entity": "accounts", "count": 2, "data": [...] }

Mutation responses (create, update, delete — always JSON regardless of --json flag):

{ "status": "ok", "entity": "account", "action": "create", "id": "a1b2c3" }

Errors:

{ "status": "err", "message": "No budget selected." }

Validation errors include an errors array with path and message per item.

init

fscl init [--non-interactive --mode <local|remote>]

Modes: local (disk-only), remote (pull from server). Use budgets push to upload a local budget. On success, prints fscl status output.

When init is launched through npx fscl init, interactive mode asks whether to install fscl globally (npm install -g fscl) so the fscl command is available afterward.

Interactive fscl init also asks whether to install the Fiscal agent skill by running npx skills add fiscal-sh/fscl.

status

fscl status [--compact]

Shows: budget name/ID, server connectivity, entity counts, uncategorized count, transaction date range.

sync

fscl sync

Write commands auto-sync when a server is configured. Use for explicit manual sync.

login

fscl login [server-url] [--password <pw>]

Authenticates with the Actual server and stores serverURL + token in config. If --password is omitted in a TTY, fscl prompts securely.

Server URL resolution:

1. Positional arg ([server-url])
2. FISCAL_SERVER_URL
3. Config serverURL

logout

fscl logout

Clears stored serverURL and token.

budgets

budgets create options:

Remote operations require a valid login token (fscl login).

accounts

Output columns: id, name, offbudget, closed, balance_current

transactions

Output columns: id, date, account, account_name, amount, payee, payee_name, category, category_name, notes, cleared, reconciled, transfer_id, imported_id

categorize draft/apply

fscl transactions categorize draft [--account <id>] [--start] [--end] [--limit <n>] fscl transactions categorize apply [--dry-run]

Draft shape: [{ id, category, _meta: { date, amount, payeeName, accountName, notes } }]

Fill in category with category IDs. Apply output: id, category, result.

edit draft/apply

fscl transactions edit draft --account|--category|--start|--end [--limit <n>] (at least one filter required) fscl transactions edit apply [--dry-run]

Draft shape: [{ id, date, amount, payee, category, notes, cleared, account, _meta }]

Amounts are decimal strings. Apply output: id, fields, result.

Importing transactions

Supported formats: CSV/TSV, OFX/QFX, QIF, CAMT XML. Auto-detected from file extension.

General flags

Supported date formats: yyyy mm dd, yy mm dd, mm dd yyyy, mm dd yy, dd mm yyyy, dd mm yy.

--dry-run requires reconcile mode (default). Cannot combine with --no-reconcile.

OFX/QFX flags

CSV flags

CSV amount modes

Three ways to handle amounts:

1. Single signed column: --csv-amount-col "Amount"
2. Separate inflow/outflow: --csv-inflow-col "Credit" --csv-outflow-col "Debit"
3. Amount with in/out marker: --csv-amount-col "Amount" --csv-inout-col "Type" --csv-out-value "DR"

Import pipeline

Parse → Normalize (date format, multiplier, flip) → Reconcile (rules + dedup, skip with --no-reconcile) → Commit (skip with --dry-run)

month

month show columns: month, group_id, group_name, category_id, category_name, budgeted, spent, balance. Metadata: toBudget.

month status columns: above + remaining, percent_used, over_under, status, compare_months, prev_spent_avg, trend_delta.

month draft/apply

fscl month draft <month> fscl month apply <month> [--dry-run]

Draft shape: [{ categoryId, group, name, amount }]. Only categoryId and amount (decimal string) are used on apply.

month templates

categories

List columns: kind, id, group_id, name, is_income, hidden Find columns: kind, id, name, group_id, group_name, is_income, hidden

categories draft/apply

fscl categories draft fscl categories apply [--dry-run]

Draft shape: [{ id?, name, categories: [{ id?, name }] }]

Top-level entries are category groups. The categories array contains category entities. Categories do not nest inside other categories.

• id present + changed name -> rename
• category id moved under a different group -> reassign
• missing id -> create
• rows removed from draft are ignored (no deletion)

payees

Output columns: id, name, transfer_acct

rules

List columns: id, stage, conditions_op, conditions, actions Run columns: id, date, account, account_name, amount, payee_before, payee_before_name, payee_after, payee_after_name, notes, category_before, category_before_name, category_after, category_after_name, matched_rule

See rules.md for JSON schema, stages, conditions, and actions.

schedules

List columns: id, name, posts_transaction, next_date, amount, amount_op, account, account_name, payee, payee_name, date Upcoming adds: days_until. Missed adds: days_overdue. Summary columns: id, name, payee_name, account_name, amount, frequency, interval, monthly_amount, annual_amount, next_date. Metadata: total_monthly, total_annual. Reviews columns: schedule_id, name, payee_name, amount, decision, reviewed_at, next_review_at, cadence_months, note, days_until_review

tags

query

Run custom ActualQL queries.

fscl query --module <path>       # Run a query module
fscl query --inline <expr>       # Run an inline expression

Use exactly one of --module or --inline. Module can export default (q) => query or a named query.

Draft/apply workflow

Six commands support draft/apply: categories, categorize, edit, rules, month, templates.

1. <command> draft [filters] — generates JSON at <dataDir>/<budgetId>/drafts/
2. Edit the JSON file
3. <command> apply --dry-run — preview changes
4. <command> apply — commit (deletes draft on success)

Never hand-create a draft file by path. Generate it with <command> draft, then edit that generated file.

Exit codes