docs: programmatic access — API keys, Use the API, and transiliencectl (CLI)

README.md

@@ -30,6 +30,8 @@ If you're brand new, read these in order:
 | [Artifacts](concepts/artifacts.md) | Saved outputs, organized into folders. |
 | [Threads](concepts/threads.md) | Chats where you ask questions about sessions and files. |
 | [Scheduling](concepts/scheduling.md) | Running an app on a recurring schedule or at a future time. |
+| [API keys](concepts/api-keys.md) | Long-lived keys to call the API from a script or an AI agent. |
+| [transiliencectl (CLI)](concepts/cli.md) | The command-line tool for driving the platform with an API key. |
 
 ## Install
 
@@ -45,6 +47,8 @@ If you're brand new, read these in order:
 | [Save an artifact](workflows/save-an-artifact.md) | Take an output from a session and save it into an artifact folder. |
 | [Ask about a session](workflows/ask-about-a-session.md) | Open a thread on one or more sessions and ask questions about the results. |
 | [Schedule an app](workflows/schedule-an-app.md) | Set an app to run on a recurring schedule or at a specific time. |
+| [Use the API](workflows/use-the-api.md) | Drive the platform from a script or AI agent with an API key (curl examples). |
+| [Use the CLI](workflows/use-the-cli.md) | Drive the platform from your terminal with transiliencectl. |
 
 ## Glossary
 

concepts/api-keys.md

