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.
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/PKG-INFO +81 -20
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/README.md +79 -18
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/__init__.py +1 -1
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/auth.py +45 -2
- arch_insight_cli-0.5.0/arch_cli/finance.py +706 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/main.py +70 -83
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/PKG-INFO +81 -20
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/SOURCES.txt +2 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/pyproject.toml +2 -2
- arch_insight_cli-0.5.0/tests/test_finance.py +360 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/comms.py +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_cli/work.py +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/dependency_links.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/entry_points.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/requires.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/arch_insight_cli.egg-info/top_level.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/setup.cfg +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.5.0}/tests/test_comms.py +0 -0
- {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
|
-
Summary: Command-line client for ARCH-Insight tasks, factsheets
|
|
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,
|
|
13
|
-
|
|
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.
|
|
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,
|
|
5
|
-
|
|
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.
|
|
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
|
-
```
|
|
@@ -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
|
|
261
|
-
|
|
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"]
|