arch-insight-cli 0.4.2__tar.gz → 0.6.0__tar.gz

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 (24) hide show
  1. arch_insight_cli-0.6.0/PKG-INFO +265 -0
  2. arch_insight_cli-0.6.0/README.md +257 -0
  3. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/__init__.py +1 -1
  4. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/auth.py +56 -4
  5. arch_insight_cli-0.6.0/arch_cli/finance.py +706 -0
  6. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/main.py +113 -83
  7. arch_insight_cli-0.6.0/arch_insight_cli.egg-info/PKG-INFO +265 -0
  8. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/SOURCES.txt +4 -0
  9. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/pyproject.toml +2 -2
  10. arch_insight_cli-0.6.0/tests/test_auth_captcha.py +29 -0
  11. arch_insight_cli-0.6.0/tests/test_claude_session.py +46 -0
  12. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/tests/test_comms.py +29 -0
  13. arch_insight_cli-0.6.0/tests/test_finance.py +360 -0
  14. arch_insight_cli-0.4.2/PKG-INFO +0 -171
  15. arch_insight_cli-0.4.2/README.md +0 -163
  16. arch_insight_cli-0.4.2/arch_insight_cli.egg-info/PKG-INFO +0 -171
  17. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/comms.py +0 -0
  18. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/work.py +0 -0
  19. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/dependency_links.txt +0 -0
  20. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/entry_points.txt +0 -0
  21. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/requires.txt +0 -0
  22. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/top_level.txt +0 -0
  23. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/setup.cfg +0 -0
  24. {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/tests/test_work.py +0 -0
@@ -0,0 +1,265 @@
1
+ Metadata-Version: 2.4
2
+ Name: arch-insight-cli
3
+ Version: 0.6.0
4
+ Summary: Command-line client for ARCH-Insight tasks, factsheets and secrets.
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: arch-secrets>=1.1.2
8
+
9
+ # arch-cli
10
+
11
+ `arch-cli` is the ARCH-Insight command-line client. It includes commands for
12
+ working with the product API, importing architecture data, and using the
13
+ secrets vault.
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ python -m pip install arch-insight-cli
19
+ ```
20
+
21
+ The installed command is `arch` (also available as `arch-cli`). Python 3.9 or
22
+ newer is required.
23
+
24
+ ## Sign in
25
+
26
+ ```sh
27
+ arch login # opens the browser; MFA and consent as for any connected app
28
+ arch login --email you@example.com # unattended: password from ARCH_PASSWORD, or asked for
29
+ arch whoami
30
+ arch logout
31
+ ```
32
+
33
+ The session is stored for your user (`%APPDATA%\arch-insight\credentials.json`
34
+ on Windows, `~/.config/arch-insight/credentials.json` elsewhere, readable by
35
+ you only) and refreshed automatically, so scheduled jobs keep working.
36
+ `ARCH_ACCESS_TOKEN` or `--token` still override it. Set
37
+ `ARCH_API_URL` for a self-hosted deployment (default `https://arch-insight.com`)
38
+ and, if its sign-in is not at `auth.<host>`, `ARCH_AUTH_URL`.
39
+
40
+ ### API keys
41
+
42
+ For scripts and CI, create a personal API key under **Account > API keys**:
43
+ it belongs to one organisation, carries only the scopes you chose (`read`, `projects:write`,
44
+ `finance:write`, `finance:invoice`, ...) and is shown once, starting with
45
+ `ai_live_`.
46
+
47
+ ```sh
48
+ export ARCH_API_KEY=ai_live_... # used as is, nothing stored
49
+ arch login --api-key # or check it and store it (read from ARCH_API_KEY, or asked for)
50
+ arch whoami # shows the key as ai_live_...last4, never in full
51
+ ```
52
+
53
+ Order of precedence: `--token`, `ARCH_ACCESS_TOKEN`, `ARCH_API_KEY`, then
54
+ what `arch login` stored. A key cannot manage keys, billing or members; a
55
+ missing scope comes back as an HTTP 403 with the reason.
56
+
57
+ ## Tasks
58
+
59
+ ```sh
60
+ arch task create "Review database costs" \
61
+ --description "Check the quarterly forecast" \
62
+ --project-id 12 --board-id 4 --priority high \
63
+ --assignee "Alex Example" --due-date 2026-12-01
64
+
65
+ arch task list --project-id 12
66
+ ```
67
+
68
+ The create command prints the created task as JSON. Repeat `--assignee` to
69
+ assign more than one person.
70
+
71
+ ## Fact sheets
72
+
73
+ Create one fact sheet from JSON, import one or more JSON objects, or import an
74
+ ARCH-Insight ZIP export:
75
+
76
+ ```sh
77
+ arch factsheet create application.json
78
+ arch factsheet import fact-sheets.json
79
+ arch factsheet import archi_insight_export.zip
80
+ arch factsheet list
81
+ ```
82
+
83
+ JSON imports create rows one at a time through the same API used by the web
84
+ app. If an item fails, earlier successful items remain created. ZIP imports use
85
+ the application's import endpoint and report imported and skipped entries.
86
+
87
+ ## Projects, tasks, tickets and notes
88
+
89
+ ```sh
90
+ arch project list
91
+ arch project create "Webshop" --priority high
92
+ arch task create "Release Stripe production account" --project-id 12 --assignee st@example.com --due-date 2026-09-14
93
+ arch task update 41 --status in_review
94
+ arch ticket create "Alfen box offline" --message "Since 2026-09-14 after reset" --priority high
95
+ arch ticket reply 7 --message "2026-09-15: back online after factory reset"
96
+ arch document create "Meeting 2026-10-05" --file minutes.md --folder "Change Control Board"
97
+ ```
98
+
99
+ Move a whole list in at once -- projects, their tasks, a dated status log
100
+ kept as a ticket, and notes -- from one JSON file. Re-running it creates
101
+ nothing twice:
102
+
103
+ ```sh
104
+ arch project import plan.json --dry-run
105
+ arch project import plan.json
106
+ ```
107
+
108
+ See `arch_cli/work.py` for the file format.
109
+
110
+ ## Using ARCH-CLI from a Claude session
111
+
112
+ A project's Claude session (or any AI assistant working in a repository) keeps
113
+ that project's tasks and progress in ARCH-Insight itself, with an API key —
114
+ no browser sign-in.
115
+
116
+ **The owner, once per project:** Account > API keys > New key > **Claude
117
+ session**. That selects `read` and `projects:write` (projects, tasks and
118
+ progress notes — nothing else: no finance, members, billing or AI spending)
119
+ and no expiry. Name it after the project, e.g. `Claude (whatcha)`: that name
120
+ is who ARCH-Insight shows as having made the changes, in History, on task
121
+ notifications and on progress notes. Put the key in the project's vault scope
122
+ (e.g. `arch-secrets --scope <project>/dev push` with `ARCH_API_KEY=ai_live_...`)
123
+ and give the session that scope. Revoke the key when the project ends.
124
+
125
+ **The session:**
126
+
127
+ ```sh
128
+ export ARCH_API_KEY=ai_live_... # from the vault; never on the command line
129
+ arch whoami # key_name "Claude (whatcha)", scopes [read, projects:write]
130
+ arch project list
131
+ arch project create "whatcha" --priority high
132
+ arch task create "Ship 1.4 to the stores" --project-id 12 --due-date 2026-12-01
133
+ arch task update 41 --status in_progress
134
+ arch task note 41 "2026-11-17: Android build green; iOS waiting for review"
135
+ arch task update 41 --status done
136
+ arch project import plan.json --dry-run && arch project import plan.json
137
+ ```
138
+
139
+ A key cannot delete a project or a board (archive instead), cannot use the
140
+ AI helpers, and acts only inside the organisation it was made for; anything
141
+ else comes back as HTTP 403 with the reason.
142
+
143
+ ## Organisation
144
+
145
+ ```sh
146
+ arch org show # name, members, whether Entra sign-in is on
147
+ arch org entra show # the Redirect URI to register in Entra
148
+ ARCH_ENTRA_CLIENT_SECRET=... arch org entra set --tenant-id <Directory ID> --client-id <Application ID>
149
+ ```
150
+
151
+ With Entra sign-in on, members choose "Sign in with your organization" on the
152
+ login screen and type the organisation's name. `--domain` (a domain proven
153
+ under Organization -> Access) also sends that domain's addresses to Entra by
154
+ themselves. The secret is read from `ARCH_ENTRA_CLIENT_SECRET` or asked for,
155
+ never taken as an argument.
156
+
157
+ `arch login` prints the organisation it signed in to. A browser sign-in uses
158
+ the account that browser is signed in to; check it before importing.
159
+
160
+ ## Marketing e-mail
161
+
162
+ Contact lists drop malformed addresses and reserved domains (`example.com`,
163
+ `*.invalid`, `*.test`, ...) and duplicates, and say what they dropped:
164
+
165
+ ```sh
166
+ arch email-list create "Customers" --file customers.csv --exclude-domain mycompany.com
167
+ arch email-list create "Team" --members --dry-run
168
+ arch email-list add 4 --email new@customer.org
169
+ arch email-list export 4 --out customers.csv
170
+ ```
171
+
172
+ A campaign's own subject and bodies are the English base. Each recipient who
173
+ chose a language in ARCH-Insight gets that language's version when the
174
+ campaign has one, everyone else the base:
175
+
176
+ ```sh
177
+ arch marketing campaign create --name "Release 3.1" --subject "ARCH-Insight 3.1" \
178
+ --html release.html --text release.txt --list 4 --translations translations.json
179
+ arch marketing campaign preview 12 --language ja --out preview.html
180
+ arch marketing campaign test 12 --to me@mycompany.com --language ja # stays a draft
181
+ arch marketing campaign send 12 --yes
182
+ ```
183
+
184
+ `translations.json`:
185
+
186
+ ```json
187
+ {"ja": {"subject": "ARCH-Insight 3.1", "body_html_file": "release.ja.html", "body_text_file": "release.ja.txt"},
188
+ "de": {"subject": "ARCH-Insight 3.1 ist da"}}
189
+ ```
190
+
191
+ Set the logo shown at the top of every e-mail with `arch org logo logo.png`.
192
+
193
+ ## Finance
194
+
195
+ ```sh
196
+ arch finance accounts list
197
+ arch finance tx list --account 3 --type income --from 2026-10-01 --to 2026-10-31 --search acme
198
+ arch finance tx add --account 3 --type income --category Sales --buyer "ACME GmbH" \
199
+ --line "Consulting:2:500:19" --line "Travel:1:80:19"
200
+ arch finance tx import statement.csv --account 3 --dry-run # validate; nothing is booked
201
+ arch finance tx import statement.xlsx --account 3 --map category=5
202
+ ```
203
+
204
+ `tx import` uses the column mapping the server guesses, the same as the web
205
+ import; `--map field=index` (0-based, `field=` to drop a guess) corrects it.
206
+ Rows already booked are reported as duplicates rather than booked twice.
207
+
208
+ E-invoices (EN 16931: ZUGFeRD, XRechnung CII and UBL):
209
+
210
+ ```sh
211
+ arch finance invoice validate 41 --format xrechnung-cii # checks only; exits 1 when invalid
212
+ arch finance invoice issue 41 # RE-2026-00041.pdf (XML embedded)
213
+ arch finance invoice issue 41 --format xrechnung-ubl # RE-2026-00041.xml
214
+ arch finance invoice list --tx 41
215
+ arch finance invoice download 7 --as xml # the archived file, byte for byte
216
+ arch finance invoice credit-note 7 --reason "Wrong amount" # asks first; --yes in scripts
217
+ arch finance invoice bulk 41 42 43 --out october.zip
218
+ arch finance invoice send 41 --to ap@customer.example # issue and e-mail; asks first
219
+ arch finance invoice send --invoice 7 --to ap@customer.example --attach pdf_xml --yes
220
+ arch finance invoice import supplier-invoice.pdf # prints the draft, saves nothing
221
+ arch finance invoice import supplier-invoice.xml --account 3 # ... or books it
222
+ arch finance customers add --name "Stadt Musterhausen" --leitweg-id 991-12345-67 --email rechnung@stadt.example
223
+ ```
224
+
225
+ A transaction is invoiced once: `issue` assigns the next gap-free number and
226
+ archives the invoice, and issuing it again takes a credit note first. The
227
+ buyer is the transaction's customer unless `--buyer` says otherwise;
228
+ `--format` is passed to the server as given and, left out, the
229
+ organisation's default applies. In `send`, `{invoice_no}` in `--subject` is
230
+ replaced with the number.
231
+
232
+ Recurring invoices, issued (and, if you like, sent) by the server on a schedule:
233
+
234
+ ```sh
235
+ arch finance recurring add --name "Hosting" --customer 3 --account 6 \
236
+ --description "Hosting {month}" --line "Hosting:1:100:19" --preset monthly --start 2026-12-01 \
237
+ --send auto --to ap@customer.example # --preview shows the next dates first
238
+ arch finance recurring add --file schedule.json # the API's fields; flags override them
239
+ arch finance recurring list
240
+ arch finance recurring runs 9
241
+ arch finance recurring pause 9 / resume 9 / run 9 --yes / delete 9
242
+ arch finance sends list --status pending_approval # --send approval queues each e-mail
243
+ arch finance sends approve 12
244
+ ```
245
+
246
+ For automation, sign in with an API key (`ARCH_API_KEY=ai_live_...` in the
247
+ environment) and pass `--yes` to commands that would otherwise ask. Every
248
+ command prints JSON and exits non-zero on failure. An API key needs `read` to
249
+ list, `finance:write` to add or import transactions and `finance:invoice` to
250
+ issue, send or schedule invoices.
251
+
252
+ ## Secrets
253
+
254
+ The dedicated `arch-secrets` command remains available. The same functionality
255
+ can be reached through `arch secrets`:
256
+
257
+ ```sh
258
+ export ARCH_SECRETS_TOKEN='your-vault-token'
259
+ arch secrets run -- npm start
260
+ arch secrets export > .env
261
+ arch secrets push .env
262
+ ```
263
+
264
+ The vault token is scoped independently from the user access token used by
265
+ product commands.
@@ -0,0 +1,257 @@
1
+ # arch-cli
2
+
3
+ `arch-cli` is the ARCH-Insight command-line client. It includes commands for
4
+ working with the product API, importing architecture data, and using the
5
+ secrets vault.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ python -m pip install arch-insight-cli
11
+ ```
12
+
13
+ The installed command is `arch` (also available as `arch-cli`). Python 3.9 or
14
+ newer is required.
15
+
16
+ ## Sign in
17
+
18
+ ```sh
19
+ arch login # opens the browser; MFA and consent as for any connected app
20
+ arch login --email you@example.com # unattended: password from ARCH_PASSWORD, or asked for
21
+ arch whoami
22
+ arch logout
23
+ ```
24
+
25
+ The session is stored for your user (`%APPDATA%\arch-insight\credentials.json`
26
+ on Windows, `~/.config/arch-insight/credentials.json` elsewhere, readable by
27
+ you only) and refreshed automatically, so scheduled jobs keep working.
28
+ `ARCH_ACCESS_TOKEN` or `--token` still override it. Set
29
+ `ARCH_API_URL` for a self-hosted deployment (default `https://arch-insight.com`)
30
+ and, if its sign-in is not at `auth.<host>`, `ARCH_AUTH_URL`.
31
+
32
+ ### API keys
33
+
34
+ For scripts and CI, create a personal API key under **Account > API keys**:
35
+ it belongs to one organisation, carries only the scopes you chose (`read`, `projects:write`,
36
+ `finance:write`, `finance:invoice`, ...) and is shown once, starting with
37
+ `ai_live_`.
38
+
39
+ ```sh
40
+ export ARCH_API_KEY=ai_live_... # used as is, nothing stored
41
+ arch login --api-key # or check it and store it (read from ARCH_API_KEY, or asked for)
42
+ arch whoami # shows the key as ai_live_...last4, never in full
43
+ ```
44
+
45
+ Order of precedence: `--token`, `ARCH_ACCESS_TOKEN`, `ARCH_API_KEY`, then
46
+ what `arch login` stored. A key cannot manage keys, billing or members; a
47
+ missing scope comes back as an HTTP 403 with the reason.
48
+
49
+ ## Tasks
50
+
51
+ ```sh
52
+ arch task create "Review database costs" \
53
+ --description "Check the quarterly forecast" \
54
+ --project-id 12 --board-id 4 --priority high \
55
+ --assignee "Alex Example" --due-date 2026-12-01
56
+
57
+ arch task list --project-id 12
58
+ ```
59
+
60
+ The create command prints the created task as JSON. Repeat `--assignee` to
61
+ assign more than one person.
62
+
63
+ ## Fact sheets
64
+
65
+ Create one fact sheet from JSON, import one or more JSON objects, or import an
66
+ ARCH-Insight ZIP export:
67
+
68
+ ```sh
69
+ arch factsheet create application.json
70
+ arch factsheet import fact-sheets.json
71
+ arch factsheet import archi_insight_export.zip
72
+ arch factsheet list
73
+ ```
74
+
75
+ JSON imports create rows one at a time through the same API used by the web
76
+ app. If an item fails, earlier successful items remain created. ZIP imports use
77
+ the application's import endpoint and report imported and skipped entries.
78
+
79
+ ## Projects, tasks, tickets and notes
80
+
81
+ ```sh
82
+ arch project list
83
+ arch project create "Webshop" --priority high
84
+ arch task create "Release Stripe production account" --project-id 12 --assignee st@example.com --due-date 2026-09-14
85
+ arch task update 41 --status in_review
86
+ arch ticket create "Alfen box offline" --message "Since 2026-09-14 after reset" --priority high
87
+ arch ticket reply 7 --message "2026-09-15: back online after factory reset"
88
+ arch document create "Meeting 2026-10-05" --file minutes.md --folder "Change Control Board"
89
+ ```
90
+
91
+ Move a whole list in at once -- projects, their tasks, a dated status log
92
+ kept as a ticket, and notes -- from one JSON file. Re-running it creates
93
+ nothing twice:
94
+
95
+ ```sh
96
+ arch project import plan.json --dry-run
97
+ arch project import plan.json
98
+ ```
99
+
100
+ See `arch_cli/work.py` for the file format.
101
+
102
+ ## Using ARCH-CLI from a Claude session
103
+
104
+ A project's Claude session (or any AI assistant working in a repository) keeps
105
+ that project's tasks and progress in ARCH-Insight itself, with an API key —
106
+ no browser sign-in.
107
+
108
+ **The owner, once per project:** Account > API keys > New key > **Claude
109
+ session**. That selects `read` and `projects:write` (projects, tasks and
110
+ progress notes — nothing else: no finance, members, billing or AI spending)
111
+ and no expiry. Name it after the project, e.g. `Claude (whatcha)`: that name
112
+ is who ARCH-Insight shows as having made the changes, in History, on task
113
+ notifications and on progress notes. Put the key in the project's vault scope
114
+ (e.g. `arch-secrets --scope <project>/dev push` with `ARCH_API_KEY=ai_live_...`)
115
+ and give the session that scope. Revoke the key when the project ends.
116
+
117
+ **The session:**
118
+
119
+ ```sh
120
+ export ARCH_API_KEY=ai_live_... # from the vault; never on the command line
121
+ arch whoami # key_name "Claude (whatcha)", scopes [read, projects:write]
122
+ arch project list
123
+ arch project create "whatcha" --priority high
124
+ arch task create "Ship 1.4 to the stores" --project-id 12 --due-date 2026-12-01
125
+ arch task update 41 --status in_progress
126
+ arch task note 41 "2026-11-17: Android build green; iOS waiting for review"
127
+ arch task update 41 --status done
128
+ arch project import plan.json --dry-run && arch project import plan.json
129
+ ```
130
+
131
+ A key cannot delete a project or a board (archive instead), cannot use the
132
+ AI helpers, and acts only inside the organisation it was made for; anything
133
+ else comes back as HTTP 403 with the reason.
134
+
135
+ ## Organisation
136
+
137
+ ```sh
138
+ arch org show # name, members, whether Entra sign-in is on
139
+ arch org entra show # the Redirect URI to register in Entra
140
+ ARCH_ENTRA_CLIENT_SECRET=... arch org entra set --tenant-id <Directory ID> --client-id <Application ID>
141
+ ```
142
+
143
+ With Entra sign-in on, members choose "Sign in with your organization" on the
144
+ login screen and type the organisation's name. `--domain` (a domain proven
145
+ under Organization -> Access) also sends that domain's addresses to Entra by
146
+ themselves. The secret is read from `ARCH_ENTRA_CLIENT_SECRET` or asked for,
147
+ never taken as an argument.
148
+
149
+ `arch login` prints the organisation it signed in to. A browser sign-in uses
150
+ the account that browser is signed in to; check it before importing.
151
+
152
+ ## Marketing e-mail
153
+
154
+ Contact lists drop malformed addresses and reserved domains (`example.com`,
155
+ `*.invalid`, `*.test`, ...) and duplicates, and say what they dropped:
156
+
157
+ ```sh
158
+ arch email-list create "Customers" --file customers.csv --exclude-domain mycompany.com
159
+ arch email-list create "Team" --members --dry-run
160
+ arch email-list add 4 --email new@customer.org
161
+ arch email-list export 4 --out customers.csv
162
+ ```
163
+
164
+ A campaign's own subject and bodies are the English base. Each recipient who
165
+ chose a language in ARCH-Insight gets that language's version when the
166
+ campaign has one, everyone else the base:
167
+
168
+ ```sh
169
+ arch marketing campaign create --name "Release 3.1" --subject "ARCH-Insight 3.1" \
170
+ --html release.html --text release.txt --list 4 --translations translations.json
171
+ arch marketing campaign preview 12 --language ja --out preview.html
172
+ arch marketing campaign test 12 --to me@mycompany.com --language ja # stays a draft
173
+ arch marketing campaign send 12 --yes
174
+ ```
175
+
176
+ `translations.json`:
177
+
178
+ ```json
179
+ {"ja": {"subject": "ARCH-Insight 3.1", "body_html_file": "release.ja.html", "body_text_file": "release.ja.txt"},
180
+ "de": {"subject": "ARCH-Insight 3.1 ist da"}}
181
+ ```
182
+
183
+ Set the logo shown at the top of every e-mail with `arch org logo logo.png`.
184
+
185
+ ## Finance
186
+
187
+ ```sh
188
+ arch finance accounts list
189
+ arch finance tx list --account 3 --type income --from 2026-10-01 --to 2026-10-31 --search acme
190
+ arch finance tx add --account 3 --type income --category Sales --buyer "ACME GmbH" \
191
+ --line "Consulting:2:500:19" --line "Travel:1:80:19"
192
+ arch finance tx import statement.csv --account 3 --dry-run # validate; nothing is booked
193
+ arch finance tx import statement.xlsx --account 3 --map category=5
194
+ ```
195
+
196
+ `tx import` uses the column mapping the server guesses, the same as the web
197
+ import; `--map field=index` (0-based, `field=` to drop a guess) corrects it.
198
+ Rows already booked are reported as duplicates rather than booked twice.
199
+
200
+ E-invoices (EN 16931: ZUGFeRD, XRechnung CII and UBL):
201
+
202
+ ```sh
203
+ arch finance invoice validate 41 --format xrechnung-cii # checks only; exits 1 when invalid
204
+ arch finance invoice issue 41 # RE-2026-00041.pdf (XML embedded)
205
+ arch finance invoice issue 41 --format xrechnung-ubl # RE-2026-00041.xml
206
+ arch finance invoice list --tx 41
207
+ arch finance invoice download 7 --as xml # the archived file, byte for byte
208
+ arch finance invoice credit-note 7 --reason "Wrong amount" # asks first; --yes in scripts
209
+ arch finance invoice bulk 41 42 43 --out october.zip
210
+ arch finance invoice send 41 --to ap@customer.example # issue and e-mail; asks first
211
+ arch finance invoice send --invoice 7 --to ap@customer.example --attach pdf_xml --yes
212
+ arch finance invoice import supplier-invoice.pdf # prints the draft, saves nothing
213
+ arch finance invoice import supplier-invoice.xml --account 3 # ... or books it
214
+ arch finance customers add --name "Stadt Musterhausen" --leitweg-id 991-12345-67 --email rechnung@stadt.example
215
+ ```
216
+
217
+ A transaction is invoiced once: `issue` assigns the next gap-free number and
218
+ archives the invoice, and issuing it again takes a credit note first. The
219
+ buyer is the transaction's customer unless `--buyer` says otherwise;
220
+ `--format` is passed to the server as given and, left out, the
221
+ organisation's default applies. In `send`, `{invoice_no}` in `--subject` is
222
+ replaced with the number.
223
+
224
+ Recurring invoices, issued (and, if you like, sent) by the server on a schedule:
225
+
226
+ ```sh
227
+ arch finance recurring add --name "Hosting" --customer 3 --account 6 \
228
+ --description "Hosting {month}" --line "Hosting:1:100:19" --preset monthly --start 2026-12-01 \
229
+ --send auto --to ap@customer.example # --preview shows the next dates first
230
+ arch finance recurring add --file schedule.json # the API's fields; flags override them
231
+ arch finance recurring list
232
+ arch finance recurring runs 9
233
+ arch finance recurring pause 9 / resume 9 / run 9 --yes / delete 9
234
+ arch finance sends list --status pending_approval # --send approval queues each e-mail
235
+ arch finance sends approve 12
236
+ ```
237
+
238
+ For automation, sign in with an API key (`ARCH_API_KEY=ai_live_...` in the
239
+ environment) and pass `--yes` to commands that would otherwise ask. Every
240
+ command prints JSON and exits non-zero on failure. An API key needs `read` to
241
+ list, `finance:write` to add or import transactions and `finance:invoice` to
242
+ issue, send or schedule invoices.
243
+
244
+ ## Secrets
245
+
246
+ The dedicated `arch-secrets` command remains available. The same functionality
247
+ can be reached through `arch secrets`:
248
+
249
+ ```sh
250
+ export ARCH_SECRETS_TOKEN='your-vault-token'
251
+ arch secrets run -- npm start
252
+ arch secrets export > .env
253
+ arch secrets push .env
254
+ ```
255
+
256
+ The vault token is scoped independently from the user access token used by
257
+ product commands.
@@ -1,3 +1,3 @@
1
1
  """ARCH-Insight command-line client."""
