@hisaabo/cli 0.6.1 → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/LICENSE +31 -0
  2. package/README.md +9 -0
  3. package/dist/bin/{audit-trail-4AMEFQGB.js → audit-trail-IJ6SKACR.js} +3 -3
  4. package/dist/bin/{categories-CLCBRNWC.js → categories-O6TODPAH.js} +2 -2
  5. package/dist/bin/{check-slug-OKW7KDYG.js → check-slug-P7RFU6OP.js} +2 -2
  6. package/dist/bin/chunk-NO4FIFMS.js +0 -0
  7. package/dist/bin/{chunk-FIMJZAS4.js → chunk-QUITS2FE.js} +46 -1
  8. package/dist/bin/{chunk-GXRLFDZW.js → chunk-WDN7RIE3.js} +32 -2
  9. package/dist/bin/{chunk-T63VQXNM.js → chunk-ZPYC767N.js} +1 -0
  10. package/dist/bin/{client-2ZKMLWI6.js → client-36JX5MR3.js} +1 -1
  11. package/dist/bin/{collection-efficiency-TECE6PVQ.js → collection-efficiency-DA5RWG3V.js} +3 -3
  12. package/dist/bin/{config-335MN4I7.js → config-4LLNT4SH.js} +5 -1
  13. package/dist/bin/{create-AS2YVGRA.js → create-C5INBPQO.js} +2 -2
  14. package/dist/bin/{default-account-3RVSU7RF.js → default-account-2GMQ7ZA4.js} +2 -2
  15. package/dist/bin/{expenses-KXFQJKD6.js → expenses-S2YVA5UT.js} +3 -3
  16. package/dist/bin/{export-UHZISG7H.js → export-YOOODNVX.js} +2 -2
  17. package/dist/bin/export-ZA43MLWO.js +191 -0
  18. package/dist/bin/{factory-OBESY2LG.js → factory-6MUCSXTL.js} +3 -3
  19. package/dist/bin/{get-WUSYEMG4.js → get-GMQRROK2.js} +2 -2
  20. package/dist/bin/{get-GTL556HL.js → get-ZV3SC2VY.js} +3 -3
  21. package/dist/bin/hisaabo.js +107 -59
  22. package/dist/bin/import-UUHMLCKX.js +267 -0
  23. package/dist/bin/{invitations-U4ZNYWY7.js → invitations-OVORTTMF.js} +2 -2
  24. package/dist/bin/{invite-5S4GJKRF.js → invite-GGHBZY4U.js} +2 -2
  25. package/dist/bin/{invoice-breakdown-PP3BZQLG.js → invoice-breakdown-32XXAZDP.js} +3 -3
  26. package/dist/bin/{items-CHEFLI7C.js → items-6NOIMH6B.js} +3 -3
  27. package/dist/bin/{items-toggle-ETVCDCU6.js → items-toggle-L6W6QKQD.js} +2 -2
  28. package/dist/bin/{list-3FO4UJKC.js → list-FC5JHKHD.js} +3 -3
  29. package/dist/bin/{list-RJ34MFPR.js → list-OXAVDXH7.js} +2 -2
  30. package/dist/bin/{list-LQJGTZB4.js → list-RAR56EMQ.js} +2 -2
  31. package/dist/bin/{members-TE5K5NQC.js → members-Y6XJVHHR.js} +3 -3
  32. package/dist/bin/{monthly-comparison-Q6KPMTPS.js → monthly-comparison-IAUZ6SBJ.js} +3 -3
  33. package/dist/bin/{order-cancel-NOQDBL2N.js → order-cancel-QRTCNART.js} +2 -2
  34. package/dist/bin/{order-confirm-6WMKTGPV.js → order-confirm-LGQOMC4O.js} +2 -2
  35. package/dist/bin/{order-get-ONWR4GTW.js → order-get-4XAQCRYV.js} +3 -3
  36. package/dist/bin/{order-update-IVO4AFGV.js → order-update-KZY4H2UR.js} +3 -3
  37. package/dist/bin/output-NUOL7KJW.js +0 -0
  38. package/dist/bin/{payment-modes-FXB2G6WP.js → payment-modes-DY2ZEMK7.js} +3 -3
  39. package/dist/bin/{profit-loss-XPYELDTH.js → profit-loss-5GJBG3PL.js} +3 -3
  40. package/dist/bin/{receivables-aging-MU6Q3DZ4.js → receivables-aging-6A7XJKDT.js} +3 -3
  41. package/dist/bin/{remove-DJBOOOR4.js → remove-ZBX34TIQ.js} +2 -2
  42. package/dist/bin/{revoke-WRIK7HLY.js → revoke-XDNOA2GJ.js} +2 -2
  43. package/dist/bin/{revoke-5L5GZ4ZZ.js → revoke-ZTAMW2Q2.js} +2 -2
  44. package/dist/bin/{revoke-all-QARW2G6R.js → revoke-all-365NRBOA.js} +2 -2
  45. package/dist/bin/{revoke-invitation-ZGLJHYNB.js → revoke-invitation-PQH7XNYA.js} +2 -2
  46. package/dist/bin/{sales-trend-P5HOZJSX.js → sales-trend-D6PQ7MHY.js} +3 -3
  47. package/dist/bin/{sequence-LK6QLSI5.js → sequence-KZWADVD7.js} +2 -2
  48. package/dist/bin/{store-FU7CEILC.js → store-SVRZBUFO.js} +3 -3
  49. package/dist/bin/{summary-XONLN72I.js → summary-H6U7O5GJ.js} +3 -3
  50. package/dist/bin/{top-customers-U6HQW2GH.js → top-customers-ATBN6RDI.js} +3 -3
  51. package/dist/bin/{top-items-EAOIVZ4P.js → top-items-XXU6KYTC.js} +3 -3
  52. package/dist/bin/{top-outstanding-4546FJDH.js → top-outstanding-JTQNGGW4.js} +3 -3
  53. package/dist/bin/{unpaid-invoices-AED55PLC.js → unpaid-invoices-BTNQFWCH.js} +3 -3
  54. package/dist/bin/{untracked-ZEM2CDHC.js → untracked-PAMEDJ6Y.js} +3 -3
  55. package/dist/bin/{update-FO7AAXF5.js → update-6ZMX2OYX.js} +3 -3
  56. package/dist/bin/{update-OZPBIBME.js → update-EGHPFXLK.js} +2 -2
  57. package/dist/bin/{update-QCK32XAG.js → update-EK4NJWU4.js} +3 -3
  58. package/dist/bin/{update-role-RB35QIA5.js → update-role-24PDTNFK.js} +2 -2
  59. package/dist/bin/{update-settings-EUC2FJQJ.js → update-settings-AASI6WZX.js} +2 -2
  60. package/package.json +35 -9
  61. package/.turbo/turbo-build.log +0 -13
  62. package/.turbo/turbo-typecheck.log +0 -4
  63. package/CLI-UX-ARCHITECTURE.md +0 -1269
  64. package/src/auth.ts +0 -221
  65. package/src/bin/hisaabo.ts +0 -74
  66. package/src/bin/registrars/api-key.ts +0 -44
  67. package/src/bin/registrars/auth.ts +0 -222
  68. package/src/bin/registrars/automated-invoice.ts +0 -167
  69. package/src/bin/registrars/bank-recon.ts +0 -34
  70. package/src/bin/registrars/bank.ts +0 -124
  71. package/src/bin/registrars/business.ts +0 -120
  72. package/src/bin/registrars/dashboard.ts +0 -225
  73. package/src/bin/registrars/document.ts +0 -184
  74. package/src/bin/registrars/einvoice.ts +0 -46
  75. package/src/bin/registrars/ewb.ts +0 -37
  76. package/src/bin/registrars/expense.ts +0 -87
  77. package/src/bin/registrars/gst.ts +0 -57
  78. package/src/bin/registrars/import.ts +0 -49
  79. package/src/bin/registrars/invoice.ts +0 -117
  80. package/src/bin/registrars/itc.ts +0 -56
  81. package/src/bin/registrars/item.ts +0 -112
  82. package/src/bin/registrars/journal.ts +0 -47
  83. package/src/bin/registrars/party.ts +0 -81
  84. package/src/bin/registrars/payment.ts +0 -128
  85. package/src/bin/registrars/report.ts +0 -186
  86. package/src/bin/registrars/session.ts +0 -32
  87. package/src/bin/registrars/shipment.ts +0 -74
  88. package/src/bin/registrars/store.ts +0 -128
  89. package/src/bin/registrars/target.ts +0 -46
  90. package/src/bin/registrars/tenant.ts +0 -73
  91. package/src/client.ts +0 -2051
  92. package/src/commands/api-key/create.ts +0 -72
  93. package/src/commands/api-key/list.ts +0 -71
  94. package/src/commands/api-key/revoke.ts +0 -46
  95. package/src/commands/automated-invoice/create.ts +0 -85
  96. package/src/commands/automated-invoice/delete.ts +0 -42
  97. package/src/commands/automated-invoice/get.ts +0 -113
  98. package/src/commands/automated-invoice/history.ts +0 -65
  99. package/src/commands/automated-invoice/index.ts +0 -11
  100. package/src/commands/automated-invoice/list.ts +0 -91
  101. package/src/commands/automated-invoice/pause.ts +0 -29
  102. package/src/commands/automated-invoice/resume.ts +0 -29
  103. package/src/commands/automated-invoice/run-now.ts +0 -29
  104. package/src/commands/automated-invoice/suggestions.ts +0 -68
  105. package/src/commands/automated-invoice/update.ts +0 -54
  106. package/src/commands/automated-invoice/usage.ts +0 -68
  107. package/src/commands/bank/gateway-config.ts +0 -61
  108. package/src/commands/bank/index.ts +0 -244
  109. package/src/commands/bank/update-gateway.ts +0 -84
  110. package/src/commands/bank-recon/index.ts +0 -127
  111. package/src/commands/business/audit-trail.ts +0 -79
  112. package/src/commands/business/export.ts +0 -52
  113. package/src/commands/business/get.ts +0 -55
  114. package/src/commands/business/sequence.ts +0 -65
  115. package/src/commands/business/update.ts +0 -64
  116. package/src/commands/dashboard/collection-efficiency.ts +0 -164
  117. package/src/commands/dashboard/expenses.ts +0 -76
  118. package/src/commands/dashboard/invoice-breakdown.ts +0 -89
  119. package/src/commands/dashboard/monthly-comparison.ts +0 -193
  120. package/src/commands/dashboard/payment-modes.ts +0 -121
  121. package/src/commands/dashboard/profit-loss.ts +0 -146
  122. package/src/commands/dashboard/receivables-aging.ts +0 -169
  123. package/src/commands/dashboard/sales-trend.ts +0 -68
  124. package/src/commands/dashboard/summary.ts +0 -105
  125. package/src/commands/dashboard/top-customers.ts +0 -70
  126. package/src/commands/dashboard/top-items.ts +0 -74
  127. package/src/commands/dashboard/top-outstanding.ts +0 -61
  128. package/src/commands/dashboard.ts +0 -105
  129. package/src/commands/document/factory.ts +0 -590
  130. package/src/commands/einvoice/index.ts +0 -109
  131. package/src/commands/ewb/index.ts +0 -108
  132. package/src/commands/expense/categories.ts +0 -40
  133. package/src/commands/expense/create.ts +0 -51
  134. package/src/commands/expense/delete.ts +0 -45
  135. package/src/commands/expense/list.ts +0 -65
  136. package/src/commands/expense/update.ts +0 -58
  137. package/src/commands/gst/index.ts +0 -194
  138. package/src/commands/import/index.ts +0 -168
  139. package/src/commands/invoice/create.ts +0 -262
  140. package/src/commands/invoice/delete.ts +0 -44
  141. package/src/commands/invoice/get.ts +0 -105
  142. package/src/commands/invoice/list.ts +0 -126
  143. package/src/commands/invoice/pdf.ts +0 -75
  144. package/src/commands/invoice/status.ts +0 -41
  145. package/src/commands/itc/index.ts +0 -163
  146. package/src/commands/item/categories.ts +0 -40
  147. package/src/commands/item/create.ts +0 -98
  148. package/src/commands/item/delete.ts +0 -44
  149. package/src/commands/item/list.ts +0 -81
  150. package/src/commands/item/low-stock-count.ts +0 -32
  151. package/src/commands/item/merge.ts +0 -53
  152. package/src/commands/item/price-history.ts +0 -59
  153. package/src/commands/item/rename-unit.ts +0 -39
  154. package/src/commands/item/sales-stats.ts +0 -44
  155. package/src/commands/item/stock-history.ts +0 -70
  156. package/src/commands/item/stock.ts +0 -46
  157. package/src/commands/item/switch-base-unit.ts +0 -42
  158. package/src/commands/item/update.ts +0 -59
  159. package/src/commands/item/variants-create.ts +0 -58
  160. package/src/commands/item/variants-delete.ts +0 -47
  161. package/src/commands/item/variants-list.ts +0 -63
  162. package/src/commands/item/variants-update.ts +0 -61
  163. package/src/commands/journal/index.ts +0 -156
  164. package/src/commands/party/create.ts +0 -88
  165. package/src/commands/party/delete.ts +0 -44
  166. package/src/commands/party/get.ts +0 -42
  167. package/src/commands/party/ledger-report.ts +0 -81
  168. package/src/commands/party/ledger.ts +0 -63
  169. package/src/commands/party/list.ts +0 -69
  170. package/src/commands/party/merge.ts +0 -50
  171. package/src/commands/party/stats.ts +0 -40
  172. package/src/commands/party/top-items.ts +0 -57
  173. package/src/commands/party/update.ts +0 -65
  174. package/src/commands/payment/create.ts +0 -131
  175. package/src/commands/payment/default-account.ts +0 -56
  176. package/src/commands/payment/delete.ts +0 -46
  177. package/src/commands/payment/get.ts +0 -59
  178. package/src/commands/payment/list.ts +0 -66
  179. package/src/commands/payment/unpaid-invoices.ts +0 -69
  180. package/src/commands/payment/untracked.ts +0 -70
  181. package/src/commands/payment/update.ts +0 -54
  182. package/src/commands/report/index.ts +0 -736
  183. package/src/commands/session/list.ts +0 -91
  184. package/src/commands/session/revoke-all.ts +0 -20
  185. package/src/commands/session/revoke.ts +0 -32
  186. package/src/commands/shipment/index.ts +0 -170
  187. package/src/commands/store/check-slug.ts +0 -48
  188. package/src/commands/store/index.ts +0 -77
  189. package/src/commands/store/items-toggle.ts +0 -41
  190. package/src/commands/store/items.ts +0 -61
  191. package/src/commands/store/order-cancel.ts +0 -48
  192. package/src/commands/store/order-confirm.ts +0 -45
  193. package/src/commands/store/order-get.ts +0 -66
  194. package/src/commands/store/order-update.ts +0 -52
  195. package/src/commands/store/update-settings.ts +0 -52
  196. package/src/commands/target/index.ts +0 -118
  197. package/src/commands/tenant/invitations.ts +0 -62
  198. package/src/commands/tenant/invite.ts +0 -57
  199. package/src/commands/tenant/list.ts +0 -46
  200. package/src/commands/tenant/members.ts +0 -55
  201. package/src/commands/tenant/remove.ts +0 -47
  202. package/src/commands/tenant/revoke-invitation.ts +0 -32
  203. package/src/commands/tenant/update-role.ts +0 -41
  204. package/src/config.ts +0 -96
  205. package/src/error-handler.ts +0 -53
  206. package/src/format.ts +0 -180
  207. package/src/output.ts +0 -228
  208. package/src/spinner.ts +0 -39
  209. package/tsconfig.json +0 -22
  210. package/tsup.config.ts +0 -18