@@ -0,0 +1,58 @@
+# API keys
+
+## What they are
+
+An **API key** is a long-lived credential that lets a program — for example a coding agent like Claude Code, a script, or `curl` — call the Transilience.ai API on your behalf, without signing in through the browser. With a key, anything you can do from the app (run [apps](apps.md), read [sessions](sessions.md) and [outputs](outputs.md), browse [artifacts](artifacts.md), and more) can be done from the command line or an agent.
+
+Each key is **bound to one [organization](#org-binding)** — the org you were in when you created it. The key carries that org with it, so requests made with the key are automatically scoped to it.
+
+![The API Keys tab in Account settings](../images/api-keys-profile-ui.jpg)
+
+## Where to find them
+
+Open **Settings** from the bottom of the left sidebar, then the **API Keys** tab. You'll see:
+
+- A short "Use SOS from Claude Code" panel with the **documentation URL** to hand to an agent (a `/llms.txt` guide).
+- A **Create key** button.
+- The list of keys for the current organization, each with its name, when it was created, and when it was last used.
+
+## Creating a key
+
+1. Click **Create key** and give it a name (for example `claude-code-laptop`).
+2. The **secret is shown once**, right after creation. Copy it immediately and store it somewhere safe (a password manager) — for security it is never shown again and cannot be retrieved later.
+3. If you lose a secret, just **revoke** the key and create a new one.
+
+## Using a key
+
+Send the key as a bearer token on every request:
+
+```
+Authorization: Bearer <YOUR_API_KEY>
+```
+
+Because the key is bound to an organization, you do **not** send any organization header — the org comes from the key. For a full walkthrough with `curl`, see [use the API](../workflows/use-the-api.md).
+
+## <a id="org-binding"></a>Organization binding
+
+A key belongs to exactly one organization. If you work across several orgs, create one key per org. To act in a different org, switch organizations in the app first, then create a key there.
+
+## Revoking a key
+
+In the **API Keys** tab, click **Revoke** next to a key. Revoked keys stop working shortly afterward and cannot be restored. Revoke a key any time you suspect its secret has leaked, or when a script that used it is retired.
+
+## Common questions
+
+**"Where is the key after I create it?"** — The secret appears only in the one-time dialog right after creation. The list afterward shows the key's name and dates, never the secret. If you didn't copy it, revoke the key and create a new one.
+
+**"Do I need to send my organization with each request?"** — No. The key is tied to one org, so the org is implied.
+
+**"What can a key do?"** — The same things you can do in that org. Admin-only actions still require that you are an org admin.
+
+**"How do I point an AI agent at the API?"** — Give it the documentation URL shown in the API Keys panel (the `/llms.txt` guide) plus a key. See [use the API](../workflows/use-the-api.md).
+
+## Related
+
+- [transiliencectl (CLI)](cli.md) — drive the platform from your terminal with a key.
+- [Use the API](../workflows/use-the-api.md) — step-by-step with curl examples.
+- [Sessions](sessions.md) — what a run is, and the IDs you'll see in API responses.
+- [Outputs](outputs.md) — the files a run produces, which you can fetch over the API.

concepts/cli.md

@@ -0,0 +1,54 @@
+# transiliencectl (CLI)
+
+## What it is
+
+**transiliencectl** is a command-line tool that talks to the Transilience.ai [API](../workflows/use-the-api.md). It turns the everyday loop — list apps, run one, watch it, pull the outputs — into short commands, so you can drive the platform from a terminal or a script instead of writing `curl` by hand.
+
+It authenticates with an [API key](api-keys.md) you mint in the app. Because the key is bound to one [organization](api-keys.md#org-binding), the CLI always acts in that org — there's nothing extra to pass.
+
+## Install
+
+```bash
+pipx install transiliencectl      # recommended (isolated)
+# or, for development from a checkout:
+pip install -e .
+```
+
+## Configure it once
+
+```bash
+transiliencectl config set base-url <your-api-host>
+transiliencectl auth login --api-key <YOUR_API_KEY>
+transiliencectl auth status        # → Authenticated. base_url=...
+```
+
+Settings live in `~/.transilience/config.json`. Values can also come from the environment
+(`TRANSILIENCE_BASE_URL`, `TRANSILIENCE_API_KEY`) or per-command flags (`--base-url`, `--api-key`);
+the order of precedence is **flag → environment → config file**.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `config set <key> <value>` | Store `base-url` or `api-key`. `config get` / `config path` to inspect. |
+| `auth login --api-key <key>` | Save your key. `auth status` checks it; `auth logout` clears it. |
+| `projects list` / `projects get <id>` | Browse the [apps](apps.md) you can run. |
+| `run <project_id> -q "..." [--follow]` | Start a [run](sessions.md); `--follow` waits for it to finish. |
+| `sessions list` / `sessions get <id> [--follow]` | List past runs; inspect one. |
+| `files list <id>` / `files get <id> <path> -o out` | List a run's [outputs](outputs.md) and download one. |
+
+Add `--json` to any command for machine-readable output (handy for scripts and AI agents).
+
+## Common questions
+
+**"How is this different from the raw API?"** — It's a friendlier front-end to the same [API](../workflows/use-the-api.md): no `curl`, no headers to remember, tables instead of raw JSON (unless you ask for `--json`).
+
+**"Where do I get the key?"** — In the app under **Settings → API Keys**. See [API keys](api-keys.md).
+
+**"Which org does it use?"** — The one your key is bound to. To act in another org, create a key there and `auth login` with it.
+
+## Related
+
+- [Use the CLI](../workflows/use-the-cli.md) — step-by-step walkthrough.
+- [API keys](api-keys.md) — minting and managing keys.
+- [Use the API](../workflows/use-the-api.md) — the underlying HTTP endpoints.

glossary.md

@@ -2,6 +2,8 @@
 
 One-line definitions for the terms used across these docs. Each term links to its concept page where one exists.
 
+- **[API](workflows/use-the-api.md)** — The HTTP interface that lets a script or AI agent do what you do in the app — run apps, read sessions and outputs — authenticated with an [API key](concepts/api-keys.md).
+- **[API key](concepts/api-keys.md)** — A long-lived credential for calling the API on your behalf, sent as `Authorization: Bearer <key>`. Created in **Settings → API Keys**, bound to one organization, and shown only once.
 - **[App](concepts/apps.md)** — A reusable security or compliance workflow you can run; the catalog lives on the **Apps** page in the sidebar. ("Project" is the internal name for the same thing.)
 - **[Apps page](concepts/apps.md)** — The page at the **Apps** sidebar entry where every app is listed as a card you can run, schedule, or open.
 - **[App detail](concepts/apps.md#app-detail)** — A per-app page that shows the app's description, what it does, and lets you launch it.
@@ -16,6 +18,7 @@ One-line definitions for the terms used across these docs. Each term links to it
 - **[Data file](concepts/outputs.md#data-files)** — A structured output file (typically JSON or CSV) produced by an app — usually raw scan results before they are summarized into a report.
 - **Failed** — A [session status](concepts/sessions.md#statuses) meaning the app encountered an error and did not finish.
 - **Files tab** — The tab inside a [session detail](concepts/run-history.md#session-detail) that lists every output file the app produced.
+- **llms.txt** — A machine-readable guide to the [API](workflows/use-the-api.md), served at `/llms.txt`. Hand its URL plus an [API key](concepts/api-keys.md) to an AI agent so it can call the platform for you.
 - **[Live Activity](concepts/live-activity.md)** — The page that shows a session while it is running, with the timeline and log streaming in real time.
 - **New Thread** — The sidebar button that starts a new empty [thread](concepts/threads.md).
 - **[Notifications](concepts/live-activity.md#notifications)** — The Notifications tab inside the chat area where running and recently-finished sessions appear.
@@ -34,5 +37,6 @@ One-line definitions for the terms used across these docs. Each term links to it
 - **[Schedule](concepts/scheduling.md)** — A rule that runs an app automatically — either repeatedly (recurring) or once at a future time (one-off).
 - **Status** — One of pending, running, completed, or failed. See [session statuses](concepts/sessions.md#statuses).
 - **[Thread](concepts/threads.md)** — A conversation in which you can ask questions about a session, an output file, or several of them.
+- **[transiliencectl](concepts/cli.md)** — The command-line tool that drives the platform via the [API](workflows/use-the-api.md), authenticated with an [API key](concepts/api-keys.md).
 - **[Thread group](concepts/threads.md#thread-groups)** — A named collection of threads that helps you organize related conversations.
 - **Timeline tab** — The tab inside a [session detail](concepts/run-history.md#session-detail) that shows the step-by-step log of what the app did.

workflows/use-the-api.md

@@ -0,0 +1,80 @@
+# Use the API
+
+Drive Transilience.ai from a script or an AI agent (like Claude Code) instead of the browser, using an [API key](../concepts/api-keys.md).
+
+## Before you start
+
+- Create a key in **Settings → API Keys** and copy the secret (it's shown once). See [API keys](../concepts/api-keys.md).
+- Know your **base URL** — the address of the API. The exact host is shown in the API Keys panel.
+
+## Authenticate
+
+Send the key as a bearer token on every request. The key is bound to one [organization](../concepts/api-keys.md#org-binding), so you do **not** send any organization header.
+
+```
+Authorization: Bearer <YOUR_API_KEY>
+```
+
+## The core loop
+
+The everyday path is: list apps → run one → poll until it finishes → read its outputs.
+
+```bash
+BASE="https://<your-api-host>"
+KEY="<YOUR_API_KEY>"
+
+# 1. See which apps you can run
+curl -s "$BASE/projects/" -H "Authorization: Bearer $KEY"
+
+# 2. Start a run — returns a session id
+curl -s "$BASE/project/execute" \
+  -H "Authorization: Bearer $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"project_id":"aws_public_resource_analyzer","query":"Run a compliance scan"}'
+
+# 3. Poll the run until status is COMPLETED (or INCOMPLETE / FAILED)
+curl -s "$BASE/project/outputs/<session_id>" -H "Authorization: Bearer $KEY"
+
+# 4. List the output files, then download one
+curl -s "$BASE/project/files/<session_id>" -H "Authorization: Bearer $KEY"
+curl -s "$BASE/project/files/<session_id>?file_path=reports/summary.md" \
+  -H "Authorization: Bearer $KEY" -o summary.md
+```
+
+Other useful calls:
+
+```bash
+# List your recent runs (defaults to the last 5 days)
+curl -s "$BASE/project/sessions" -H "Authorization: Bearer $KEY"
+
+# Widen the date range
+curl -s "$BASE/project/sessions?start_date=2026-01-01&end_date=2026-12-31" \
+  -H "Authorization: Bearer $KEY"
+```
+
+Notes:
+
+- `/project/outputs/{session_id}` is a **polling** endpoint — call it on an interval until the status is terminal (`COMPLETED`, `INCOMPLETE`, or `FAILED`).
+- `/project/files/{session_id}` returns a **file list** with no query parameter, or one file's **raw bytes** when you pass `?file_path=...`.
+
+## Point an AI agent at it
+
+Hand the agent two things:
+
+1. Your **API key**.
+2. The **documentation URL** shown in the API Keys panel — a machine-readable guide at `/llms.txt` that explains auth and the core endpoints with examples.
+
+The agent reads the guide, then makes the same calls shown above on your behalf — running apps, polling them, and reading the results.
+
+## If something goes wrong
+
+- **`401`** — the key is missing, wrong, or revoked. Check the `Authorization` header and that the key still exists in **Settings → API Keys**.
+- **`503` about API keys not being enabled** — the workspace administrator needs to enable the API Keys feature; ask them to turn it on.
+- **Empty session list** — `/project/sessions` defaults to the last 5 days; widen it with `start_date` / `end_date`.
+
+## Related
+
+- [Use the CLI](use-the-cli.md) — the same loop via the `transiliencectl` command-line tool.
+- [API keys](../concepts/api-keys.md) — creating, binding, and revoking keys.
+- [Run an app](run-an-app.md) — the same flow from the web UI.
+- [Sessions](../concepts/sessions.md) and [Outputs](../concepts/outputs.md) — what the responses contain.

workflows/use-the-cli.md

@@ -0,0 +1,73 @@
+# Use the CLI
+
+Drive Transilience.ai from your terminal with **[transiliencectl](../concepts/cli.md)** — list apps, run one, follow it to completion, and pull the outputs.
+
+## 1. Install
+
+```bash
+pipx install transiliencectl
+```
+
+## 2. Configure once
+
+Get an [API key](../concepts/api-keys.md) from the app (**Settings → API Keys**), then:
+
+```bash
+transiliencectl config set base-url <your-api-host>
+transiliencectl auth login --api-key <YOUR_API_KEY>
+transiliencectl auth status        # → Authenticated. base_url=...
+```
+
+You don't pass an organization anywhere — the key is bound to one, and the CLI uses it automatically.
+
+## 3. The everyday loop
+
+```bash
+# See which apps you can run
+transiliencectl projects list
+
+# Start a run and wait for it to finish
+transiliencectl run aws_public_resource_analyzer -q "Run a compliance scan" --follow
+
+# Or list past runs and inspect one
+transiliencectl sessions list
+transiliencectl sessions get <session_id>
+
+# Browse and download the outputs
+transiliencectl files list <session_id>
+transiliencectl files get <session_id> reports/summary.md -o summary.md
+```
+
+- `run --follow` (and `sessions get --follow`) polls until the run reaches a terminal status
+  (**completed**, **incomplete**, or **failed**).
+- `files get` without `-o` writes the file to stdout; with `-o PATH` it saves to disk.
+
+## 4. Scripting and agents
+
+Add `--json` to any command to get raw JSON instead of a table — easy to pipe into `jq` or hand to an AI agent:
+
+```bash
+transiliencectl --json sessions list | jq '.sessions[].session_id'
+```
+
+## Configuration reference
+
+Resolution order is **flag → environment → config file**:
+
+| Source | Base URL | API key |
+|---|---|---|
+| Flag | `--base-url` | `--api-key` |
+| Environment | `TRANSILIENCE_BASE_URL` | `TRANSILIENCE_API_KEY` |
+| Config file | `base_url` in `~/.transilience/config.json` | `api_key` in the same file |
+
+## If something goes wrong
+
+- **"Invalid or expired API key"** — re-check the key, or set a fresh one: `transiliencectl auth login --api-key <key>`.
+- **"Cannot reach <base_url>"** — verify `transiliencectl config get base-url` points at the right host.
+- **Empty `sessions list`** — it defaults to recent sessions; widen with `--start 2026-01-01 --end 2026-12-31`.
+
+## Related
+
+- [transiliencectl](../concepts/cli.md) — what the CLI is and its full command list.
+- [API keys](../concepts/api-keys.md) — creating and revoking keys.
+- [Use the API](use-the-api.md) — the raw HTTP endpoints behind the CLI.