arch-cli

arch-cli is the ARCH-Insight command-line client. It includes commands for working with the product API, importing architecture data, managing the developer platform, and using the secrets vault.

Install

python -m pip install arch-insight-cli

The installed command is arch (also available as arch-cli). Python 3.9 or newer is required.

Sign in

arch login                               # opens the browser; MFA and consent as for any connected app
arch login --email you@example.com       # unattended: password from ARCH_PASSWORD, or asked for
arch whoami
arch logout

The session is stored for your user (%APPDATA%\arch-insight\credentials.json on Windows, ~/.config/arch-insight/credentials.json elsewhere, readable by you only) and refreshed automatically, so scheduled jobs keep working. ARCH_ACCESS_TOKEN or --token still override it. Developer-platform commands also accept the platform token through ARCH_TOKEN. Set ARCH_API_URL for a self-hosted deployment (default https://arch-insight.com) and, if its sign-in is not at auth.<host>, ARCH_AUTH_URL.

Tasks

arch task create "Review database costs" \
  --description "Check the quarterly forecast" \
  --project-id 12 --board-id 4 --priority high \
  --assignee "Alex Example" --due-date 2026-12-01

arch task list --project-id 12

The create command prints the created task as JSON. Repeat --assignee to assign more than one person.

Fact sheets

Create one fact sheet from JSON, import one or more JSON objects, or import an ARCH-Insight ZIP export:

arch factsheet create application.json
arch factsheet import fact-sheets.json
arch factsheet import archi_insight_export.zip
arch factsheet list

JSON imports create rows one at a time through the same API used by the web app. If an item fails, earlier successful items remain created. ZIP imports use the application's import endpoint and report imported and skipped entries.

Projects, tasks, tickets and notes

arch project list
arch project create "Webshop" --priority high
arch task create "Release Stripe production account" --project-id 12 --assignee st@example.com --due-date 2026-09-14
arch task update 41 --status in_review
arch ticket create "Alfen box offline" --message "Since 2026-09-14 after reset" --priority high
arch ticket reply 7 --message "2026-09-15: back online after factory reset"
arch document create "Meeting 2026-10-05" --file minutes.md --folder "Change Control Board"

Move a whole list in at once -- projects, their tasks, a dated status log kept as a ticket, and notes -- from one JSON file. Re-running it creates nothing twice:

arch project import plan.json --dry-run
arch project import plan.json

See arch_cli/work.py for the file format.

Organisation

arch org show                 # name, members, whether Entra sign-in is on
arch org entra show           # the Redirect URI to register in Entra
ARCH_ENTRA_CLIENT_SECRET=... arch org entra set --tenant-id <Directory ID> --client-id <Application ID>

With Entra sign-in on, members choose "Sign in with your organization" on the login screen and type the organisation's name. --domain (a domain proven under Organization -> Access) also sends that domain's addresses to Entra by themselves. The secret is read from ARCH_ENTRA_CLIENT_SECRET or asked for, never taken as an argument.

arch login prints the organisation it signed in to. A browser sign-in uses the account that browser is signed in to; check it before importing.

Marketing e-mail

Contact lists drop malformed addresses and reserved domains (example.com, *.invalid, *.test, ...) and duplicates, and say what they dropped:

arch email-list create "Customers" --file customers.csv --exclude-domain mycompany.com
arch email-list create "Team" --members --dry-run
arch email-list add 4 --email new@customer.org
arch email-list export 4 --out customers.csv

A campaign's own subject and bodies are the English base. Each recipient who chose a language in ARCH-Insight gets that language's version when the campaign has one, everyone else the base:

arch marketing campaign create --name "Release 3.1" --subject "ARCH-Insight 3.1" \
  --html release.html --text release.txt --list 4 --translations translations.json
arch marketing campaign preview 12 --language ja --out preview.html
arch marketing campaign test 12 --to me@mycompany.com --language ja   # stays a draft
arch marketing campaign send 12 --yes

translations.json:

{"ja": {"subject": "ARCH-Insight 3.1", "body_html_file": "release.ja.html", "body_text_file": "release.ja.txt"},
 "de": {"subject": "ARCH-Insight 3.1 ist da"}}

Set the logo shown at the top of every e-mail with arch org logo logo.png.

Secrets

The dedicated arch-secrets command remains available. The same functionality can be reached through arch secrets:

export ARCH_SECRETS_TOKEN='your-vault-token'
arch secrets run -- npm start
arch secrets export > .env
arch secrets push .env

The vault token is scoped independently from the user access token used by product commands.

Developer platform

arch repo list
arch repo create team/sample --description "Example repository"
arch pipeline list --repo 12
arch pipeline show 42
arch pipeline logs 99
arch registry list
arch registry tags team/sample
arch runner list
arch deploy list production