arch-insight-cli 0.4.2__tar.gz → 0.5.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 (19) hide show
  1. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/PKG-INFO +81 -20
  2. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/README.md +79 -18
  3. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/__init__.py +1 -1
  4. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/auth.py +45 -2
  5. arch_insight_cli-0.5.0/arch_cli/finance.py +706 -0
  6. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/main.py +70 -83
  7. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/PKG-INFO +81 -20
  8. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/SOURCES.txt +2 -0
  9. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/pyproject.toml +2 -2
  10. arch_insight_cli-0.5.0/tests/test_finance.py +360 -0
  11. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/comms.py +0 -0
  12. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/work.py +0 -0
  13. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/dependency_links.txt +0 -0
  14. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/entry_points.txt +0 -0
  15. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/requires.txt +0 -0
  16. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/top_level.txt +0 -0
  17. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/setup.cfg +0 -0
  18. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/tests/test_comms.py +0 -0
  19. {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/tests/test_work.py +0 -0
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: arch-insight-cli
3
- Version: 0.4.2
4
- Summary: Command-line client for ARCH-Insight tasks, factsheets, secrets, and developer platform.
3
+ Version: 0.5.0
4
+ Summary: Command-line client for ARCH-Insight tasks, factsheets and secrets.
5
5
  Requires-Python: >=3.10
6
6
  Description-Content-Type: text/markdown
7
7
  Requires-Dist: arch-secrets>=1.1.2
@@ -9,8 +9,8 @@ Requires-Dist: arch-secrets>=1.1.2
9
9
  # arch-cli
10
10
 
11
11
  `arch-cli` is the ARCH-Insight command-line client. It includes commands for
12
- working with the product API, importing architecture data, managing the
13
- developer platform, and using the secrets vault.
12
+ working with the product API, importing architecture data, and using the
13
+ secrets vault.
14
14
 
15
15
  ## Install
16
16
 
@@ -33,11 +33,27 @@ arch logout
33
33
  The session is stored for your user (`%APPDATA%\arch-insight\credentials.json`
34
34
  on Windows, `~/.config/arch-insight/credentials.json` elsewhere, readable by
35
35
  you only) and refreshed automatically, so scheduled jobs keep working.
36
- `ARCH_ACCESS_TOKEN` or `--token` still override it. Developer-platform
37
- commands also accept the platform token through `ARCH_TOKEN`. Set
36
+ `ARCH_ACCESS_TOKEN` or `--token` still override it. Set
38
37
  `ARCH_API_URL` for a self-hosted deployment (default `https://arch-insight.com`)
39
38
  and, if its sign-in is not at `auth.<host>`, `ARCH_AUTH_URL`.
40
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`,
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
+
41
57
  ## Tasks
42
58
 
43
59
  ```sh
@@ -141,6 +157,65 @@ arch marketing campaign send 12 --yes
141
157
 
142
158
  Set the logo shown at the top of every e-mail with `arch org logo logo.png`.
143
159
 
160
+ ## Finance
161
+
162
+ ```sh
163
+ arch finance accounts list
164
+ arch finance tx list --account 3 --type income --from 2026-10-01 --to 2026-10-31 --search acme
165
+ arch finance tx add --account 3 --type income --category Sales --buyer "ACME GmbH" \
166
+ --line "Consulting:2:500:19" --line "Travel:1:80:19"
167
+ arch finance tx import statement.csv --account 3 --dry-run # validate; nothing is booked
168
+ arch finance tx import statement.xlsx --account 3 --map category=5
169
+ ```
170
+
171
+ `tx import` uses the column mapping the server guesses, the same as the web
172
+ import; `--map field=index` (0-based, `field=` to drop a guess) corrects it.
173
+ Rows already booked are reported as duplicates rather than booked twice.
174
+
175
+ E-invoices (EN 16931: ZUGFeRD, XRechnung CII and UBL):
176
+
177
+ ```sh
178
+ arch finance invoice validate 41 --format xrechnung-cii # checks only; exits 1 when invalid
179
+ arch finance invoice issue 41 # RE-2026-00041.pdf (XML embedded)
180
+ arch finance invoice issue 41 --format xrechnung-ubl # RE-2026-00041.xml
181
+ arch finance invoice list --tx 41
182
+ arch finance invoice download 7 --as xml # the archived file, byte for byte
183
+ arch finance invoice credit-note 7 --reason "Wrong amount" # asks first; --yes in scripts
184
+ arch finance invoice bulk 41 42 43 --out october.zip
185
+ arch finance invoice send 41 --to ap@customer.example # issue and e-mail; asks first
186
+ arch finance invoice send --invoice 7 --to ap@customer.example --attach pdf_xml --yes
187
+ arch finance invoice import supplier-invoice.pdf # prints the draft, saves nothing
188
+ arch finance invoice import supplier-invoice.xml --account 3 # ... or books it
189
+ arch finance customers add --name "Stadt Musterhausen" --leitweg-id 991-12345-67 --email rechnung@stadt.example
190
+ ```
191
+
192
+ A transaction is invoiced once: `issue` assigns the next gap-free number and
193
+ archives the invoice, and issuing it again takes a credit note first. The
194
+ buyer is the transaction's customer unless `--buyer` says otherwise;
195
+ `--format` is passed to the server as given and, left out, the
196
+ organisation's default applies. In `send`, `{invoice_no}` in `--subject` is
197
+ replaced with the number.
198
+
199
+ Recurring invoices, issued (and, if you like, sent) by the server on a schedule:
200
+
201
+ ```sh
202
+ arch finance recurring add --name "Hosting" --customer 3 --account 6 \
203
+ --description "Hosting {month}" --line "Hosting:1:100:19" --preset monthly --start 2026-12-01 \
204
+ --send auto --to ap@customer.example # --preview shows the next dates first
205
+ arch finance recurring add --file schedule.json # the API's fields; flags override them
206
+ arch finance recurring list
207
+ arch finance recurring runs 9
208
+ arch finance recurring pause 9 / resume 9 / run 9 --yes / delete 9
209
+ arch finance sends list --status pending_approval # --send approval queues each e-mail
210
+ arch finance sends approve 12
211
+ ```
212
+
213
+ For automation, sign in with an API key (`ARCH_API_KEY=ai_live_...` in the
214
+ environment) and pass `--yes` to commands that would otherwise ask. Every
215
+ command prints JSON and exits non-zero on failure. An API key needs `read` to
216
+ list, `finance:write` to add or import transactions and `finance:invoice` to
217
+ issue, send or schedule invoices.
218
+
144
219
  ## Secrets
145
220
 
146
221
  The dedicated `arch-secrets` command remains available. The same functionality
@@ -155,17 +230,3 @@ arch secrets push .env
155
230
 
156
231
  The vault token is scoped independently from the user access token used by
157
232
  product commands.
158
-
159
- ## Developer platform
160
-
161
- ```sh
162
- arch repo list
163
- arch repo create team/sample --description "Example repository"
164
- arch pipeline list --repo 12
165
- arch pipeline show 42
166
- arch pipeline logs 99
167
- arch registry list
168
- arch registry tags team/sample
169
- arch runner list
170
- arch deploy list production
171
- ```
@@ -1,8 +1,8 @@
1
1
  # arch-cli
2
2
 
3
3
  `arch-cli` is the ARCH-Insight command-line client. It includes commands for
4
- working with the product API, importing architecture data, managing the
5
- developer platform, and using the secrets vault.
4
+ working with the product API, importing architecture data, and using the
5
+ secrets vault.
6
6
 
7
7
  ## Install
8
8
 
@@ -25,11 +25,27 @@ arch logout
25
25
  The session is stored for your user (`%APPDATA%\arch-insight\credentials.json`
26
26
  on Windows, `~/.config/arch-insight/credentials.json` elsewhere, readable by
27
27
  you only) and refreshed automatically, so scheduled jobs keep working.
28
- `ARCH_ACCESS_TOKEN` or `--token` still override it. Developer-platform
29
- commands also accept the platform token through `ARCH_TOKEN`. Set
28
+ `ARCH_ACCESS_TOKEN` or `--token` still override it. Set
30
29
  `ARCH_API_URL` for a self-hosted deployment (default `https://arch-insight.com`)
31
30
  and, if its sign-in is not at `auth.<host>`, `ARCH_AUTH_URL`.
32
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`,
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
+
33
49
  ## Tasks
34
50
 
35
51
  ```sh
@@ -133,6 +149,65 @@ arch marketing campaign send 12 --yes
133
149
 
134
150
  Set the logo shown at the top of every e-mail with `arch org logo logo.png`.
135
151
 
152
+ ## Finance
153
+
154
+ ```sh
155
+ arch finance accounts list
156
+ arch finance tx list --account 3 --type income --from 2026-10-01 --to 2026-10-31 --search acme
157
+ arch finance tx add --account 3 --type income --category Sales --buyer "ACME GmbH" \
158
+ --line "Consulting:2:500:19" --line "Travel:1:80:19"
159
+ arch finance tx import statement.csv --account 3 --dry-run # validate; nothing is booked
160
+ arch finance tx import statement.xlsx --account 3 --map category=5
161
+ ```
162
+
163
+ `tx import` uses the column mapping the server guesses, the same as the web
164
+ import; `--map field=index` (0-based, `field=` to drop a guess) corrects it.
165
+ Rows already booked are reported as duplicates rather than booked twice.
166
+
167
+ E-invoices (EN 16931: ZUGFeRD, XRechnung CII and UBL):
168
+
169
+ ```sh
170
+ arch finance invoice validate 41 --format xrechnung-cii # checks only; exits 1 when invalid
171
+ arch finance invoice issue 41 # RE-2026-00041.pdf (XML embedded)
172
+ arch finance invoice issue 41 --format xrechnung-ubl # RE-2026-00041.xml
173
+ arch finance invoice list --tx 41
174
+ arch finance invoice download 7 --as xml # the archived file, byte for byte
175
+ arch finance invoice credit-note 7 --reason "Wrong amount" # asks first; --yes in scripts
176
+ arch finance invoice bulk 41 42 43 --out october.zip
177
+ arch finance invoice send 41 --to ap@customer.example # issue and e-mail; asks first
178
+ arch finance invoice send --invoice 7 --to ap@customer.example --attach pdf_xml --yes
179
+ arch finance invoice import supplier-invoice.pdf # prints the draft, saves nothing
180
+ arch finance invoice import supplier-invoice.xml --account 3 # ... or books it
181
+ arch finance customers add --name "Stadt Musterhausen" --leitweg-id 991-12345-67 --email rechnung@stadt.example
182
+ ```
183
+
184
+ A transaction is invoiced once: `issue` assigns the next gap-free number and
185
+ archives the invoice, and issuing it again takes a credit note first. The
186
+ buyer is the transaction's customer unless `--buyer` says otherwise;
187
+ `--format` is passed to the server as given and, left out, the
188
+ organisation's default applies. In `send`, `{invoice_no}` in `--subject` is
189
+ replaced with the number.
190
+
191
+ Recurring invoices, issued (and, if you like, sent) by the server on a schedule:
192
+
193
+ ```sh
194
+ arch finance recurring add --name "Hosting" --customer 3 --account 6 \
195
+ --description "Hosting {month}" --line "Hosting:1:100:19" --preset monthly --start 2026-12-01 \
196
+ --send auto --to ap@customer.example # --preview shows the next dates first
197
+ arch finance recurring add --file schedule.json # the API's fields; flags override them
198
+ arch finance recurring list
199
+ arch finance recurring runs 9
200
+ arch finance recurring pause 9 / resume 9 / run 9 --yes / delete 9
201
+ arch finance sends list --status pending_approval # --send approval queues each e-mail
202
+ arch finance sends approve 12
203
+ ```
204
+
205
+ For automation, sign in with an API key (`ARCH_API_KEY=ai_live_...` in the
206
+ environment) and pass `--yes` to commands that would otherwise ask. Every
207
+ command prints JSON and exits non-zero on failure. An API key needs `read` to
208
+ list, `finance:write` to add or import transactions and `finance:invoice` to
209
+ issue, send or schedule invoices.
210
+
136
211
  ## Secrets
137
212
 
138
213
  The dedicated `arch-secrets` command remains available. The same functionality
@@ -147,17 +222,3 @@ arch secrets push .env
147
222
 
148
223
  The vault token is scoped independently from the user access token used by
149
224
  product commands.
150
-
151
- ## Developer platform
152
-
153
- ```sh
154
- arch repo list
155
- arch repo create team/sample --description "Example repository"
156
- arch pipeline list --repo 12
157
- arch pipeline show 42
158
- arch pipeline logs 99
159
- arch registry list
160
- arch registry tags team/sample
161
- arch runner list
162
- arch deploy list production
163
- ```
@@ -1,3 +1,3 @@
1
1
  """ARCH-Insight command-line client."""
2
2
 
3
- __version__ = "0.4.2"
3
+ __version__ = "0.5.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
@@ -256,12 +260,51 @@ def _refresh(api: str, record: dict) -> dict:
256
260
  return _store(api, auth, tokens, **extra)
257
261
 
258
262
 
263
+ API_KEY_PREFIX = "ai_"
264
+
265
+
266
+ def is_api_key(token: str | None) -> bool:
267
+ return bool(token) and token.startswith(API_KEY_PREFIX)
268
+
269
+
270
+ def mask(token: str | None) -> str:
271
+ """Enough of a key to tell which one it is -- its prefix and last four,
272
+ as the Account page shows it -- and nothing that would let it be used."""
273
+ if not token:
274
+ return ""
275
+ head = token[:len("ai_live_")] if token.startswith("ai_live_") else token[:3]
276
+ return f"{head}...{token[-4:]}" if len(token) > len(head) + 4 else head + "..."
277
+
278
+
279
+ def store_api_key(api: str, key: str) -> dict:
280
+ """Keep an API key for this API in place of a session. Nothing to refresh:
281
+ it works until it expires or is revoked under Account > API keys."""
282
+ key = (key or "").strip()
283
+ if not is_api_key(key):
284
+ raise AuthError("That is not an ARCH-Insight API key (they start with ai_live_).")
285
+ record = {"kind": "api_key", "api_key": key}
286
+ data = _load_all()
287
+ data[_key(api)] = record
288
+ _save_all(data)
289
+ return record
290
+
291
+
292
+ def read_api_key() -> str:
293
+ return (os.environ.get("ARCH_API_KEY") or getpass.getpass("API key: ")).strip()
294
+
295
+
296
+ def stored_record(api: str) -> dict | None:
297
+ return _load_all().get(_key(api))
298
+
299
+
259
300
  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."""
301
+ """The stored credential for this API: an API key as it is, a session's
302
+ access token refreshed when it is about to expire; None without either."""
262
303
  record = _load_all().get(_key(api))
263
304
  if not record:
264
305
  return None
306
+ if record.get("kind") == "api_key":
307
+ return record.get("api_key")
265
308
  if record.get("expires_at", 0) - 60 <= time.time():
266
309
  record = _refresh(api, record)
267
310
  return record["access_token"]