@@ -1,1269 +0,0 @@
1
- # Hisaabo CLI: UX Architecture & Interaction Patterns
2
-
3
- ## Table of Contents
4
-
5
- 1. [Global Conventions](#1-global-conventions)
6
- 2. [Information Density](#2-information-density)
7
- 3. [Interactive Flows](#3-interactive-flows)
8
- 4. [Non-Interactive Mode](#4-non-interactive-mode)
9
- 5. [Error States](#5-error-states)
10
- 6. [Navigation Patterns](#6-navigation-patterns)
11
- 7. [Configuration & Auth](#7-configuration--auth)
12
- 8. [Implementation Notes](#8-implementation-notes)
13
-
14
- ---
15
-
16
- ## 1. Global Conventions
17
-
18
- ### Command Grammar
19
-
20
- Every command follows: `hisaabo <resource> <action> [flags]`
21
-
22
- ```
23
- hisaabo login
24
- hisaabo dashboard
25
- hisaabo invoice list
26
- hisaabo invoice create
27
- hisaabo invoice get INV-0042
28
- hisaabo invoice pdf INV-0042
29
- hisaabo party list --type customer
30
- hisaabo payment create
31
- hisaabo expense list --from 2026-04-01 --to 2026-06-30
32
- hisaabo gst r1 --quarter Q1
33
- hisaabo report daybook --from 2026-04-01 --to 2026-04-30
34
- ```
35
-
36
- Resources match the existing tRPC router names exactly: `invoice`, `party`, `item`, `payment`, `expense`, `bank`, `shipment`, `gst`, `report`.
37
-
38
- ### INR Formatting
39
-
40
- All monetary values use the Indian numbering system with the rupee symbol. This matches the existing `formatCurrency` in `packages/shared`:
41
-
42
- ```
43
- 12,345.00 -- amounts under 1 lakh, no symbol in tables (column header has it)
44
- 1,23,456.78 -- lakhs grouping
45
- 15,00,000.00 -- standard crore notation
46
- ```
47
-
48
- Right-align all currency columns. Use the `en-IN` locale for grouping. The column header carries the symbol once:
49
-
50
- ```
51
- Amount (₹)
52
- ─────────────
53
- 12,345.00
54
- 1,23,456.78
55
- ```
56
-
57
- Negative amounts (credit notes, refunds) use a minus prefix, not parentheses:
58
-
59
- ```
60
- -5,000.00
61
- ```
62
-
63
- ### Date Formatting
64
-
65
- Match the existing `formatDate` function (en-IN, `dd MMM yyyy`):
66
-
67
- ```
68
- 30 Mar 2026
69
- 01 Apr 2025
70
- ```
71
-
72
- For relative dates in status contexts (overdue by, due in):
73
-
74
- ```
75
- Due in 3 days
76
- Overdue by 12 days
77
- Due today
78
- ```
79
-
80
- ### Status Indicators
81
-
82
- Terminal-safe Unicode characters with ANSI colors. These map directly to the `invoiceStatusEnum` and the existing `STATUS_CONFIG` in the mobile app:
83
-
84
- ```
85
- Status Symbol Color (ANSI) Code
86
- ──────────────────────────────────────────────
87
- paid [PAID] green (32) \x1b[32m
88
- sent [SENT] blue (34) \x1b[34m
89
- draft [DRAFT] dim (2) \x1b[2m
90
- partial [PARTIAL] yellow (33) \x1b[33m
91
- overdue [OVERDUE] red (31) \x1b[31m
92
- cancelled [CANCEL] dim (2;9) \x1b[2;9m (dim + strikethrough)
93
- unfulfilled [UNFUL] blue (34) \x1b[34m
94
- pending [PEND] yellow (33) \x1b[33m
95
- confirmed [CONF] blue (34) \x1b[34m
96
- delivered [DELIV] green (32) \x1b[32m
97
- ```
98
-
99
- When `--no-color` is set or `NO_COLOR` env var is present, strip all ANSI codes and use text-only badges:
100
-
101
- ```
102
- [PAID] [OVERDUE] [DRAFT] [PARTIAL]
103
- ```
104
-
105
- ### Terminal Width Awareness
106
-
107
- Detect terminal width via `process.stdout.columns` (default 80). Three layout tiers:
108
-
109
- - **Narrow (< 80)**: Compact single-line per record, truncate party names to 15 chars
110
- - **Standard (80-120)**: Full table with all relevant columns
111
- - **Wide (> 120)**: Add extra columns (notes, created by, etc.)
112
-
113
- ---
114
-
115
- ## 2. Information Density
116
-
117
- ### 2.1 Invoice List
118
-
119
- The most-used screen. Optimized for scanning 50+ invoices quickly.
120
-
121
- **Standard width (80-120 cols):**
122
-
123
- ```
124
- Sale Invoices FY 2025-26
125
- ══════════════════════════════════════════════════════════════════════
126
-
127
- # Party Date Amount (₹) Status
128
- ─────────────────────────────────────────────────────────────────────
129
- INV-0042 Sharma Traders 30 Mar 2026 15,400.00 [PAID]
130
- INV-0041 Patel & Sons 28 Mar 2026 1,23,000.00 [PARTIAL]
131
- INV-0040 Gupta Retail 27 Mar 2026 800.00 [OVERDUE]
132
- INV-0039 ABC Wholesale 25 Mar 2026 45,200.00 [SENT]
133
- INV-0038 Kumar Stores 24 Mar 2026 2,500.00 [DRAFT]
134
- ─────────────────────────────────────────────────────────────────────
135
- Showing 1-20 of 156 Total: 8,45,900.00
136
-
137
- [n] Next page [p] Previous [/] Search [q] Quit
138
- ```
139
-
140
- **Narrow width (< 80 cols):**
141
-
142
- ```
143
- INV-0042 Sharma Traders 15,400.00 [PAID]
144
- INV-0041 Patel & Sons 1,23,000.00 [PARTIAL]
145
- INV-0040 Gupta Retail 800.00 [OVERDUE]
146
- ```
147
-
148
- **Wide width (> 120 cols) adds columns:**
149
-
150
- ```
151
- # Party Date Due Amount (₹) Paid (₹) Balance (₹) Status
152
- ──────────────────────────────────────────────────────────────────────────────────────────────────────────
153
- INV-0042 Sharma Traders 30 Mar 2026 14 Apr 2026 15,400.00 15,400.00 0.00 [PAID]
154
- INV-0041 Patel & Sons 28 Mar 2026 12 Apr 2026 1,23,000.00 50,000.00 73,000.00 [PARTIAL]
155
- ```
156
-
157
- ### 2.2 Invoice Detail View
158
-
159
- When a user runs `hisaabo invoice get INV-0042`:
160
-
161
- ```
162
- ┌─────────────────────────────────────────────────────────────────┐
163
- │ SALE INVOICE INV-0042 [PAID] │
164
- ├─────────────────────────────────────────────────────────────────┤
165
- │ Party: Sharma Traders (Customer) │
166
- │ Date: 30 Mar 2026 │
167
- │ Due: 14 Apr 2026 │
168
- │ Created: Saurabh (30 Mar 2026, 10:32 AM) │
169
- │ Delivery: Hand Delivery │
170
- ├─────────────────────────────────────────────────────────────────┤
171
- │ │
172
- │ # Item Qty Rate (₹) Tax% Amount (₹) │
173
- │ ── ─────────────────── ───── ────────── ────── ──────────── │
174
- │ 1 Basmati Rice 5kg 10 1,200.00 5% 12,600.00 │
175
- │ 2 Toor Dal 1kg 5 180.00 12% 1,008.00 │
176
- │ 3 Packing Charges 1 200.00 0% 200.00 │
177
- │ │
178
- ├─────────────────────────────────────────────────────────────────┤
179
- │ Subtotal: 13,808.00 │
180
- │ Tax: 1,608.00 │
181
- │ Additional Charges: 200.00 (Delivery) │
182
- │ Discount: -216.00 │
183
- │ Round Off: 0.22 │
184
- │ ───────────────────────────────── │
185
- │ Total: 15,400.00 │
186
- │ Paid: 15,400.00 │
187
- │ Balance: 0.00 │
188
- ├─────────────────────────────────────────────────────────────────┤
189
- │ Notes: Deliver before Holi │
190
- │ Terms: Payment within 15 days of invoice date │
191
- └─────────────────────────────────────────────────────────────────┘
192
-
193
- Actions: [e] Edit [p] PDF [s] Share [d] Duplicate [pay] Record Payment
194
- ```
195
-
196
- ### 2.3 Dashboard Summary
197
-
198
- `hisaabo dashboard`:
199
-
200
- ```
201
- Hisaabo Dashboard Sharma Trading Co.
202
- FY 2025-26 (01 Apr 2025 - 31 Mar 2026)
203
- ═══════════════════════════════════════════════════════════
204
-
205
- ┌─ Revenue ───────────┐ ┌─ Expenses ──────────┐
206
- │ Sales 18,45,000 │ │ Purchases 8,20,000 │
207
- │ Cash In 15,30,000 │ │ Expenses 2,15,000 │
208
- │ │ │ Cash Out 9,80,000 │
209
- └──────────────────────┘ └─────────────────────┘
210
-
211
- ┌─ Outstanding ────────────────────────────────────┐
212
- │ Receivable 3,15,000 from 12 parties │
213
- │ Payable 1,40,000 to 5 parties │
214
- │ Net Position 1,75,000 receivable │
215
- └──────────────────────────────────────────────────┘
216
-
217
- ┌─ Recent Invoices ───────────────────────────────────────┐
218
- │ INV-0042 Sharma Traders 15,400.00 [PAID] Today │
219
- │ INV-0041 Patel & Sons 1,23,000.00 [PARTIAL] 2d ago │
220
- │ INV-0040 Gupta Retail 800.00 [OVERDUE] 3d ago │
221
- │ INV-0039 ABC Wholesale 45,200.00 [SENT] 5d ago │
222
- │ INV-0038 Kumar Stores 2,500.00 [DRAFT] 6d ago │
223
- └─────────────────────────────────────────────────────────┘
224
-
225
- Low Stock Alerts: Basmati Rice 5kg (2 left), Toor Dal 1kg (5 left)
226
- ```
227
-
228
- ### 2.4 Party List
229
-
230
- `hisaabo party list --type customer`:
231
-
232
- ```
233
- Customers 12 total
234
- ════════════════════════════════════════════════════════════════
235
-
236
- Name Phone Balance (₹) Invoices Category
237
- ──────────────────────────────────────────────────────────────────────
238
- Sharma Traders +91 98765xxxxx 45,200.00 23 Retail
239
- Patel & Sons +91 87654xxxxx 73,000.00 18 Wholesale
240
- Gupta Retail +91 76543xxxxx 800.00 4 Retail
241
- ABC Wholesale +91 65432xxxxx 0.00 31 Wholesale
242
-
243
- Sort: [n] Name [b] Balance [i] Invoice count [q] Quit
244
- ```
245
-
246
- ### 2.5 Item List
247
-
248
- `hisaabo item list`:
249
-
250
- ```
251
- Items 45 total
252
- ═══════════════════════════════════════════════════════════════
253
-
254
- Name HSN Unit Sale (₹) Stock Tax%
255
- ─────────────────────────────────────────────────────────────
256
- Basmati Rice 5kg 10063010 pcs 1,200.00 2 ! 5%
257
- Toor Dal 1kg 07139090 kg 180.00 5 12%
258
- Packing Box 48191000 pcs 50.00 200 0%
259
- Courier Service 996812 - 250.00 - 18%
260
-
261
- ! = below low stock alert threshold
262
- ```
263
-
264
- ### 2.6 GST Reports
265
-
266
- `hisaabo gst r1 --quarter Q4`:
267
-
268
- ```
269
- GSTR-1 Summary Q4 FY 2025-26
270
- Jan 2026 - Mar 2026 GSTIN: 07AAACR5055K1Z5
271
- ═════════════════════════════════════════════════════════════
272
-
273
- B2B Invoices (> ₹2,50,000)
274
- ──────────────────────────────────────────────────────────────
275
- Invoice Party GSTIN Taxable (₹) Tax (₹)
276
- INV-0035 07AAACR5055K1Z5 3,50,000.00 63,000.00
277
- INV-0029 27AABCU9603R1ZM 2,80,000.00 50,400.00
278
-
279
- B2C (Small) Summary
280
- ──────────────────────────────────────────────────────────────
281
- Rate Taxable (₹) CGST (₹) SGST (₹)
282
- 5% 4,50,000.00 11,250.00 11,250.00
283
- 12% 2,80,000.00 16,800.00 16,800.00
284
- 18% 95,000.00 8,550.00 8,550.00
285
-
286
- Totals
287
- ──────────────────────────────────────────────────────────────
288
- Total Taxable: 14,55,000.00
289
- Total Tax: 1,61,550.00
290
- Total Invoices: 42
291
- ```
292
-
293
- ---
294
-
295
- ## 3. Interactive Flows
296
-
297
- ### 3.1 First-Time Login
298
-
299
- ```
300
- $ hisaabo login
301
-
302
- Hisaabo CLI
303
- ───────────
304
-
305
- Server URL [http://localhost:3000]: https://billing.mycompany.in
306
- Email: saurabh@example.com
307
- Password: ••••••••
308
-
309
- Authenticating... done
310
-
311
- You have access to 2 businesses:
312
-
313
- # Business GSTIN Role
314
- ── ────────────────────── ─────────────────── ──────
315
- 1 Sharma Trading Co. 07AAACR5055K1Z5 owner
316
- 2 Kumar Enterprises 27AABCU9603R1ZM admin
317
-
318
- Select business [1]: 1
319
-
320
- Active business: Sharma Trading Co.
321
- Config saved to ~/.config/hisaabo/config.json
322
-
323
- You can switch businesses anytime with:
324
- hisaabo business switch
325
- ```
326
-
327
- ### 3.2 Invoice Creation (Interactive)
328
-
329
- `hisaabo invoice create`:
330
-
331
- The flow mirrors the web `InvoiceCreator.tsx` but linearized for terminal. Each step can be skipped or pre-filled via flags.
332
-
333
- ```
334
- $ hisaabo invoice create
335
-
336
- New Sale Invoice
337
- ────────────────
338
-
339
- Type (sale/purchase) [sale]: sale
340
-
341
- Select Party:
342
- > Search: sha█
343
- 1 Sharma Traders +91 98765xxxxx Customer
344
- 2 Shankar & Co. +91 87654xxxxx Customer
345
-
346
- Party [1]: 1
347
- Party: Sharma Traders
348
-
349
- Add Line Items (empty description to finish):
350
-
351
- Item 1:
352
- Search item: bas█
353
- 1 Basmati Rice 5kg ₹1,200.00/pcs Stock: 2
354
- 2 Basmati Rice 1kg ₹280.00/pcs Stock: 15
355
- Item [1]: 1
356
- Quantity [1]: 10
357
- Unit Price [1200.00]: 1200
358
- Tax % [5]: 5
359
- Discount % [0]:
360
- > Basmati Rice 5kg x10 @1,200.00 5% tax = 12,600.00
361
-
362
- Item 2:
363
- Search item: toor█
364
- 1 Toor Dal 1kg ₹180.00/kg Stock: 5
365
- Item [1]: 1
366
- Quantity [1]: 5
367
- Unit Price [180.00]:
368
- Tax % [12]:
369
- Discount % [0]:
370
- > Toor Dal 1kg x5 @180.00 12% tax = 1,008.00
371
-
372
- Item 3:
373
- Description: (empty, done adding items)
374
-
375
- ─── Invoice Summary ───────────────────────────
376
- Subtotal: 13,608.00
377
- Tax: 1,608.00
378
- Additional Charges [0]:
379
- Discount [0]:
380
- Round Off [auto]: 0.22
381
-
382
- Total: 15,216.22
383
-
384
- Invoice Date [30 Mar 2026]:
385
- Due Date [14 Apr 2026]:
386
- Delivery Method [self_pickup]: hand_delivery
387
- Notes:
388
- Terms:
389
- ───────────────────────────────────────────────
390
-
391
- Create this invoice? (y/n) [y]: y
392
-
393
- Created: INV-0042 for ₹15,216.22
394
- View: hisaabo invoice get INV-0042
395
- PDF: hisaabo invoice pdf INV-0042
396
- ```
397
-
398
- **Shortcut for power users** -- supply everything via flags:
399
-
400
- ```
401
- $ hisaabo invoice create \
402
- --party "Sharma Traders" \
403
- --item "Basmati Rice 5kg" --qty 10 --rate 1200 \
404
- --item "Toor Dal 1kg" --qty 5 \
405
- --delivery hand_delivery \
406
- --yes
407
- ```
408
-
409
- ### 3.3 Payment Recording (Interactive)
410
-
411
- `hisaabo payment create`:
412
-
413
- ```
414
- $ hisaabo payment create
415
-
416
- Record Payment
417
- ──────────────
418
-
419
- Select Party:
420
- > Search: pat█
421
- 1 Patel & Sons Balance: ₹73,000.00 receivable
422
-
423
- Party [1]: 1
424
-
425
- Unpaid Invoices for Patel & Sons:
426
- # Invoice Date Total (₹) Paid (₹) Due (₹) Status
427
- ── ────────── ────────────── ─────────── ─────────── ─────────── ──────────
428
- 1 INV-0041 28 Mar 2026 1,23,000.00 50,000.00 73,000.00 [PARTIAL]
429
- 2 INV-0036 15 Mar 2026 25,000.00 0.00 25,000.00 [SENT]
430
-
431
- Allocate to specific invoices? (y/n) [y]: y
432
-
433
- INV-0041 - Due: ₹73,000.00
434
- Amount to allocate [73000.00]: 50000
435
-
436
- INV-0036 - Due: ₹25,000.00
437
- Amount to allocate [25000.00]: 25000
438
-
439
- Total Payment: 75,000.00
440
-
441
- Payment Mode (cash/bank/upi/cheque/other) [upi]: upi
442
- Reference Number: TXN123456
443
- Bank Account [HDFC Current]: 1
444
- Payment Date [30 Mar 2026]:
445
- Notes:
446
-
447
- Record this payment? (y/n) [y]: y
448
-
449
- Recorded: PAY-0089 for ₹75,000.00
450
- Allocated: INV-0041 (₹50,000.00), INV-0036 (₹25,000.00)
451
- Patel & Sons new balance: ₹23,000.00 receivable
452
- ```
453
-
454
- ### 3.4 Quick Operations (No Wizard Needed)
455
-
456
- Some operations should be instant, no wizard:
457
-
458
- ```
459
- # Mark invoice as sent
460
- $ hisaabo invoice status INV-0042 sent
461
- INV-0042 status updated: draft -> [SENT]
462
-
463
- # Download PDF
464
- $ hisaabo invoice pdf INV-0042
465
- Saved: INV-0042.pdf (45 KB)
466
-
467
- $ hisaabo invoice pdf INV-0042 --output ~/Desktop/
468
- Saved: ~/Desktop/INV-0042.pdf (45 KB)
469
-
470
- # Quick expense entry
471
- $ hisaabo expense create --amount 500 --category "Office Supplies" --mode cash
472
- Created: Expense #45 - Office Supplies ₹500.00
473
-
474
- # Switch business
475
- $ hisaabo business switch
476
- 1 Sharma Trading Co. [active]
477
- 2 Kumar Enterprises
478
- Select [2]: 2
479
- Switched to: Kumar Enterprises
480
- ```
481
-
482
- ### 3.5 Search and Filtering
483
-
484
- Consistent filtering grammar across all resources:
485
-
486
- ```
487
- # Date ranges
488
- $ hisaabo invoice list --from 2026-01-01 --to 2026-03-31
489
- $ hisaabo invoice list --this-month
490
- $ hisaabo invoice list --this-quarter
491
- $ hisaabo invoice list --this-fy
492
-
493
- # Status filtering
494
- $ hisaabo invoice list --status overdue
495
- $ hisaabo invoice list --status overdue,partial
496
-
497
- # Party filtering
498
- $ hisaabo invoice list --party "Sharma Traders"
499
- $ hisaabo invoice list --party-id 550e8400-e29b-41d4-a716-446655440000
500
-
501
- # Type filtering
502
- $ hisaabo invoice list --type sale
503
- $ hisaabo party list --type customer
504
-
505
- # Combined
506
- $ hisaabo invoice list --type sale --status overdue --this-month
507
-
508
- # Full text search
509
- $ hisaabo party search "sharma"
510
- $ hisaabo item search "basmati"
511
- ```
512
-
513
- ---
514
-
515
- ## 4. Non-Interactive Mode
516
-
517
- ### 4.1 JSON Output
518
-
519
- Every command supports `--json` for machine-readable output:
520
-
521
- ```
522
- $ hisaabo invoice list --status overdue --json
523
- ```
524
-
525
- ```json
526
- {
527
- "data": [
528
- {
529
- "id": "550e8400-e29b-41d4-a716-446655440000",
530
- "invoiceNumber": "INV-0040",
531
- "party": {
532
- "id": "...",
533
- "name": "Gupta Retail"
534
- },
535
- "type": "sale",
536
- "status": "overdue",
537
- "invoiceDate": "2026-03-27T00:00:00.000Z",
538
- "dueDate": "2026-03-30T00:00:00.000Z",
539
- "totalAmount": "800.00",
540
- "amountPaid": "0.00",
541
- "balance": "800.00"
542
- }
543
- ],
544
- "pagination": {
545
- "page": 1,
546
- "limit": 20,
547
- "total": 3,
548
- "hasMore": false
549
- }
550
- }
551
- ```
552
-
553
- ### 4.2 Piping Patterns
554
-
555
- TSV output for piping to standard Unix tools:
556
-
557
- ```
558
- # Pipe to awk for custom calculations
559
- $ hisaabo invoice list --status overdue --format tsv | awk -F'\t' '{sum += $5} END {print sum}'
560
-
561
- # Pipe to grep
562
- $ hisaabo party list --format tsv | grep "Wholesale"
563
-
564
- # Feed into another command
565
- $ hisaabo invoice list --status draft --format ids | xargs -I{} hisaabo invoice status {} sent
566
-
567
- # CSV export
568
- $ hisaabo invoice list --this-fy --format csv > invoices-fy2526.csv
569
- ```
570
-
571
- Output formats:
572
-
573
- | Flag | Format | Use Case |
574
- |------|--------|----------|
575
- | (default) | Pretty table | Human reading |
576
- | `--json` | JSON | Scripts, jq |
577
- | `--format tsv` | Tab-separated | Unix pipes, awk |
578
- | `--format csv` | CSV with headers | Spreadsheet import |
579
- | `--format ids` | One ID per line | xargs, loops |
580
- | `--quiet` / `-q` | Suppress all output except errors | Cron jobs |
581
-
582
- ### 4.3 Exit Codes
583
-
584
- ```
585
- 0 Success
586
- 1 General error (unexpected)
587
- 2 Usage error (bad arguments, missing required flags)
588
- 3 Authentication error (not logged in, expired token)
589
- 4 Authorization error (insufficient permissions)
590
- 5 Not found (resource doesn't exist)
591
- 6 Validation error (business logic violation)
592
- 7 Network error (API unreachable)
593
- 8 Conflict (duplicate invoice number, concurrent edit)
594
- ```
595
-
596
- Script example:
597
-
598
- ```bash
599
- #!/bin/bash
600
- # Daily overdue reminder script (cron: 0 9 * * *)
601
-
602
- overdue=$(hisaabo invoice list --status overdue --json 2>/dev/null)
603
- exit_code=$?
604
-
605
- if [ $exit_code -eq 3 ]; then
606
- echo "Auth expired, re-login needed" >&2
607
- exit 1
608
- fi
609
-
610
- if [ $exit_code -eq 7 ]; then
611
- echo "API unreachable" >&2
612
- exit 1
613
- fi
614
-
615
- count=$(echo "$overdue" | jq '.pagination.total')
616
- total=$(echo "$overdue" | jq '[.data[].balance | tonumber] | add')
617
-
618
- if [ "$count" -gt 0 ]; then
619
- echo "ALERT: $count overdue invoices totaling INR $total"
620
- echo "$overdue" | jq -r '.data[] | "\(.invoiceNumber) - \(.party.name) - INR \(.balance)"'
621
- fi
622
- ```
623
-
624
- ### 4.4 Idempotent Operations
625
-
626
- For scripting safety, create operations accept `--idempotency-key`:
627
-
628
- ```
629
- # Safe to retry -- won't create duplicate invoices
630
- $ hisaabo invoice create --idempotency-key "daily-sharma-2026-03-30" \
631
- --party "Sharma Traders" \
632
- --item "Basmati Rice 5kg" --qty 10 \
633
- --yes
634
-
635
- # First run: Created: INV-0043
636
- # Second run: Already exists: INV-0043 (idempotency key match)
637
- ```
638
-
639
- ### 4.5 Batch Operations
640
-
641
- ```
642
- # Bulk status update
643
- $ hisaabo invoice status --from-status draft --to-status sent --this-week
644
- Updated 8 invoices: draft -> sent
645
-
646
- # Import from CSV (matches existing import router)
647
- $ hisaabo import parties --file customers.csv --dry-run
648
- Parsed 45 records: 40 new, 3 duplicates (will skip), 2 errors
649
- Run without --dry-run to import.
650
-
651
- $ hisaabo import parties --file customers.csv
652
- Imported 40 parties, skipped 3 duplicates, 2 errors (see import-errors.log)
653
- ```
654
-
655
- ---
656
-
657
- ## 5. Error States
658
-
659
- ### 5.1 Validation Errors
660
-
661
- Field-level errors with the exact field name (matching Zod validator paths from `packages/shared`):
662
-
663
- ```
664
- $ hisaabo party create --name "" --phone "abc"
665
-
666
- Error: Validation failed (2 errors)
667
-
668
- name String must contain at least 1 character(s)
669
- phone Invalid phone number format
670
-
671
- Run with --help for field requirements.
672
- ```
673
-
674
- For interactive mode, validate inline and re-prompt:
675
-
676
- ```
677
- Name: █
678
- Error: Name is required. Try again.
679
- Name: █
680
- ```
681
-
682
- ### 5.2 Network Errors
683
-
684
- ```
685
- $ hisaabo dashboard
686
-
687
- Error: Cannot reach Hisaabo API at https://billing.mycompany.in
688
-
689
- Possible causes:
690
- - Server is not running (try: docker compose up -d)
691
- - Network is unreachable
692
- - URL is wrong (check: hisaabo config show)
693
-
694
- Last successful connection: 30 Mar 2026, 09:15 AM
695
- ```
696
-
697
- ### 5.3 Authentication Errors
698
-
699
- ```
700
- $ hisaabo invoice list
701
-
702
- Error: Session expired
703
-
704
- Run 'hisaabo login' to re-authenticate.
705
- Your business selection will be preserved.
706
- ```
707
-
708
- Token refresh happens silently. Only show auth errors when refresh also fails.
709
-
710
- ### 5.4 Business Logic Errors
711
-
712
- Map these to user-understandable messages:
713
-
714
- ```
715
- # Insufficient stock
716
- $ hisaabo invoice create --party "Sharma" --item "Basmati Rice 5kg" --qty 100 --yes
717
-
718
- Error: Insufficient stock for Basmati Rice 5kg
719
-
720
- Available: 2 pcs
721
- Requested: 100 pcs
722
-
723
- Use --skip-stock-check to override (for back-orders).
724
-
725
- # Duplicate invoice number
726
- $ hisaabo invoice create ...
727
-
728
- Error: Invoice number INV-0042 already exists
729
-
730
- The server auto-assigns the next number. If you need to reset:
731
- hisaabo business sequence invoice 100
732
-
733
- # Credit limit exceeded
734
- $ hisaabo invoice create --party "Kumar Stores" ...
735
-
736
- Warning: This invoice will exceed Kumar Stores' credit limit.
737
-
738
- Credit Limit: 50,000.00
739
- Current Balance: 48,000.00
740
- This Invoice: 5,000.00
741
- New Balance: 53,000.00
742
-
743
- Proceed anyway? (y/n) [n]:
744
- ```
745
-
746
- ### 5.5 Error Output Convention
747
-
748
- Errors always go to stderr, never stdout. This keeps piping clean:
749
-
750
- ```
751
- # stdout has the data, stderr has the error
752
- $ hisaabo invoice list --json 2>errors.log | jq '.data | length'
753
- ```
754
-
755
- Error format in `--json` mode:
756
-
757
- ```json
758
- {
759
- "error": {
760
- "code": "VALIDATION_ERROR",
761
- "message": "Validation failed",
762
- "fields": {
763
- "name": "String must contain at least 1 character(s)",
764
- "phone": "Invalid phone number format"
765
- }
766
- }
767
- }
768
- ```
769
-
770
- ---
771
-
772
- ## 6. Navigation Patterns
773
-
774
- ### 6.1 Help Structure
775
-
776
- Three levels of help, matching how users actually ask for help:
777
-
778
- **Level 1: Overview** (`hisaabo --help`):
779
-
780
- ```
781
- Hisaabo CLI - Self-hosted invoicing for Indian businesses
782
-
783
- Usage: hisaabo <command> [options]
784
-
785
- Commands:
786
- login Authenticate with your Hisaabo server
787
- dashboard View business summary and key metrics
788
- business Manage businesses and settings
789
-
790
- invoice Create, list, and manage invoices
791
- party Manage customers and suppliers
792
- item Manage products and services
793
- payment Record and track payments
794
- expense Track business expenses
795
-
796
- bank Manage bank accounts and transactions
797
- shipment Track deliveries and shipments
798
- gst GST returns and compliance
799
- report Financial reports (daybook, outstanding, P&L, etc.)
800
- import Import data from CSV or other apps
801
-
802
- config View and edit CLI configuration
803
-
804
- Run 'hisaabo <command> --help' for details on a specific command.
805
- Run 'hisaabo <command> <subcommand> --help' for subcommand details.
806
-
807
- Examples:
808
- hisaabo invoice list --this-month --status overdue
809
- hisaabo invoice create --party "Sharma Traders" --item "Rice" --qty 10
810
- hisaabo dashboard
811
- hisaabo gst r1 --quarter Q4
812
- ```
813
-
814
- **Level 2: Command help** (`hisaabo invoice --help`):
815
-
816
- ```
817
- hisaabo invoice - Manage invoices
818
-
819
- Usage: hisaabo invoice <subcommand> [options]
820
-
821
- Subcommands:
822
- list List invoices with filters
823
- get <number> View invoice details
824
- create Create a new invoice (interactive or flags)
825
- edit <number> Edit a draft invoice
826
- status <number> Update invoice status
827
- pdf <number> Download invoice PDF
828
- delete <number> Delete a draft invoice
829
- duplicate <number> Create a copy of an invoice
830
-
831
- Common Flags:
832
- --type <sale|purchase> Filter by invoice type
833
- --status <status> Filter by status
834
- --party <name> Filter by party name
835
- --from <YYYY-MM-DD> Start date
836
- --to <YYYY-MM-DD> End date
837
- --this-month Current month shortcut
838
- --this-quarter Current quarter shortcut
839
- --this-fy Current financial year shortcut
840
- --json Output as JSON
841
- --format <tsv|csv|ids> Alternative output formats
842
- --no-color Disable colored output
843
-
844
- Examples:
845
- hisaabo invoice list --type sale --this-month
846
- hisaabo invoice get INV-0042
847
- hisaabo invoice create --party "Sharma" --item "Rice" --qty 10 --yes
848
- hisaabo invoice pdf INV-0042 --output ~/invoices/
849
- hisaabo invoice status INV-0042 paid
850
- hisaabo invoice list --status overdue --json | jq '.data[].party.name'
851
- ```
852
-
853
- **Level 3: Subcommand help** (`hisaabo invoice create --help`):
854
-
855
- ```
856
- hisaabo invoice create - Create a new invoice
857
-
858
- Usage: hisaabo invoice create [options]
859
-
860
- Without flags, starts an interactive wizard.
861
- With flags, creates directly (use --yes to skip confirmation).
862
-
863
- Options:
864
- --type <sale|purchase> Invoice type (default: sale)
865
- --party <name|id> Party name (fuzzy match) or UUID
866
- --item <name> --qty <n> Add a line item (repeatable)
867
- --rate <amount> Override item sale price
868
- --tax <percent> Override tax percentage
869
- --discount <percent> Line item discount
870
- --date <YYYY-MM-DD> Invoice date (default: today)
871
- --due <YYYY-MM-DD> Due date (default: party credit period)
872
- --delivery <method> self_pickup|hand_delivery|courier|bus|transport|post
873
- --notes <text> Invoice notes
874
- --terms <text> Terms and conditions
875
- --additional-charges <n> Additional charges amount
876
- --invoice-discount <n> Invoice-level discount
877
- --invoice-discount-type amount|percent (default: amount)
878
- --skip-stock-check Allow negative stock
879
- --yes Skip confirmation prompt
880
- --idempotency-key <key> Prevent duplicate creation on retry
881
- --json Output created invoice as JSON
882
-
883
- Examples:
884
- # Interactive wizard
885
- hisaabo invoice create
886
-
887
- # Quick sale
888
- hisaabo invoice create --party "Sharma" --item "Rice" --qty 10 --yes
889
-
890
- # Multiple items
891
- hisaabo invoice create \
892
- --party "Patel & Sons" \
893
- --item "Basmati Rice 5kg" --qty 10 --rate 1200 \
894
- --item "Toor Dal 1kg" --qty 5 \
895
- --delivery hand_delivery \
896
- --notes "Deliver before Holi" \
897
- --yes
898
-
899
- # Scripted with JSON output
900
- hisaabo invoice create --party "Sharma" --item "Rice" --qty 10 --yes --json
901
- ```
902
-
903
- ### 6.2 Command Discovery
904
-
905
- **Fuzzy matching on typos:**
906
-
907
- ```
908
- $ hisaabo invioce list
909
-
910
- Unknown command: invioce
911
-
912
- Did you mean?
913
- invoice Manage invoices
914
-
915
- Run 'hisaabo --help' for all commands.
916
- ```
917
-
918
- **Contextual suggestions after actions:**
919
-
920
- ```
921
- $ hisaabo invoice create ... --yes
922
-
923
- Created: INV-0043 for ₹15,216.22
924
-
925
- Next steps:
926
- hisaabo invoice get INV-0043 View details
927
- hisaabo invoice pdf INV-0043 Download PDF
928
- hisaabo invoice status INV-0043 sent Mark as sent
929
- hisaabo payment create Record a payment
930
- ```
931
-
932
- **Shortest unique prefix (for power users):**
933
-
934
- ```
935
- $ hisaabo inv list # matches 'invoice'
936
- $ hisaabo pay create # matches 'payment'
937
- $ hisaabo dash # matches 'dashboard'
938
- $ hisaabo exp list # matches 'expense'
939
- ```
940
-
941
- ### 6.3 Shell Completions
942
-
943
- Provide installable completions for bash, zsh, and fish:
944
-
945
- ```
946
- $ hisaabo completion bash >> ~/.bashrc
947
- $ hisaabo completion zsh >> ~/.zshrc
948
- $ hisaabo completion fish > ~/.config/fish/completions/hisaabo.fish
949
- ```
950
-
951
- Completions cover:
952
-
953
- - Commands and subcommands
954
- - Flag names and their allowed values (statuses, types, modes)
955
- - Party names (cached locally, refreshed on `hisaabo party list`)
956
- - Item names (cached locally)
957
- - Invoice numbers (recent, cached)
958
- - Bank account names
959
-
960
- Cache location: `~/.cache/hisaabo/completions.json`, refreshed every 5 minutes or on explicit list commands.
961
-
962
- ### 6.4 Recent Command Context
963
-
964
- ```
965
- $ hisaabo invoice list --type sale --this-month --status overdue
966
-
967
- ... (results) ...
968
-
969
- $ hisaabo invoice list --repeat
970
- (re-runs the previous invoice list command with same filters)
971
-
972
- $ hisaabo invoice list --last
973
- (shows what filters were used last time)
974
- Last: --type sale --this-month --status overdue (30 Mar 2026, 10:45 AM)
975
- ```
976
-
977
- ---
978
-
979
- ## 7. Configuration & Auth
980
-
981
- ### 7.1 Config File
982
-
983
- Location: `~/.config/hisaabo/config.json`
984
-
985
- ```json
986
- {
987
- "server": "https://billing.mycompany.in",
988
- "session": {
989
- "id": "...",
990
- "expiresAt": "2026-04-29T10:32:00.000Z"
991
- },
992
- "activeBusinessId": "550e8400-e29b-41d4-a716-446655440000",
993
- "activeBusiness": "Sharma Trading Co.",
994
- "defaults": {
995
- "invoiceType": "sale",
996
- "deliveryMethod": "hand_delivery",
997
- "pageSize": 20
998
- },
999
- "display": {
1000
- "color": true,
1001
- "dateFormat": "en-IN",
1002
- "compactMode": false
1003
- }
1004
- }
1005
- ```
1006
-
1007
- ### 7.2 Config Commands
1008
-
1009
- ```
1010
- $ hisaabo config show
1011
- Server: https://billing.mycompany.in
1012
- Business: Sharma Trading Co. (07AAACR5055K1Z5)
1013
- User: saurabh@example.com
1014
- Session: Valid until 29 Apr 2026
1015
- Defaults: invoice type=sale, delivery=hand_delivery, page=20
1016
-
1017
- $ hisaabo config set defaults.pageSize 50
1018
- Updated: defaults.pageSize = 50
1019
-
1020
- $ hisaabo config set display.color false
1021
- Updated: display.color = false
1022
- ```
1023
-
1024
- ### 7.3 Environment Variable Overrides
1025
-
1026
- Every config value can be overridden via env var (useful for CI/CD):
1027
-
1028
- ```
1029
- HISAABO_SERVER=https://billing.mycompany.in
1030
- HISAABO_SESSION_ID=...
1031
- HISAABO_BUSINESS_ID=...
1032
- HISAABO_NO_COLOR=1
1033
- HISAABO_FORMAT=json
1034
- ```
1035
-
1036
- Priority: CLI flags > env vars > config file > defaults.
1037
-
1038
- ---
1039
-
1040
- ## 8. Implementation Notes
1041
-
1042
- ### 8.1 Recommended Libraries
1043
-
1044
- | Concern | Library | Why |
1045
- |---------|---------|-----|
1046
- | CLI framework | `@oclif/core` or `commander` + `inquirer` | oclif for plugin architecture, commander+inquirer for simpler setup |
1047
- | Table rendering | `cli-table3` | Handles Unicode box drawing, column alignment, width truncation |
1048
- | Colors | `chalk` | Respects `NO_COLOR`, supports 256-color detection |
1049
- | Spinners | `ora` | Non-blocking progress for API calls |
1050
- | Prompts | `@inquirer/prompts` | Modern, composable, supports autocomplete |
1051
- | JSON output | Built-in `JSON.stringify` | No dependency needed |
1052
- | HTTP client | `ofetch` or `ky` | Small, handles retries, timeout |
1053
- | Fuzzy search | `fuse.js` | For party/item name matching in interactive mode |
1054
- | Keychain | `keytar` | Secure session storage on macOS/Linux |
1055
-
1056
- ### 8.2 Package Structure
1057
-
1058
- ```
1059
- apps/cli/
1060
- package.json # @hisaabo/cli
1061
- src/
1062
- index.ts # Entry point, CLI parser setup
1063
- commands/
1064
- login.ts
1065
- dashboard.ts
1066
- invoice/
1067
- list.ts
1068
- get.ts
1069
- create.ts
1070
- status.ts
1071
- pdf.ts
1072
- party/
1073
- list.ts
1074
- get.ts
1075
- create.ts
1076
- item/
1077
- list.ts
1078
- create.ts
1079
- payment/
1080
- list.ts
1081
- create.ts
1082
- expense/
1083
- list.ts
1084
- create.ts
1085
- bank/
1086
- list.ts
1087
- create.ts
1088
- transfer.ts
1089
- gst/
1090
- r1.ts
1091
- r3b.ts
1092
- report/
1093
- daybook.ts
1094
- outstanding.ts
1095
- pnl.ts
1096
- tax-summary.ts
1097
- shipment/
1098
- list.ts
1099
- track.ts
1100
- import.ts
1101
- config.ts
1102
- business/
1103
- list.ts
1104
- switch.ts
1105
- completion.ts
1106
- lib/
1107
- api.ts # HTTP client, auth header injection, business ID header
1108
- config.ts # Read/write ~/.config/hisaabo/config.json
1109
- format.ts # INR formatting, date formatting, status badges
1110
- table.ts # Table rendering with width detection
1111
- prompt.ts # Interactive prompts, party/item search
1112
- errors.ts # Error classification and display
1113
- cache.ts # Completion cache, party/item name cache
1114
- types.ts # CLI-specific types (extends @hisaabo/shared)
1115
- bin/
1116
- hisaabo # Shebang entry: #!/usr/bin/env node
1117
- tsconfig.json
1118
- tsup.config.ts # Bundle for distribution
1119
- ```
1120
-
1121
- ### 8.3 API Communication
1122
-
1123
- The CLI talks to the same Hono+tRPC API as the web app. Two options:
1124
-
1125
- **Option A: Direct tRPC client** (recommended -- get full type safety):
1126
-
1127
- ```typescript
1128
- import { createTRPCClient, httpBatchLink } from "@trpc/client";
1129
- import type { AppRouter } from "@hisaabo/api";
1130
- import SuperJSON from "superjson";
1131
-
1132
- const trpc = createTRPCClient<AppRouter>({
1133
- links: [
1134
- httpBatchLink({
1135
- url: `${config.server}/api/trpc`,
1136
- headers: () => ({
1137
- cookie: `session_id=${config.session.id}`,
1138
- "x-business-id": config.activeBusinessId,
1139
- }),
1140
- transformer: SuperJSON,
1141
- }),
1142
- ],
1143
- });
1144
-
1145
- // Fully typed:
1146
- const invoices = await trpc.invoice.list.query({
1147
- type: "sale",
1148
- status: "overdue",
1149
- page: 1,
1150
- limit: 20,
1151
- });
1152
- ```
1153
-
1154
- **Option B: REST-like HTTP** (for simpler build, but loses type safety):
1155
-
1156
- ```typescript
1157
- const response = await fetch(`${config.server}/api/trpc/invoice.list`, {
1158
- method: "POST",
1159
- headers: {
1160
- "Content-Type": "application/json",
1161
- Cookie: `session_id=${config.session.id}`,
1162
- "x-business-id": config.activeBusinessId,
1163
- },
1164
- body: JSON.stringify({ json: { type: "sale", status: "overdue" } }),
1165
- });
1166
- ```
1167
-
1168
- Option A is strongly preferred since the existing monorepo already has `@hisaabo/api` available as a devDependency for type imports.
1169
-
1170
- ### 8.4 Auth Flow
1171
-
1172
- The API uses session cookies (HttpOnly, 30-day expiry). The CLI stores the session ID in the config file (or system keychain if `keytar` is available):
1173
-
1174
- ```typescript
1175
- // Login: call auth.login, extract session_id from Set-Cookie header
1176
- const response = await fetch(`${server}/api/trpc/auth.login`, {
1177
- method: "POST",
1178
- headers: { "Content-Type": "application/json" },
1179
- body: JSON.stringify({ json: { email, password } }),
1180
- });
1181
-
1182
- const setCookie = response.headers.get("set-cookie");
1183
- const sessionId = parseCookie(setCookie, "session_id");
1184
-
1185
- // Store in config
1186
- await saveConfig({ session: { id: sessionId, expiresAt: "..." } });
1187
- ```
1188
-
1189
- ### 8.5 Performance Budget
1190
-
1191
- For a user billing 50 invoices a day, every millisecond counts:
1192
-
1193
- | Operation | Target | How |
1194
- |-----------|--------|-----|
1195
- | CLI startup | < 200ms | Lazy-load commands, minimal top-level imports |
1196
- | Invoice list | < 500ms | Single tRPC batch call, stream table rows |
1197
- | Invoice create (flags) | < 800ms | Single mutation call |
1198
- | Dashboard | < 1s | Single batch call (matches existing Promise.all in dashboard router) |
1199
- | PDF download | < 2s | Stream to file, show progress bar |
1200
- | Completion load | < 100ms | Read from local cache file |
1201
-
1202
- ### 8.6 Offline Considerations
1203
-
1204
- The CLI requires network access (it talks to the API). But provide graceful degradation:
1205
-
1206
- - Cache the last dashboard response for `hisaabo dashboard --cached`
1207
- - Cache party and item lists for completion (5 min TTL)
1208
- - Queue operations for later with `hisaabo invoice create ... --queue` (writes to `~/.local/share/hisaabo/queue.json`, flushed on `hisaabo sync`)
1209
-
1210
- ### 8.7 Document Type Support
1211
-
1212
- The CLI should support all 8 document types from the schema, using the existing `document-router-factory.ts` endpoints:
1213
-
1214
- ```
1215
- hisaabo invoice list # type=invoice (default)
1216
- hisaabo quotation list # documentType=quotation
1217
- hisaabo credit-note list # documentType=credit_note
1218
- hisaabo debit-note list # documentType=debit_note
1219
- hisaabo challan list # documentType=delivery_challan
1220
- hisaabo proforma list # documentType=proforma
1221
- hisaabo sales-return list # documentType=sales_return
1222
- hisaabo purchase-return list # documentType=purchase_return
1223
- ```
1224
-
1225
- Or use a unified flag:
1226
-
1227
- ```
1228
- hisaabo invoice list --doc-type quotation
1229
- ```
1230
-
1231
- ### 8.8 Report Command Mapping
1232
-
1233
- Maps to the 11 report types in `routers/reports.ts`:
1234
-
1235
- ```
1236
- hisaabo report daybook --from 2026-04-01 --to 2026-04-30
1237
- hisaabo report outstanding --type receivable
1238
- hisaabo report sale-register --this-fy
1239
- hisaabo report purchase-register --this-fy
1240
- hisaabo report tax-summary --this-quarter
1241
- hisaabo report pnl --this-fy
1242
- hisaabo report balance-sheet --as-of 2026-03-31
1243
- hisaabo report stock --low-stock
1244
- hisaabo report ageing --type receivable
1245
- hisaabo report party-statement --party "Sharma Traders"
1246
- hisaabo report expense-summary --this-fy
1247
- ```
1248
-
1249
- ---
1250
-
1251
- ## Design Decisions and Rationale
1252
-
1253
- **Why text badges (`[PAID]`) instead of emoji?**
1254
- Emoji rendering varies wildly across terminals and SSH sessions. A user SSH-ing into their billing server from PuTTY on Windows will see broken emoji. Text badges with ANSI colors work everywhere.
1255
-
1256
- **Why right-aligned currency with Indian grouping?**
1257
- Indian accountants read numbers from right to left (thousands, lakhs, crores). Right-alignment makes columns scannable. The `en-IN` locale grouping (12,34,567) matches what they see in Tally, GST portal, and bank statements.
1258
-
1259
- **Why interactive by default, flags for scripting?**
1260
- An accountant creating their first invoice needs guidance. A developer writing a cron job needs flags. Defaulting to interactive with a `--yes` escape hatch serves both without a mode switch.
1261
-
1262
- **Why fuzzy search for party/item names?**
1263
- Users remember "Sharma" not the full "Sharma Trading Co. Pvt. Ltd." Fuzzy search with ranked results prevents UUID lookups for simple operations.
1264
-
1265
- **Why separate exit codes?**
1266
- A cron job needs to distinguish "invoice not found" (exit 5, retry later) from "auth expired" (exit 3, alert admin). Generic exit 1 for everything makes automation brittle.
1267
-
1268
- **Why `--format ids` output?**
1269
- The most common scripting pattern is "get a list of things, do something to each." Piping IDs through xargs is the Unix way. Without this, users parse JSON with jq just to get IDs.