---
title: "Automation"
description: "Run the CLI in CI with an API key, and let an agent drive it safely."
canonical: "https://atelier201.com/docs/cli/automation"
updated: "2026-11-06"
---

# Automation

## In CI

Use an API key, not an OAuth login: a key belongs to the workspace and does not
expire when a person leaves.

```bash
export ATELIER201_API_KEY="atelier201_live_..."
atelier201 site push --build --wait
```

Set the narrowest scopes the job needs. A job that builds and previews needs
`sites:write`. Leave out `sites:publish` and the job cannot change what visitors
see, so a leaked log cannot put anything online.

In a script, `publish` needs `--yes`, and `sites delete` needs `--confirm <slug>`.
Without them the command exits `2`, writes nothing and prints the exact command to
re-run.

## With an agent

```bash
atelier201 help --json
```

`help --json` prints the full command tree, the exit codes, the retry policy and
the error envelope as one machine-readable document. An agent that reads it first
stops guessing at flags.

Use `atelier201 help files read --json` to inspect only one command, or
`atelier201 help --operation readSiteFile --json` for its full REST schemas and
CLI/MCP mapping. Discovery works offline without credentials. The bundled
contract describes your installed CLI version; the live OpenAPI and MCP resource
describe the deployed API. See [operation coverage](/docs/api/surfaces).

> **Warning: Let the owner publish**
>
> An agent should build a draft, share a preview and ask. Give it `sites:write`
> and withhold `sites:publish`. It can then do all the work, and the owner decides
> when the site goes live.

## Retries

The CLI retries `429` for every command. It retries `408` and `5xx` only for reads
(`GET`, `HEAD`, and `OPTIONS`). A write that fails with a `5xx` is
reported instead of repeated, because it may already have been applied: read the
site again before retrying it yourself. An `Idempotency-Key` header does not
enable automatic write retries. If `Retry-After` exceeds 60 seconds, the CLI
returns the error with its recovery details instead of retrying early or waiting
indefinitely. Network errors and timeouts are not retried. Turn retries off with
`--no-retry`.