Metadata-Version: 2.4
Name: arch-insight-cli
Version: 0.4.0
Summary: Command-line client for ARCH-Insight tasks, factsheets, secrets, and developer platform.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: arch-secrets>=1.1.2

# 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

```sh
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

```sh
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

```sh
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:

```sh
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

```sh
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:

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

See `arch_cli/work.py` for the file format.

## Organisation

```sh
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:

```sh
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:

```sh
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`:

```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`:

```sh
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

```sh
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
```
