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.
- arch_insight_cli-0.6.0/PKG-INFO +265 -0
- arch_insight_cli-0.6.0/README.md +257 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/__init__.py +1 -1
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/auth.py +56 -4
- arch_insight_cli-0.6.0/arch_cli/finance.py +706 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/main.py +113 -83
- arch_insight_cli-0.6.0/arch_insight_cli.egg-info/PKG-INFO +265 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/SOURCES.txt +4 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/pyproject.toml +2 -2
- arch_insight_cli-0.6.0/tests/test_auth_captcha.py +29 -0
- arch_insight_cli-0.6.0/tests/test_claude_session.py +46 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/tests/test_comms.py +29 -0
- arch_insight_cli-0.6.0/tests/test_finance.py +360 -0
- arch_insight_cli-0.4.2/PKG-INFO +0 -171
- arch_insight_cli-0.4.2/README.md +0 -163
- arch_insight_cli-0.4.2/arch_insight_cli.egg-info/PKG-INFO +0 -171
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/comms.py +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_cli/work.py +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/dependency_links.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/entry_points.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/requires.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/arch_insight_cli.egg-info/top_level.txt +0 -0
- {arch_insight_cli-0.4.2 → arch_insight_cli-0.6.0}/setup.cfg +0 -0
- {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.
|
|
@@ -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
|
-
|
|
150
|
-
|
|
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
|
|
261
|
-
|
|
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"]
|