Install Archie's CLI

Archie's command line is how you put his team to work from your terminal. Rich tables when you read it, plain JSON when you pipe it.

Install and sign in

The archie command is a standalone app, so install it in its own isolated environment with pipx (or uv). That keeps it off your system Python and drops archie straight onto your PATH. The steps below follow the operating system selected in the header.

terminalbash

brew install pipx
pipx install heyarchie

archie auth login

Prefer uv? It is identical on every OS:

uv tool install heyarchie

A bare pip install heyarchie trips an externally-managed-environment error on macOS and recent Debian/Ubuntu (PEP 668), because the system Python is guarded. pipx and uv sidestep it by managing a virtualenv for you. To use the SDK as a library instead, run pip install heyarchie inside your project's virtualenv.

archie auth login opens your browser, shows a one-time code, and waits while you sign in with your firm's SSO and pick your workspace. Archie remembers you. No keys to paste, no files to edit.

Then put him to work:

archie skills list        # everything Archie can do
archie keys list          # your Connect keys
archie workstreams run    # put a WorkStream to work

What the first run looks like

archie auth login runs a browser sign-in (the RFC 8628 device flow). You get a code, you approve it, Archie saves a short-lived session for you. Nothing is pasted and no long-lived key is minted.

$ archie auth login
╭─ Archie device login ──────────────────────────────────╮
│ Open this URL and confirm the code:                    │
│                                                        │
│   https://api.dev.arch.ie/device                       │
│                                                        │
│ Your code:  PKGX-GLCH                                  │
│                                                        │
│ Opening your browser… (waiting for approval, this      │
│ code expires in 5 minutes)                             │
╰────────────────────────────────────────────────────────╯

Signed in as [email protected].
Session saved to ~/.archie/credentials.toml (profile='default').
Try: archie keys list

The session is written to ~/.archie/credentials.toml (chmod 600) under the [default] profile, so every other command reads it the same way. Run archie auth status to see who you are, archie auth logout to drop it.

Prove the sign-in worked: archie keys list reads your real Connect keys with the session Archie just minted.

For automation

In CI, swap the browser flow for a Connect key. Mint one in the dashboard, then:

archie auth login --api-key sk_live_xxxxxxxxxxxxxxxx
# or set ARCHIE_API_KEY in the environment and skip login entirely

Commands

archie auth login                            Browser sign-in (default).
archie auth status                           Who am I? (redacted token).
archie auth token                            Print the bearer for scripts.
archie auth logout                           Drop the saved session.

archie keys list                             Your Connect keys.
archie keys create <name>                    Mint an sk_* (developer role).

archie skills list [--category ...]          The skill catalogue.
archie skills run <command> [--flags]        One typed command per skill (1.4.0+).
archie skills invoke <slug> --input <json>   Call one skill with raw JSON.

archie workstreams list [--scope ...]        WorkStreams you can see.
archie workstreams describe <id>             Metadata + step graph.
archie workstreams run <id> [--var k=v]      Start a cycle.
archie workstreams status <cycle_id>         Cycle progress.
archie workstreams cancel <cycle_id>         Cancel a running cycle.
archie workstreams logs <cycle_id>           Stream events live.

workstream_id accepts a UUID, a WorkStream slug, or a 7-char permakey; Archie resolves all three.

archie logs and archie webhooks ship marked coming soon. They are discoverable in --help and ready to wire into scripts; until their backends land they report cleanly and exit without erroring.

Typed skill commands: archie skills run

Every public skill is also a first-class CLI command under archie skills run — 65 commands, generated from the canonical skill registry. The flags on each command derive from that skill's typed input model: required fields become required flags, and list/object fields accept inline JSON. Add a skill to the registry, regenerate, and it gets a command for free — no JSON body to hand-assemble.

Version note: archie skills run ships in heyarchie 1.4.0. PyPI currently serves 1.3.0, which has skills list and the generic skills invoke but not run. Until 1.4.0 publishes, get the typed commands from a repo checkout: pip install -e apps/sdk-python.

--help lists every command:

$ archie skills run --help | head
Usage: archie skills run [OPTIONS] COMMAND [ARGS]...

  Invoke any skill with typed options.

Options:
  --help  Show this message and exit.

Commands:
  accruals-suggest               Advisory — LLM-driven; verify against
                                 authoritative sources

