diff --git a/README.md b/README.md index 7a6b0a8..fd65c58 100644 --- a/README.md +++ b/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 diff --git a/concepts/api-keys.md b/concepts/api-keys.md new file mode 100644 index 0000000..93ea087 --- /dev/null +++ b/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 +``` + +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). + +## 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. diff --git a/concepts/cli.md b/concepts/cli.md new file mode 100644 index 0000000..dc81ba2 --- /dev/null +++ b/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 +transiliencectl auth login --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 ` | Store `base-url` or `api-key`. `config get` / `config path` to inspect. | +| `auth login --api-key ` | Save your key. `auth status` checks it; `auth logout` clears it. | +| `projects list` / `projects get ` | Browse the [apps](apps.md) you can run. | +| `run -q "..." [--follow]` | Start a [run](sessions.md); `--follow` waits for it to finish. | +| `sessions list` / `sessions get [--follow]` | List past runs; inspect one. | +| `files list ` / `files get -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. diff --git a/glossary.md b/glossary.md index c2c671a..5f8dafd 100644 --- a/glossary.md +++ b/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 `. 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. diff --git a/images/api-keys-profile-ui.jpg b/images/api-keys-profile-ui.jpg new file mode 100644 index 0000000..5739502 Binary files /dev/null and b/images/api-keys-profile-ui.jpg differ diff --git a/workflows/use-the-api.md b/workflows/use-the-api.md new file mode 100644 index 0000000..9ffe877 --- /dev/null +++ b/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 +``` + +## The core loop + +The everyday path is: list apps → run one → poll until it finishes → read its outputs. + +```bash +BASE="https://" +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/" -H "Authorization: Bearer $KEY" + +# 4. List the output files, then download one +curl -s "$BASE/project/files/" -H "Authorization: Bearer $KEY" +curl -s "$BASE/project/files/?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. diff --git a/workflows/use-the-cli.md b/workflows/use-the-cli.md new file mode 100644 index 0000000..b38aed7 --- /dev/null +++ b/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 +transiliencectl auth login --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 + +# Browse and download the outputs +transiliencectl files list +transiliencectl files get 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 `. +- **"Cannot reach "** — 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.