> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# SDK and CLI

Use the TypeScript SDK inside an application. Use the `saturation` CLI from a
terminal, CI job, or agent runtime. Both use the same `/v1` contract.

## TypeScript SDK

The official package is `@saturationio/sdk`. The current release channel is
`alpha`.

```bash
npm install @saturationio/sdk@alpha
```

```ts
import { Saturation, SaturationError } from '@saturationio/sdk';

const token = process.env.SATURATION_TOKEN;
if (!token) throw new Error('SATURATION_TOKEN is required');

const saturation = new Saturation({
  token,
});

const me = await saturation.me();
const project = saturation.projects('feature-film-2026');
const budget = await project.budget.get();

console.log(me, budget.totals);
```

The SDK defaults to `https://next-api.saturation.io/v1`. Keep the token on your
server. Set `baseURL` only for a local or staging environment.

The SDK throws `SaturationError` for non-`2xx` responses. Branch on
`error.code`, and include `requestId` when reporting a failed request.

### Build with project data

A few typed reads are enough to build a custom view of a production. This
example loads a project, its pinned brief, the current budget document, and its
comments:

```ts
const projects = await saturation.projects.list({ limit: 100 }).all();
const projectId = projects[0].id;

const project = await saturation.projects.get(projectId, {
  expand: ['assumptions'],
});
const budget = await saturation.projects(projectId).budget.get();
const comments = await saturation.projects(projectId).comments.list().all();
```

`project.assumptions` contains the brief pinned on the Project Info sheet.
`budget` contains the current phases, lines, and computed totals. The response
stays tied to Saturation instead of creating a second budget model in your
application.

## Bidbook

Bidbook turns a Saturation project into a client-ready proposal. It reads the
project brief, budget, and comments through the SDK.

[View the source](https://github.com/Saturation-IO/saturation-sdk-typescript/tree/main/demos/bidbook)
· [Open the demo](https://bidbook-sdk-demo.saturation.io)

![Bidbook reads a project brief and budget through the Saturation SDK](https://raw.githubusercontent.com/Saturation-IO/saturation-sdk-typescript/main/demos/bidbook/public/bidbook-demo.gif)

## Command-line interface

### Homebrew

```bash
brew install Saturation-IO/tap/saturation
```

### macOS and Linux

```bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/Saturation-IO/saturation-cli/releases/latest/download/saturation-cli-installer.sh | sh
```

### Windows PowerShell

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Saturation-IO/saturation-cli/releases/latest/download/saturation-cli-installer.ps1 | iex"
```

### Cargo

```bash
cargo install saturation-cli --locked
```

Sign in through Saturation. This uses the same OAuth login, MFA, workspace
selection, and consent flow as MCP:

```bash
saturation login
saturation projects list
saturation search "camera"
```

For CI, create a personal token under **Settings > Developers > API** and keep it
in a protected file instead of the saved CLI config:

```bash
saturation --token-file /run/secrets/saturation-token projects list
```

Run `saturation --help` for the resource list and `saturation <resource> --help`
for its command grammar. Run `saturation schema` for the offline API operation
inventory. The HTTP API uses the `/v1` contract, while the CLI handles API
versioning internally. Global flags such as `--project` and `--idempotency-key`
do not require a version namespace.

Create commands require an idempotency key so retries cannot duplicate a
record:

```bash
saturation --idempotency-key UNIQUE_KEY projects create '{"name":"Summer Feature"}'
```

Document content is returned as its original bytes. Redirect it to a file:

```bash
saturation documents content DOCUMENT_ID > document.pdf
```

Release archives include SHA-256 checksums. GitHub records build provenance for
each published binary.

## Contract entrypoints

| Path | What it serves |
|---|---|
| `/openapi.yaml` | The full API definition: fields, allowed values, requests, and responses. |
| `/api-reference.md` | A generated Markdown index of every endpoint. |
| `/api-reference/{operationId}.md` | One endpoint with auth, parameters, request body, responses, curl, and agent notes. |
| `/llms.txt` | The entrypoint assistants should read first. |

## Next

- [Quickstart](/quickstart.md): authenticate and make your first call.
- [Errors](/errors.md): error responses, status codes, and retries.
- [Pagination](/pagination.md): how to read long lists.