Each command's --help is the skill's input schema, flattened to flags. Note the auth and output flags (--json, --profile, --api-url, --api-key) ride along on every command, exactly as they do on invoke:

$ archie skills run topic-create --help
Usage: archie skills run topic-create [OPTIONS]

  Create a Topic in the caller's workspace (optionally bound to a client). The
  topic is stamped created_by_type=archie.

Options:
  --name TEXT         [required]
  --client-id TEXT    UUID of the client to bind
  --theme-color TEXT  Hex like #DAFBE1; default applied server-side
  --type TEXT         Topic type: client | matter | process_period | advisory
                      | compliance | internal (DB-enforced enum)
  --json              Emit raw JSON to stdout (machine-friendly).
  --profile TEXT      Credentials profile in ~/.archie/credentials.toml
                      (default: 'default').
  --api-url TEXT      API base URL. Falls back to env ARCHIE_API_URL or saved
                      credentials.
  --api-key TEXT      Bearer token. Falls back to env ARCHIE_API_KEY or saved
                      credentials.
  --help              Show this message and exit.

Scalar fields are plain flags; list and object fields take inline JSON (flagged (JSON) in the help text):

# Create a topic, typed flags instead of a JSON body
archie skills run topic-create --name "FY26 audit — Acme" --type client

# List topics, pipe-friendly
archie skills run topic-list --limit 5 --json | jq '.topics[].name'

# ask_archie as a typed command (--query is required)
archie skills run ask-archie --query "Under ASC 606, when is revenue recognised?"

# A list-typed field takes inline JSON
archie skills run accruals-suggest \
  --client-id "$CLIENT" --period 2026-04 \
  --focus-areas '["wages", "rent"]'

Examples

See everything Archie can do

archie skills list

# Pipe-friendly
archie skills list --json | jq '.[].slug'

Run a cycle and follow it live

CYCLE=$(archie workstreams run month-end-close \
  --period FY26-Q1 \
  --var include_deferred=true \
  --idempotency-key close-2026-04-acme-001 \
  --json | jq -r .cycle_id)

archie workstreams logs "$CYCLE" --follow

Ask Archie a question

ask_archie is the general-purpose skill — the fallback for any accounting question that doesn't fit a more specific one. It is invoked like any skill, with a query:

archie skills invoke ask_archie \
  --input '{"query": "Under ASC 606, when is revenue recognised?"}'

He answers in a rich table on a terminal. For just the prose, pipe the JSON through jq:

archie skills invoke ask_archie \
  --input '{"query": "What is the BAS, and when is it due?"}' \
  --json | jq -r '.answer'

# Every answer carries citations to the standard it came from:
archie skills invoke ask_archie \
  --input '{"query": "Capitalise or expense a 3-year SaaS subscription?"}' \
  --json | jq -r '.citations[].standard'

Long questions live in a file rather than the shell — pass it with @:

echo '{"query": "Walk me through the lease classification test for our new warehouse."}' > q.json
archie skills invoke ask_archie --input @q.json

Invoke any other skill

Also available: the generic invoke path. Every skill in the catalogue takes the same invoke <slug> --input shape — only the input fields change. This is the path that works on the current PyPI release (1.3.0) as well as 1.4.0, and it's the right tool when you already have the input as JSON. The slug accepts either the friendly name or the internal one (research_standards and standards.research both work). A couple worth knowing:

# Research a standard, scoped to a jurisdiction
archie skills invoke research_standards \
  --input '{"topic": "revenue recognition for licences", "jurisdiction": "AU"}'

# List every slug you can call
archie skills list --json | jq -r '.[].slug'

Each skill's exact inputs are in the skill catalogue and the API reference (every skill is POST /api/v1/skills/<slug>/invoke with the same body the CLI sends).

Where it points

By default the CLI talks to https://api.dev.arch.ie, which serves the browser sign-in today. Point it at any tier with --api-url or the ARCHIE_API_URL environment variable once that tier serves the device flow.

Variable	Purpose	Default
`ARCHIE_API_URL`	API base URL	`https://api.dev.arch.ie`
`ARCHIE_API_KEY`	Bearer token (skips login)	(none)

CLI flags win over environment variables, which win over the saved credentials file.

Where it lives

apps/sdk-python/ in the archie-platform-v2 repo. The same package ships the Python SDK (import heyarchie) and the archie command.

WorkStreams concepts the nouns the CLI operates on.
Python SDK the same surface, programmatic.
Playground the same surface, in your browser.