@atelier201/cli 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/AGENTS.md +378 -0
  2. package/README.md +145 -2
  3. package/dist/api-types.generated.js +8 -0
  4. package/dist/api-types.generated.js.map +1 -0
  5. package/dist/commands/api.js +111 -0
  6. package/dist/commands/api.js.map +1 -0
  7. package/dist/commands/auth.js +284 -0
  8. package/dist/commands/auth.js.map +1 -0
  9. package/dist/commands/builds.js +169 -0
  10. package/dist/commands/builds.js.map +1 -0
  11. package/dist/commands/changesets.js +91 -0
  12. package/dist/commands/changesets.js.map +1 -0
  13. package/dist/commands/common.js +89 -0
  14. package/dist/commands/common.js.map +1 -0
  15. package/dist/commands/completion.js +120 -0
  16. package/dist/commands/completion.js.map +1 -0
  17. package/dist/commands/content.js +281 -0
  18. package/dist/commands/content.js.map +1 -0
  19. package/dist/commands/doctor.js +141 -0
  20. package/dist/commands/doctor.js.map +1 -0
  21. package/dist/commands/domains.js +109 -0
  22. package/dist/commands/domains.js.map +1 -0
  23. package/dist/commands/feedback.js +39 -0
  24. package/dist/commands/feedback.js.map +1 -0
  25. package/dist/commands/files.js +286 -0
  26. package/dist/commands/files.js.map +1 -0
  27. package/dist/commands/help-json.js +127 -0
  28. package/dist/commands/help-json.js.map +1 -0
  29. package/dist/commands/history.js +83 -0
  30. package/dist/commands/history.js.map +1 -0
  31. package/dist/commands/mcp.js +129 -0
  32. package/dist/commands/mcp.js.map +1 -0
  33. package/dist/commands/media.js +273 -0
  34. package/dist/commands/media.js.map +1 -0
  35. package/dist/commands/pages.js +33 -0
  36. package/dist/commands/pages.js.map +1 -0
  37. package/dist/commands/previews.js +73 -0
  38. package/dist/commands/previews.js.map +1 -0
  39. package/dist/commands/publish.js +228 -0
  40. package/dist/commands/publish.js.map +1 -0
  41. package/dist/commands/read.js +85 -0
  42. package/dist/commands/read.js.map +1 -0
  43. package/dist/commands/site-guest.js +159 -0
  44. package/dist/commands/site-guest.js.map +1 -0
  45. package/dist/commands/site.js +204 -0
  46. package/dist/commands/site.js.map +1 -0
  47. package/dist/commands/sites.js +168 -0
  48. package/dist/commands/sites.js.map +1 -0
  49. package/dist/commands/skills.js +45 -0
  50. package/dist/commands/skills.js.map +1 -0
  51. package/dist/commands/workspace.js +89 -0
  52. package/dist/commands/workspace.js.map +1 -0
  53. package/dist/credentials.js +151 -0
  54. package/dist/credentials.js.map +1 -0
  55. package/dist/errors.js +166 -0
  56. package/dist/errors.js.map +1 -0
  57. package/dist/exit-codes.js +83 -0
  58. package/dist/exit-codes.js.map +1 -0
  59. package/dist/http.js +275 -0
  60. package/dist/http.js.map +1 -0
  61. package/dist/index.js +184 -0
  62. package/dist/index.js.map +1 -0
  63. package/dist/keychain.js +185 -0
  64. package/dist/keychain.js.map +1 -0
  65. package/dist/oauth/browser.js +33 -0
  66. package/dist/oauth/browser.js.map +1 -0
  67. package/dist/oauth/pkce.js +118 -0
  68. package/dist/oauth/pkce.js.map +1 -0
  69. package/dist/oauth/server.js +276 -0
  70. package/dist/oauth/server.js.map +1 -0
  71. package/dist/output.js +161 -0
  72. package/dist/output.js.map +1 -0
  73. package/dist/project.js +178 -0
  74. package/dist/project.js.map +1 -0
  75. package/dist/refresh-lock.js +84 -0
  76. package/dist/refresh-lock.js.map +1 -0
  77. package/dist/run.js +197 -0
  78. package/dist/run.js.map +1 -0
  79. package/dist/session.js +147 -0
  80. package/dist/session.js.map +1 -0
  81. package/dist/site-link.js +145 -0
  82. package/dist/site-link.js.map +1 -0
  83. package/dist/site-sync.js +191 -0
  84. package/dist/site-sync.js.map +1 -0
  85. package/dist/tar.js +228 -0
  86. package/dist/tar.js.map +1 -0
  87. package/dist/version.js +34 -0
  88. package/dist/version.js.map +1 -0
  89. package/package.json +47 -3