2
2
 
3
- __version__ = "0.4.2"
3
+ __version__ = "0.6.0"
@@ -10,6 +10,10 @@ Two ways, both ending in a refreshable session stored for this user:
10
10
  * `arch login --email you@example.com` -- unattended (CI, cron). The password
11
11
  comes from ARCH_PASSWORD, or is asked for; it is never an argument, because
12
12
  every argument of every process is readable through `ps`.
13
+ * `arch login --api-key` -- a personal API key (`ai_live_...`, issue #1090),
14
+ created under Account > API keys for one organisation and limited to the
15
+ scopes chosen there. Read from ARCH_API_KEY or asked for, never an
16
+ argument. ARCH_API_KEY set in the environment is used without storing it.
13
17
 
14
18
  The session is kept in the user's config directory, readable by its owner
15
19
  only, and refreshed before it expires, so a scheduled job keeps working past
@@ -146,8 +150,17 @@ def _store(api: str, auth: str, tokens: dict, **extra) -> dict:
146
150
  def login_password(api: str, email: str) -> dict:
147
151
  password = os.environ.get("ARCH_PASSWORD") or getpass.getpass(f"Password for {email}: ")
148
152
  auth = auth_url(api)
149
- tokens = _http("POST", auth + "/token?grant_type=password",
150
- body={"email": email, "password": password})
153
+ try:
154
+ tokens = _http("POST", auth + "/token?grant_type=password",
155
+ body={"email": email, "password": password})
156
+ except AuthError as exc:
157
+ # The sign-in service checks a captcha on password sign-in (it stops
158
+ # bots guessing passwords), which a terminal cannot solve.
159
+ if "captcha" in str(exc).lower():
160
+ raise AuthError("Password sign-in from the terminal is blocked by the sign-in "
161
+ "service's captcha. Run `arch login` (without --email) to sign in "
162
+ "in the browser instead.") from exc
163
+ raise
151
164
  return _store(api, auth, tokens, kind="password", email=email)
152
165
 
153
166
 
@@ -256,12 +269,51 @@ def _refresh(api: str, record: dict) -> dict:
256
269
  return _store(api, auth, tokens, **extra)
257
270
 
258
271
 
272
+ API_KEY_PREFIX = "ai_"
273
+
274
+
275
+ def is_api_key(token: str | None) -> bool:
276
+ return bool(token) and token.startswith(API_KEY_PREFIX)
277
+
278
+
279
+ def mask(token: str | None) -> str:
280
+ """Enough of a key to tell which one it is -- its prefix and last four,
281
+ as the Account page shows it -- and nothing that would let it be used."""
282
+ if not token:
283
+ return ""
284
+ head = token[:len("ai_live_")] if token.startswith("ai_live_") else token[:3]
285
+ return f"{head}...{token[-4:]}" if len(token) > len(head) + 4 else head + "..."
286
+
287
+
288
+ def store_api_key(api: str, key: str) -> dict:
289
+ """Keep an API key for this API in place of a session. Nothing to refresh:
290
+ it works until it expires or is revoked under Account > API keys."""
291
+ key = (key or "").strip()
292
+ if not is_api_key(key):
293
+ raise AuthError("That is not an ARCH-Insight API key (they start with ai_live_).")
294
+ record = {"kind": "api_key", "api_key": key}
295
+ data = _load_all()
296
+ data[_key(api)] = record
297
+ _save_all(data)
298
+ return record
299
+
300
+
301
+ def read_api_key() -> str:
302
+ return (os.environ.get("ARCH_API_KEY") or getpass.getpass("API key: ")).strip()
303
+
304
+
305
+ def stored_record(api: str) -> dict | None:
306
+ return _load_all().get(_key(api))
307
+
308
+
259
309
  def stored_token(api: str) -> str | None:
260
- """The stored session's access token, refreshed when it is about to
261
- expire, or None when this API has no stored session."""
310
+ """The stored credential for this API: an API key as it is, a session's
311
+ access token refreshed when it is about to expire; None without either."""
262
312
  record = _load_all().get(_key(api))
263
313
  if not record:
264
314
  return None
315
+ if record.get("kind") == "api_key":
316
+ return record.get("api_key")
265
317
  if record.get("expires_at", 0) - 60 <= time.time():
266
318
  record = _refresh(api, record)
267
319
  return record["access_token"]