Skip to content

Commit 10d3620

Browse files
thedavidwengthedavidweng
authored
Merge pull request #9 from thedavidweng/docs/add-command-schema-docs
docs: add COMMANDS.md, JSON_SCHEMA.md
2 parents 53af583 + 7bf7220 commit 10d3620

4 files changed

Lines changed: 415 additions & 0 deletions

File tree

‎COMMANDS.md‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
# Command Reference
2+
3+
All commands accept the [global flags](#global-flags) listed at the bottom.
4+
Use `money <command> --help` for full flag details.
5+
6+
## Top-level Commands
7+
8+
| Command | Description |
9+
|---------|-------------|
10+
| `version` | Show version and commit |
11+
| `doctor` | Check configuration, store, providers, and connectivity |
12+
| `setup` | Guided first-time setup (config, encryption key, database) |
13+
| `completion` | Generate shell completion scripts (bash, zsh, fish, powershell) |
14+
15+
```bash
16+
money version
17+
money version --json
18+
money doctor
19+
money doctor --json
20+
money setup
21+
money setup --json
22+
```
23+
24+
## auth / plaid
25+
26+
Manage Plaid credentials and dashboard authentication.
27+
28+
| Command | Usage | Description |
29+
|---------|-------|-------------|
30+
| `plaid login` | `money plaid login` | Interactive Plaid Dashboard OAuth login |
31+
| `plaid logout` | `money plaid logout` | Remove Dashboard auth (preserves API keys) |
32+
| `providers configure plaid` | `money providers configure plaid --client-id ... --secret ...` | Set Plaid API keys directly |
33+
| `providers plaid login` | `money providers plaid login` | Alias for `plaid login` |
34+
35+
```bash
36+
money plaid login --json
37+
money plaid logout --json
38+
money providers configure plaid --client-id CLIENT_ID --secret SECRET --environment sandbox --json
39+
```
40+
41+
## link
42+
43+
Link a financial institution via Plaid Link (browser flow).
44+
45+
| Command | Usage | Description |
46+
|---------|-------|-------------|
47+
| `link` | `money link "Chase"` | Open Plaid Link for an institution query |
48+
| `plaid sandbox link` | `money plaid sandbox link --products transactions --institution-id ins_56` | Create a sandbox link (no browser) |
49+
50+
**Key flags:**
51+
52+
- `--no-open` — don't auto-open browser
53+
- `--additional-consented-products` — extra Plaid products (comma-separated)
54+
- `--required-if-supported-products` — required products if supported
55+
- `--optional-products` — optional products
56+
57+
```bash
58+
money link "Chase" --json
59+
money plaid sandbox link --products transactions --institution-id ins_56
60+
```
61+
62+
## accounts
63+
64+
Read local account data.
65+
66+
| Command | Usage | Description |
67+
|---------|-------|-------------|
68+
| `accounts list` | `money accounts list` | List all financial accounts |
69+
70+
```bash
71+
money accounts list --json
72+
```
73+
74+
## accounts create-manual
75+
76+
Create a local manual account (not linked to a provider).
77+
78+
```bash
79+
money accounts create-manual --name Savings --type depository --balance 5000.00 --currency USD --confirm
80+
money accounts create-manual --name "Credit Card" --type credit --balance 500.00 --dry-run
81+
```
82+
83+
## transactions
84+
85+
Read and manage local transaction data.
86+
87+
| Command | Usage | Description |
88+
|---------|-------|-------------|
89+
| `transactions list` | `money transactions list` | List transactions with filters |
90+
| `transactions search` | `money transactions search <query>` | Search transactions by text |
91+
92+
**Filters for `transactions list`:**
93+
94+
- `--account` — filter by account
95+
- `--category` — filter by category
96+
- `--merchant` — filter by merchant
97+
- `--tag` — filter by tag
98+
- `--date-from` / `--date-to` — date range
99+
- `--needs-review true|false` — review status
100+
- `--pending true|false` — pending status
101+
- `--recurring true|false` — recurring status
102+
- `--removed exclude|include|only` — removed records
103+
- `--limit` / `--offset` — pagination
104+
105+
Sort order: `date DESC`, `pending DESC`, `id ASC`.
106+
107+
```bash
108+
money transactions list --json
109+
money transactions list --account acc_xxx --date-from 2024-01-01 --json
110+
money transactions search "coffee" --json
111+
```
112+
113+
## categories / tags / recurring
114+
115+
Read local category, tag, and recurring transaction data.
116+
117+
```bash
118+
money categories list --json
119+
money tags list --json
120+
money recurring list --json
121+
```
122+
123+
## sync
124+
125+
Refresh data from linked financial providers.
126+
127+
| Command | Usage | Description |
128+
|---------|-------|-------------|
129+
| `sync` | `money sync` | Sync all linked provider items |
130+
| `sync` | `money sync --provider plaid` | Sync one provider |
131+
| `sync` | `money sync --provider-item pi_xxx` | Sync one linked item |
132+
133+
**Key flags:**
134+
135+
- `--provider` — narrow to one provider
136+
- `--provider-item` — narrow to one linked item
137+
- `--verbose` — per-item status in human mode
138+
- `--start-date` / `--end-date` — backfill date range (YYYY-MM-DD)
139+
140+
```bash
141+
money sync --json
142+
money sync --provider plaid --json
143+
money sync --start-date 2024-01-01 --end-date 2024-03-01 --json
144+
```
145+
146+
## investments
147+
148+
Read local investment data.
149+
150+
```bash
151+
money investments holdings --json
152+
money investments securities --json
153+
```
154+
155+
## liabilities
156+
157+
Read local liability data.
158+
159+
```bash
160+
money liabilities list --json
161+
```
162+
163+
## items
164+
165+
Manage linked provider items.
166+
167+
| Command | Usage | Description |
168+
|---------|-------|-------------|
169+
| `items list` | `money items list` | List linked provider items |
170+
| `items get` | `money items get <id>` | Show one provider item |
171+
| `items rename` | `money items rename <id> "My Bank"` | Update alias |
172+
| `items remove` | `money items remove <id>` | Remove item and cascade-delete associated data |
173+
174+
```bash
175+
money items list --json
176+
money items get pi_xxx --json
177+
money items rename pi_xxx "My Bank" --json
178+
money items remove pi_xxx --json
179+
```
180+
181+
## demo
182+
183+
Run against a non-persistent demo environment with synthetic data.
184+
185+
```bash
186+
money demo accounts list --json
187+
money demo transactions list --json --merchant Coffee --pending true --limit 10
188+
money demo transactions search coffee --json --limit 5
189+
```
190+
191+
## cashflow
192+
193+
Show income and expenses over time.
194+
195+
```bash
196+
money cashflow --from 2024-01-01 --to 2024-12-31
197+
money cashflow --from 2024-01-01 --to 2024-12-31 --period yearly --json
198+
```
199+
200+
## net-worth
201+
202+
Show current net worth across all visible accounts.
203+
204+
```bash
205+
money net-worth
206+
money net-worth --json
207+
```
208+
209+
## budgets
210+
211+
Manage budgets.
212+
213+
```bash
214+
money budgets list --json
215+
money budgets create --name Groceries --period monthly --start-date 2024-01-01 --end-date 2024-12-31 --confirm
216+
money budgets get <id> --json
217+
money budgets delete <id>
218+
```
219+
220+
## rules
221+
222+
Manage auto-categorization rules.
223+
224+
```bash
225+
money rules list --json
226+
money rules create --name "Mark Uber" --condition-field merchant_name --condition-op contains --condition-value uber --action-type set_category --action-value transport --confirm
227+
money rules apply
228+
money rules delete <id>
229+
```
230+
231+
## budgets categories
232+
233+
Manage budget categories.
234+
235+
```bash
236+
money budgets categories create --budget-id <id> --name Groceries --limit 50000 --confirm
237+
money budgets categories delete <id>
238+
```
239+
240+
## import
241+
242+
Import accounts and transactions from external sources.
243+
244+
```bash
245+
money import monarch transactions.csv
246+
money import csv transactions.csv --dry-run
247+
money import monarch data.csv --batch-id 20240101 --confirm
248+
```
249+
250+
## feedback
251+
252+
Submit feedback.
253+
254+
```bash
255+
money feedback
256+
```
257+
258+
## Global Flags
259+
260+
| Flag | Default | Description |
261+
|------|---------|-------------|
262+
| `--config` | | Config file path |
263+
| `--profile` | `default` | Configuration profile |
264+
| `-j, --json` | `false` | JSON envelope to stdout |

‎JSON_SCHEMA.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# JSON Envelope Schema
2+
3+
All commands emit a standard JSON envelope when invoked with `--json`.
4+
The current schema version is `0.1`.
5+
6+
## Success Envelope
7+
8+
```json
9+
{
10+
"ok": true,
11+
"data": { ... },
12+
"meta": {
13+
"command": "transactions.list",
14+
"schema_version": "0.1",
15+
"generated_at": "2026-05-10T00:00:00Z",
16+
"pagination": {
17+
"limit": 50,
18+
"offset": 0,
19+
"has_more": false
20+
}
21+
},
22+
"warnings": [],
23+
"errors": []
24+
}
25+
```
26+
27+
### Fields
28+
29+
- `ok` — always `true` on success.
30+
- `data` — command-specific payload. Collections are object-wrapped: `data.accounts`, `data.transactions`, `data.categories`, `data.tags`, `data.recurring`.
31+
- `meta` — request metadata (always present).
32+
- `meta.command` — dot-separated command name.
33+
- `meta.schema_version` — semver string.
34+
- `meta.generated_at` — ISO 8601 timestamp.
35+
- `meta.demo` — `true` when running in demo mode.
36+
- `meta.pagination` — present on list commands (`limit`, `offset`, `has_more`, `total` when available).
37+
- `warnings` — array of structured warning objects with `code`, `message`, `category`.
38+
- `errors` — empty array on success.
39+
40+
## Error Envelope
41+
42+
```json
43+
{
44+
"ok": false,
45+
"data": { ... }, // omitted when empty (omitempty)
46+
"meta": {
47+
"command": "sync",
48+
"schema_version": "0.1",
49+
"generated_at": "2026-05-10T00:00:00Z"
50+
},
51+
"warnings": [],
52+
"errors": [
53+
{
54+
"code": "SYNC_PARTIAL_FAILURE",
55+
"message": "One or more provider items failed to sync",
56+
"category": "api",
57+
"retryable": true
58+
}
59+
]
60+
}
61+
```
62+
63+
### Error Fields
64+
65+
- `ok` — always `false` on error.
66+
- `errors` — array of error objects (supports multi-error envelopes for partial failures).
67+
- Each error: `code`, `message`, `category`, `retryable`.
68+
69+
## Error Taxonomy
70+
71+
Provider errors are classified as:
72+
73+
| Code | Category | Retryable | Description |
74+
|------|----------|-----------|-------------|
75+
| `missing_credentials` | auth | false | Provider credentials not configured |
76+
| `invalid_authorization` | auth | false | Provider rejected credentials |
77+
| `reconnect_required` | auth | false | Provider item needs re-linking |
78+
| `rate_limit` | network | true | Provider rate limit hit |
79+
| `network` | network | true | Network-level failure |
80+
| `unsupported_feature` | api | false | Provider doesn't support this operation |
81+
| `provider_api` | api | varies | Provider returned an error |
82+
| `validation` | validation | false | Input validation failed |
83+
| `internal` | internal | false | Internal error |
84+
85+
## Shared Error Codes
86+
87+
| Code | Category | Retryable | Exit Code | Meaning |
88+
|------|----------|-----------|-----------|---------|
89+
| `BASE_CONFIG_MISSING` | config | false | 3 | Config doesn't exist yet |
90+
| `NOT_LOGGED_IN` | auth | false | 3 | Dashboard auth required |
91+
| `TEAM_SELECTION_REQUIRED` | validation | false | 2 | Multiple teams, no selection |
92+
| `API_KEYS_FETCH_REQUIRED` | auth | true | 3 | Dashboard auth exists but API keys need fetching |
93+
| `DASHBOARD_TOKEN_REFRESH_FAILED` | auth | false | 3 | Refresh token expired |
94+
| `READ_ONLY_VIOLATION` | safety | false | 4 | Mutation blocked by read-only mode |
95+
| `CONFIRMATION_REQUIRED` | validation | false | 2 | JSON write without `--confirm` or `--dry-run` |
96+
| `CONFIRMATION_REQUIRED` | safety | false | 10 | Destructive op without `--confirm` (via requireConfirm) |
97+
| `SYNC_PARTIAL_FAILURE` | api | true | 6 | Some provider items failed |
98+
| `CONFIG_WRITE_FAILED` | config | false | 1 | Config/env file write failure |
99+
| `DB_BACKUP_FAILED` | safety | false | 1 | Pre-repair DB backup failure |
100+
101+
## Exit Codes
102+
103+
| Code | Meaning |
104+
|------|---------|
105+
| 0 | Success |
106+
| 1 | Internal or unclassified failure |
107+
| 2 | Invalid command arguments |
108+
| 3 | Authentication or provider authorization required |
109+
| 4 | Read-only violation |
110+
| 6 | Provider/API/schema/feature failure |
111+
| 7 | Validation failure |
112+
| 10 | Confirmation required |
113+
114+
## Schema Versioning
115+
116+
- **Major** — breaking contract changes.
117+
- **Minor** — additive compatible fields.
118+
- **Patch** — implementation-only changes (no schema change).

0 commit comments

Comments
 (0)