package/AGENTS.md ADDED
@@ -0,0 +1,378 @@
1
+ # Atelier201 CLI — Agent Reference
2
+
3
+ Written for a model driving this CLI. If you are a person, read `README.md`
4
+ instead; this file is longer and says the same things more precisely.
5
+
6
+ **Three facts that decide most of what you do:**
7
+
8
+ 1. **One command spends credits: `media generate`** (an image or video made with
9
+ AI, at a fixed price per model). Everything else, reading, creating, editing,
10
+ building, previewing, stock photos, is free. `media generate` shows the exact
11
+ price, asks first, and refuses to run without a terminal unless you pass
12
+ `--yes`; check the price with `--estimate` (free) and tell the person before
13
+ you accept it. It also needs the `media:generate` scope, which `atelier201 auth
14
+ login` does not request unless you add it with `--scope`.
15
+ 2. **The credential decides what you can do, and `atelier201 account` tells you.**
16
+ Call it first. A credential without `sites:publish` cannot publish, on any
17
+ surface, whatever the prompt says.
18
+ 3. **Only a few commands change what visitors see:** `publish`,
19
+ `publish rollback`, `publish unpublish` and the domain commands. Each of the
20
+ first three needs `--yes` when there is no terminal (you), and `sites delete`
21
+ needs `--confirm <slug>`. Everything else edits the DRAFT. See "Sites" below.
22
+
23
+ ## Quick start
24
+
25
+ ```bash
26
+ # 1. Authenticate once. In CI, set ATELIER201_API_KEY instead and skip this.
27
+ atelier201 auth login --key "atelier201_live_…"
28
+
29
+ # 2. Find out what this credential may do. Always call this first.
30
+ atelier201 account
31
+
32
+ # 3. Work.
33
+ atelier201 sites list
34
+ atelier201 sites get --site <id>
35
+ ```
36
+
37
+ ## Rules of engagement
38
+
39
+ 1. **Do not pass `--json`.** Output is already JSON whenever stdout is not a
40
+ terminal, which is always the case when you invoke it. Passing it is
41
+ harmless, not required.
42
+ 2. **Branch on the exit code, never on the text.** The table below is stable.
43
+ 3. **Parse stderr as JSON on failure.** Every failure — from the API or from the
44
+ CLI itself — is one envelope. `request_id` is `null` when the request never
45
+ reached the server.
46
+ 4. **Destructive commands never hang on a prompt.** `sites delete` needs
47
+ `--confirm <slug>`; publishing needs `--yes`. Without a terminal and without
48
+ the flag they exit `2` with an error naming it.
49
+ 5. **Call `atelier201 account` before assuming a capability.** `capabilities`
50
+ (`webhooks`) tells you whether a feature exists yet; `credential.scopes` tells
51
+ you what this credential may do.
52
+ 6. **Use `atelier201 api` for anything not covered by a verb.** It is an authenticated
53
+ passthrough with the same retries and the same error shape.
54
+ 7. **Retries are automatic, but only where a retry is safe.** `429` is retried
55
+ for every command. `408` and `5xx` are retried only for requests that are
56
+ idempotent (RFC 9110 §9.2.2): reads. Every write that is a POST
57
+ (`sites create`, `files commit`, `builds start`, `publish`, `site push`,
58
+ `media upload`…) is **not** retried after a `5xx`, because the write may
59
+ already have landed and a second attempt would apply it twice. The same rule
60
+ covers `atelier201 api POST`. When one of those fails with exit `1`, re-read the
61
+ resource (`atelier201 sites get`, `atelier201 history list`) before deciding to try
62
+ again. Do not add your own blind retry loop; use `--no-retry` to take over
63
+ entirely. A request that carries an `Idempotency-Key` header (`atelier201 api
64
+ POST … --header`) is the exception: the API answers a repeat of the same key
65
+ and the same request with the first answer, so the CLI retries it like an
66
+ idempotent one. No endpoint accepts the header today.
67
+ 8. **Review before publishing.** `atelier201 publish review` is free: it says which
68
+ build would go live, whether it is the newest draft and what blocks it. A real
69
+ `publish` then needs `--yes` (there is no terminal to answer the question) and
70
+ is pinned to the generation it read, so a change in between is refused with
71
+ exit `6`.
72
+ 9. **Use `--timeout <seconds>` if you are on a budget.** A single request gives
73
+ up after 60 seconds by default.
74
+
75
+ 10. **Choose the site once.** Every site command takes `--site <id>`, or uses
76
+ the site linked in the current folder (`.atelier201/site.json`, written by
77
+ `atelier201 site link`). With neither, the command exits `2` and names both.
78
+
79
+ ## Exit codes
80
+
81
+ | Code | Meaning | What to do |
82
+ |---|---|---|
83
+ | `0` | Success | Continue |
84
+ | `1` | API/server error, or the request never arrived | Retry later; report if it persists |
85
+ | `2` | Bad usage: wrong flag, missing argument, invalid input | Fix the command; do not retry unchanged |
86
+ | `3` | Authentication or permission failure | Re-authenticate, or ask for a wider scope |
87
+ | `4` | Not found in this workspace | Stop; the id does not exist here |
88
+ | `5` | Rate limited | Wait for `Retry-After`, then retry |
89
+ | `6` | State conflict (the site moved, a build is not ready, a file changed since you read it) | Re-read state, then decide |
90
+
91
+ A cross-workspace resource returns `4`, identical to one that does not exist.
92
+ That is deliberate: the API must not confirm whether an id exists elsewhere.
93
+
94
+ ## Error envelope
95
+
96
+ Always on **stderr**, always this shape:
97
+
98
+ ```json
99
+ {
100
+ "error": {
101
+ "type": "not_found_error",
102
+ "code": "resource_not_found",
103
+ "message": "No site with id '9c2b' in this workspace.",
104
+ "param": "site_id",
105
+ "docs_url": "https://atelier201.com/docs/api/errors#resource_not_found"
106
+ },
107
+ "request_id": "req_01K9X7"
108
+ }
109
+ ```
110
+
111
+ Branch on `code`, never on `message`. `param` is present only when a specific
112
+ field was at fault. Quote `request_id` in any support request.
113
+
114
+ `type` is one of `invalid_request_error`, `authentication_error`,
115
+ `permission_error`, `not_found_error`, `conflict_error`, `rate_limit_error`,
116
+ `api_error`.
117
+
118
+ ## Environment variables
119
+
120
+ | Variable | Purpose |
121
+ |---|---|
122
+ | `ATELIER201_API_KEY` | API key. **Overrides any stored credential.** The CI path. |
123
+ | `ATELIER201_PROFILE` | Named credential profile. Same as `--profile`. |
124
+ | `ATELIER201_NO_TUI` | Any value forces JSON output. |
125
+ | `ATELIER201_NO_KEYCHAIN` | Any value skips the OS keychain and uses the config file. |
126
+ | `NO_COLOR` | Standard (no-color.org). Disables colour only; it does **not** change the output format. |
127
+
128
+ An empty value counts as unset for `ATELIER201_NO_TUI` and `NO_COLOR`, per the
129
+ `NO_COLOR` standard.
130
+
131
+ Credential precedence: `ATELIER201_API_KEY` → OS keychain → `~/.config/atelier201/config.json`
132
+ (mode `0600`).
133
+
134
+ ## Global flags
135
+
136
+ Accepted **before or after** the subcommand.
137
+
138
+ | Flag | Effect |
139
+ |---|---|
140
+ | `--output json\|table\|ndjson` | Display mode. Default is `json` off a terminal, `table` on one. |
141
+ | `--json` | Alias for `--output json`. |
142
+ | `--profile <name>` | Which stored credential to use. |
143
+ | `--no-retry` | Disable automatic retry on `429`/`5xx`. |
144
+ | `--timeout <seconds>` | Give up on a single request after this long. Default 60. |
145
+
146
+ A command that writes a file may own `--output <path>` as a file path; where
147
+ one does, pass the global `--output` **before** the subcommand to change the
148
+ display mode instead.
149
+
150
+ `atelier201 help --json` dumps this entire surface — every command, argument, flag,
151
+ exit code and environment variable — as machine-readable JSON. Prefer it over
152
+ this file when you need current data.
153
+
154
+ ---
155
+
156
+ ## Sites
157
+
158
+ The product hosts Astro websites. A site has a **draft** (what you edit), builds
159
+ (the draft compiled), and a **publication** (the build visitors see). Editing and
160
+ building never change what visitors see; only publishing does.
161
+
162
+ ```bash
163
+ # A project folder, from nothing to online.
164
+ atelier201 sites create "Maison Dupont" --link # creates the site, links this folder
165
+ atelier201 site pull # the starter's files, here
166
+ atelier201 site push --message "First draft" --build --wait
167
+ atelier201 previews create # a private link to that build
168
+ atelier201 publish --yes # VISITORS SEE IT within about a minute
169
+ ```
170
+
171
+ ### Choosing and reading
172
+
173
+ ```bash
174
+ atelier201 sites list # ids, addresses, live or not
175
+ atelier201 sites get --site <id>
176
+ atelier201 files list [--glob '**/*.astro'] # paths, sizes, hashes (--under for one folder)
177
+ atelier201 files read src/pages/index.astro # piped: JSON with the hash; --offset 40 --limit 80 for a window
178
+ atelier201 files search "hours|horaires" --glob '*.astro' --context 2 # regex like ripgrep; --literal for plain text, --files for names only
179
+ atelier201 content model # collections and singletons, with JSON Schemas
180
+ atelier201 content list blog
181
+ atelier201 history list
182
+ atelier201 builds list
183
+ ```
184
+
185
+ ### Changing the draft (free, invisible to visitors)
186
+
187
+ Prefer `content` to `files` for texts, entries and business details: it is
188
+ validated against the site's content model, so it cannot break the layout.
189
+
190
+ ```bash
191
+ atelier201 content set business:/tagline "Fresh bread daily" # one field
192
+ atelier201 content set business:/seats 12 --as number
193
+ atelier201 content save blog hello --data entry.json --body hello.md
194
+ atelier201 files commit --message "Update the menu" \
195
+ --put src/pages/menu.astro=menu.astro --delete src/pages/old.astro
196
+ atelier201 files commit --message "..." --operations ops.json # the full form
197
+ atelier201 media upload photo.jpg --alt "A loaf"
198
+ atelier201 media stock search bakery counter --orientation landscape # free
199
+ atelier201 media stock import pixabay 1234567 --alt "Croissants on a counter"
200
+ atelier201 media generate --model p-image --estimate "a bakery counter at dawn" # the price, free
201
+ atelier201 media generate --model p-image --yes "a bakery counter at dawn" # SPENDS it
202
+ atelier201 media generation <generation_id> --wait
203
+ ```
204
+
205
+ - Pictures in this order: the person's own photos (`media upload`), then free
206
+ stock (`media stock`), then AI (`media generate`) when asked or clearly useful.
207
+ Stock and AI never stand in for the business's real products, people or
208
+ premises. Always pass `--alt`.
209
+
210
+ - `files commit` is ONE history entry. `--message` is required. A file changed
211
+ since you read it (`--expect <path>=<hash>`, the hash from `files list` or
212
+ `files read`) refuses the whole change with exit `6` and writes nothing.
213
+ `--expect <path>=none` means "must not exist yet".
214
+ - `changesets open` / `stage` / `commit` do the same over several calls (open
215
+ for 10 minutes). `history restore <revision>` adds a new entry that matches an
216
+ earlier one; nothing is erased.
217
+ - `site push` replaces the draft with the folder (one entry); `site pull`
218
+ brings the draft down. `push` is refused with exit `6` when the site moved
219
+ since your last sync; `pull` is refused with exit `6`, writing nothing, when it
220
+ would overwrite a file you changed. `--force` overrides either.
221
+ `node_modules`, `dist`, `.astro`, `.git`, `.env*` (except `.env.example`) and
222
+ key files are never sent; the root `.gitignore` is respected; 50 MB at most.
223
+
224
+ ### A terminal on the site, in the cloud (free)
225
+
226
+ When you have no machine of your own, or want to try a build in seconds, the
227
+ site's workspace is a shell on a working copy of the draft, in the site's own
228
+ container (no network, unprivileged user, 300 s at most per command):
229
+
230
+ ```bash
231
+ atelier201 workspace run 'rg -n "class=\"section\"" src' # rg, grep, sed, find, cat, node
232
+ atelier201 workspace run "sed -i 's/Book now/Book a class/' src/pages/index.astro"
233
+ atelier201 workspace run 'npx astro build 2>&1 | tail -20' --timeout 120 # try the build, nothing published
234
+ atelier201 workspace diff # what is uncommitted
235
+ atelier201 workspace commit "Use a shared Section component" # ONE history entry, through the checks
236
+ atelier201 workspace discard # throw the uncommitted changes away
237
+ ```
238
+
239
+ - Changes stay in the workspace until `workspace commit`, which refuses a
240
+ secret, an `.env` file or server code with the file and the line, like every
241
+ other write. Piped, `workspace run` answers JSON with `exit_code` and
242
+ `uncommitted`.
243
+ - With a machine of your own, prefer `site pull`, your own tools, then
244
+ `site push`: same checks, and you keep your editor and your terminal.
245
+
246
+ ### Building
247
+
248
+ ```bash
249
+ atelier201 builds start --wait # polls every 2 s, 5 minutes at most
250
+ ```
251
+
252
+ `--wait` exits `0` when the build is `ready`. On failure it exits `6` and the
253
+ error message ends with the compiler's log. On timeout it exits `1`; check with
254
+ `atelier201 builds get <build_id>`. A ready build of the same revision is reused.
255
+ Without `--wait` you get a `queued` build and poll `builds get` yourself until
256
+ `ready`, `failed` or `cancelled`.
257
+
258
+ ### Publishing (visible on the internet)
259
+
260
+ ```bash
261
+ atelier201 publish review # free: which build, blockers, expected_generation
262
+ atelier201 publish --yes # the newest ready build of the draft
263
+ atelier201 publish --build <build_id> --yes # exactly this one
264
+ atelier201 publish history # ids of past publications
265
+ atelier201 publish rollback --publication <id> --yes
266
+ atelier201 publish unpublish --yes # takes the site offline, deletes nothing
267
+ ```
268
+
269
+ Each reads the state first and sends the `expected_generation` it read, so a
270
+ publish by someone else in between is refused with exit `6` instead of
271
+ overwritten. Without `--yes` and without a terminal they exit `2`, write
272
+ nothing, and print the exact command to re-run (with `--build` pinned). A build
273
+ that cannot be published (not ready, blockers) exits `6`.
274
+
275
+ ### Domains
276
+
277
+ ```bash
278
+ atelier201 domains add www.example.com # paid plans; prints the DNS records to create
279
+ atelier201 domains check <domain_id> # also checked by itself every five minutes
280
+ atelier201 domains main <domain_id> # redirects the other addresses; rebuild, then publish
281
+ ```
282
+
283
+ ### Before anybody has signed in
284
+
285
+ ```bash
286
+ atelier201 site push --guest --name "Maison Dupont" [--slug maison-dupont]
287
+ ```
288
+
289
+ Works with no credential. It prepares a demo site, sends the folder, builds it
290
+ and prints two lines: `See the site: <url>` and `Make it yours (private link,
291
+ give it only to the owner): <url>`. Give the owner the second one and never post
292
+ it publicly. The write token it receives lasts 2 hours, is stored only in
293
+ `.atelier201/site.json` (mode `0600`) and is never printed. A second
294
+ `site push --guest` in the same folder reuses it (3 builds per guest site, then
295
+ exit `6` with the way to sign in). The demo expires after 7 days.
296
+
297
+ ## Commands
298
+
299
+ None of the commands cost credits. The site commands are above; these read the
300
+ workspace.
301
+
302
+ ### Reading
303
+
304
+ ```bash
305
+ atelier201 account # workspace, credit balance, this credential's scopes
306
+ atelier201 credits # balance, and every grant with its expiry
307
+ atelier201 usage --from 2026-01-01 --to 2026-01-31 --granularity day
308
+ ```
309
+
310
+ ### Manuals
311
+
312
+ Read the manual that covers your job before you start it (create a site, edit
313
+ content, change the design, import data, fix a build, publish). Public text, no
314
+ sign-in needed.
315
+
316
+ ```bash
317
+ atelier201 skills list # id, title and when to read it
318
+ atelier201 skills get create-site # one manual as Markdown (--json for the object)
319
+ ```
320
+
321
+ ### Escape hatches
322
+
323
+ ```bash
324
+ atelier201 api GET /sites
325
+ atelier201 api POST /sites --body '{"name":"Maison Dupont"}'
326
+ atelier201 doctor
327
+ atelier201 mcp
328
+ atelier201 feedback send "What went wrong, and what you expected"
329
+ ```
330
+
331
+ `atelier201 api` reaches any endpoint, including one added after this CLI version, so
332
+ a new capability never waits for a release. Prefer the native verbs where they
333
+ exist: they validate arguments before spending a request and tell you what to do
334
+ next.
335
+
336
+ `atelier201 doctor` checks connectivity, credentials, version and clock skew, which
337
+ covers most of what goes wrong before it is worth investigating anything else.
338
+
339
+ ## Scopes
340
+
341
+ Seven. Six are live:
342
+
343
+ ```
344
+ account:read usage:read sites:read sites:write sites:publish domains:write
345
+ ```
346
+
347
+ `sites:read` (everything that only reads), `sites:write` (edit the draft, build,
348
+ preview, upload), `sites:publish` (`publish`, `rollback`, `unpublish`,
349
+ `sites delete`) and `domains:write`. A missing one is exit `3` naming the scope. A
350
+ credential can lack `sites:publish` and `domains:write` on purpose: ask the
351
+ owner to publish rather than looking for a way around it. One more can be granted
352
+ but no endpoint honours it yet:
353
+
354
+ ```
355
+ webhooks:write
356
+ ```
357
+
358
+ A credential may therefore report a scope that does nothing today. Trust
359
+ `capabilities` from `atelier201 account`, not the scope list, to decide whether a
360
+ feature exists. (Credentials issued before the template's example feature was
361
+ removed may still hold `tasks:*`; they are inert and not reported.)
362
+
363
+ **`atelier201 auth login` requests the six live scopes.** No scope gates spending
364
+ today. If one ever does, a login will deliberately omit it: an OAuth login never
365
+ grants spending power by default, and you pass `--scope` explicitly to opt in. An
366
+ API key's scopes are whatever an admin chose when creating it, unaffected by this
367
+ default.
368
+
369
+ Missing one is exit `3` with `code: "insufficient_scope"`, naming the scope
370
+ required. The effective set is the credential's scopes ∩ (the member ceiling,
371
+ for a person-owned credential), and it is reported by
372
+ `atelier201 account` under `credential.scopes`.
373
+
374
+ ## Rate limits
375
+
376
+ 240 requests per minute per credential, plus a 40-per-10-seconds burst ceiling,
377
+ identical on every plan. The CLI retries `429` automatically, honouring
378
+ `Retry-After`, up to three times with jittered backoff.
package/README.md CHANGED
@@ -1,3 +1,146 @@
1
- # Temporary Holding Version
1
+ # @atelier201/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The product from a terminal, a CI job, or an AI agent.
4
+
5
+ ```bash
6
+ npm install -g @atelier201/cli
7
+ # or, without installing:
8
+ npx @atelier201/cli account
9
+ ```
10
+
11
+ Requires Node 20 or later.
12
+
13
+ ## Getting started
14
+
15
+ ```bash
16
+ atelier201 auth login # opens a browser, stores the token in your keychain
17
+ atelier201 account
18
+ ```
19
+
20
+ For CI, use an API key created in the app's developer settings:
21
+
22
+ ```bash
23
+ export ATELIER201_API_KEY="atelier201_live_..."
24
+ atelier201 account
25
+ ```
26
+
27
+ An API key belongs to the WORKSPACE and does not expire when a person leaves,
28
+ which is what makes it the right credential for a job rather than a person.
29
+
30
+ ## Commands
31
+
32
+ ```bash
33
+ # Reading. None of these cost credits.
34
+ atelier201 account # workspace, plan, limits, scopes
35
+ atelier201 credits # balance and every grant
36
+ atelier201 usage --from 2026-01-01 # credits used over a period
37
+
38
+ # Manuals: read the one that covers your job first. No sign-in needed.
39
+ atelier201 skills list
40
+ atelier201 skills get create-site
41
+
42
+ # Sites: see the section below.
43
+
44
+ # Escape hatches.
45
+ atelier201 api GET /sites
46
+ atelier201 doctor
47
+ atelier201 mcp
48
+ ```
49
+
50
+ ## Sites
51
+
52
+ Atelier201 hosts your Astro website. Nothing in this section costs credits; only
53
+ `publish`, `publish rollback`, `publish unpublish` and `domains` change what
54
+ visitors see.
55
+
56
+ ```bash
57
+ # A project folder, from nothing to online.
58
+ atelier201 sites create "Maison Dupont" --link # creates the site, links this folder
59
+ atelier201 site pull # its files, here
60
+ # ...edit...
61
+ atelier201 site push --build --wait # send the folder, build it, wait
62
+ atelier201 previews create # a private link to look at that build
63
+ atelier201 publish # shows what goes live, asks, then does it
64
+
65
+ # Small changes without a folder.
66
+ atelier201 content set business:/tagline "Fresh bread daily"
67
+ atelier201 files commit --message "Update the menu" --put src/pages/menu.astro=menu.astro
68
+ atelier201 media upload photo.jpg
69
+
70
+ # Looking around.
71
+ atelier201 sites list
72
+ atelier201 files list
73
+ atelier201 history list
74
+ atelier201 builds list
75
+ atelier201 domains add www.example.com # prints the DNS records to create
76
+ ```
77
+
78
+ Every site command takes `--site <id>`, or uses the site linked in the current
79
+ folder (`atelier201 site link --site <id>` writes `.atelier201/site.json`, which holds
80
+ no secret and is added to `.gitignore`).
81
+
82
+ - `site push` sends the folder as it is, except `node_modules`, `dist`, `.astro`,
83
+ `.git`, `.env` files and keys, and whatever your root `.gitignore` lists (50 MB
84
+ at most). It refuses to overwrite changes made on the site since your last
85
+ sync: `site pull` first, or pass `--force`.
86
+ - `site pull` refuses, writing nothing, to overwrite a file you changed since
87
+ the last sync (`--force` overrides).
88
+ - `publish`, `publish rollback`, `publish unpublish` and `sites delete` ask
89
+ before they act. In a script, pass `--yes` (for `sites delete`,
90
+ `--confirm <slug>`).
91
+ - `builds start --wait` waits up to 5 minutes and exits non-zero with the end
92
+ of the build log when the build fails.
93
+
94
+ No account yet? `atelier201 site push --guest --name "Maison Dupont"` puts the folder
95
+ online as a demo without signing in, and prints two links: the demo, and a
96
+ private link to give only to the owner so the site becomes theirs.
97
+
98
+ ## Output
99
+
100
+ **JSON automatically when stdout is not a terminal.** Piping into `jq` just
101
+ works, and no command needs a `--json` flag added in CI. At a terminal you get a
102
+ table. Force either with `--output json|table|ndjson`.
103
+
104
+ ## Exit codes
105
+
106
+ A script can branch without parsing a message:
107
+
108
+ | Code | Meaning |
109
+ |---|---|
110
+ | 0 | success |
111
+ | 1 | an unexpected failure |
112
+ | 2 | bad usage, or a request the server rejected as invalid |
113
+ | 3 | authentication |
114
+ | 4 | not found |
115
+ | 5 | rate limited |
116
+ | 6 | conflict |
117
+
118
+ `insufficient_credits` maps to 2 on purpose: a job that runs out of money must
119
+ stop and tell a human, not retry.
120
+
121
+ ## For agents
122
+
123
+ ```bash
124
+ atelier201 help --json
125
+ ```
126
+
127
+ Prints the whole command tree, the exit codes, the retry policy and the error
128
+ envelope as one machine-readable document. An agent that reads it first stops
129
+ guessing at flags.
130
+
131
+ **Publishing asks before it changes what visitors see.** `publish` shows what
132
+ would go live and waits for a yes. With no terminal (CI, an agent) it refuses and
133
+ names `--yes`; pass it only once `atelier201 publish review` looks right.
134
+
135
+ ## Retries
136
+
137
+ 429 is retried for every command. 408 and 5xx are retried only for idempotent
138
+ requests (RFC 9110 §9.2.2). **A non-idempotent write that fails with a 5xx is
139
+ reported rather than repeated**, because the change may already have been
140
+ applied — re-read the resource before retrying it yourself.
141
+
142
+ A request that carries an `Idempotency-Key` is the exception: the API answers a
143
+ repeat of the same key and the same request with the first result, so the CLI
144
+ retries it after a 5xx. No endpoint accepts the header today.
145
+
146
+ Disable with `--no-retry`.
@@ -0,0 +1,8 @@
1
+ /**
2
+ * GENERATED by scripts/api-types.mjs from ../api-worker/openapi.json. Do not edit.
3
+ * Regenerate with `npm run generate:types`; test/api-types.test.ts fails when this
4
+ * file and the contract disagree.
5
+ */
6
+ /** The values the API accepts, read off the contract instead of copied by hand. */
7
+ export const USAGE_GRANULARITY_VALUES = ["day", "week", "month"];
8
+ //# sourceMappingURL=api-types.generated.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api-types.generated.js","sourceRoot":"","sources":["../src/api-types.generated.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmiCH,mFAAmF;AACnF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAC,MAAM,EAAC,OAAO,CAAU,CAAC"}
@@ -0,0 +1,111 @@
1
+ /**
2
+ * `atelier201 api <METHOD> <path> [--data <json>]` — the escape hatch.
3
+ *
4
+ * A new endpoint is usable the instant it exists, and an agent that has read
5
+ * `openapi.json` is never blocked waiting for us to add a verb. Same
6
+ * credential, same retries, same error envelope as every other command.
7
+ */
8
+ import { readFile } from "node:fs/promises";
9
+ import { usageError } from "../errors.js";
10
+ import { run } from "../run.js";
11
+ const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"];
12
+ export function registerApi(program) {
13
+ program
14
+ .command("api <method> <path>")
15
+ .description("Make a raw authenticated request against the Atelier201 API")
16
+ .option("--data <json>", "Request body: inline JSON, @file, or '-' to read stdin")
17
+ .option("--header <name:value>", "Extra request header; repeatable", collect, [])
18
+ .action(async (method, requestPath, options, command) => {
19
+ await run(command, async (session) => {
20
+ const verb = normalizeMethod(method);
21
+ const normalizedPath = normalizeApiPath(requestPath);
22
+ const body = await resolveData(options.data ? String(options.data) : undefined);
23
+ const response = await session.client.request(verb, normalizedPath, {
24
+ body,
25
+ headers: parseHeaders(options.header),
26
+ });
27
+ // The body is printed verbatim, envelope included: this command is the
28
+ // one place a caller wants the API's exact response, not our view of it.
29
+ session.printer.data(response.body ?? { status: response.status });
30
+ });
31
+ });
32
+ }
33
+ export function normalizeMethod(method) {
34
+ const upper = method.trim().toUpperCase();
35
+ if (!METHODS.includes(upper)) {
36
+ throw usageError(`'${method}' is not an HTTP method this CLI sends. Use one of: ${METHODS.join(", ")}.`, "method");
37
+ }
38
+ return upper;
39
+ }
40
+ /**
41
+ * Accepts every form a person is likely to type: `/v1/account`, `v1/account`,
42
+ * `/account`, `account`, and any of those with a query string. The client's
43
+ * base URL already ends in `/v1`, so a leading `v1` would double it.
44
+ */
45
+ export function normalizeApiPath(input) {
46
+ let value = input.trim();
47
+ if (!value)
48
+ throw usageError("The path is empty. Try 'atelier201 api GET /v1/account'.", "path");
49
+ if (/^https?:\/\//i.test(value)) {
50
+ throw usageError(`Pass a path, not a full URL. Use '${new URL(value).pathname}${new URL(value).search}', the base URL comes from ATELIER201_API_URL.`, "path");
51
+ }
52
+ if (!value.startsWith("/"))
53
+ value = `/${value}`;
54
+ value = value.replace(/^\/v1(?=\/|$)/i, "");
55
+ if (!value.startsWith("/"))
56
+ value = `/${value}`;
57
+ return value === "/" ? "/" : value.replace(/\/+$/, "") || "/";
58
+ }
59
+ export function parseHeaders(values) {
60
+ const headers = {};
61
+ for (const value of values) {
62
+ const index = value.indexOf(":");
63
+ if (index <= 0) {
64
+ throw usageError(`--header expects 'Name: value', got '${value}'.`, "header");
65
+ }
66
+ const name = value.slice(0, index).trim();
67
+ if (/^authorization$/i.test(name)) {
68
+ throw usageError("--header cannot set Authorization; the CLI supplies the credential itself.", "header");
69
+ }
70
+ headers[name] = value.slice(index + 1).trim();
71
+ }
72
+ return headers;
73
+ }
74
+ /** `--data` is inline JSON, `@path/to/file.json`, or `-` for stdin. */
75
+ export async function resolveData(data, readers = {}) {
76
+ if (data === undefined)
77
+ return undefined;
78
+ let raw = data;
79
+ if (data === "-") {
80
+ raw = await (readers.readStdin ?? readStdin)();
81
+ }
82
+ else if (data.startsWith("@")) {
83
+ const file = data.slice(1);
84
+ raw = await (readers.readFile ?? ((f) => readFile(f, "utf8")))(file).catch((error) => {
85
+ throw usageError(`Could not read '${file}': ${error instanceof Error ? error.message : String(error)}`, "data");
86
+ });
87
+ }
88
+ if (!raw.trim())
89
+ return undefined;
90
+ try {
91
+ return JSON.parse(raw);
92
+ }
93
+ catch (error) {
94
+ throw usageError(`--data is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, "data");
95
+ }
96
+ }
97
+ function readStdin() {
98
+ return new Promise((resolve, reject) => {
99
+ let buffer = "";
100
+ process.stdin.setEncoding("utf8");
101
+ process.stdin.on("data", (chunk) => {
102
+ buffer += chunk;
103
+ });
104
+ process.stdin.on("end", () => resolve(buffer));
105
+ process.stdin.on("error", reject);
106
+ });
107
+ }
108
+ function collect(value, previous) {
109
+ return [...previous, value];
110
+ }
111
+ //# sourceMappingURL=api.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/commands/api.ts"],"names":[],"mappings":"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"}