flypod 0.7.0 → 0.9.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.
package/README.md CHANGED
@@ -1,243 +1,570 @@
1
1
  # flypod
2
2
 
3
- Zero-auth, agent-native deploy primitive. Drop a directory of files, get a live URL back. No account, no config, no build pipeline required.
3
+ **Drop a folder. Get a URL. There is no step three.**
4
4
 
5
5
  ```sh
6
6
  npx flypod ./dist
7
7
  # → https://ab12cd34.flypod.dev
8
8
  ```
9
9
 
10
- ## How it works
11
-
12
- - **No auth to deploy** — POST a zip, receive a URL + one-time tokens
13
- - **Ephemeral by default** — anonymous deploys expire in 14 days
14
- - **Optional accounts** — sign in once at [`flypod.dev/account`](https://flypod.dev/account), then run `flypod login` to connect the CLI through a browser device flow. Owned deploys do not expire.
15
- - **Rollback built-in** — every deploy is versioned; roll back with a single call
16
- - **Render loop** — optional headless screenshot + console capture on every deploy
17
-
18
- ---
19
-
20
- ## CLI
21
-
22
- ```sh
23
- npx flypod
24
- # auto-detects dist/, build/, out/, .output/public, .vercel/output/static, public, _site
25
- # (the first one containing an index.html wins)
26
-
27
- npx flypod ./somewhere # or give it an explicit path
28
10
  ```
11
+ flypod v0.8.0
29
12
 
30
- What you see:
31
-
32
- ```
33
- flypod v0.1.0
34
-
13
+ account anonymous · deploy now, flypod login later to keep it
35
14
  source dist 12 files · 1.2 MB
36
- ✓ Deployed in 0.8s
15
+ ✓ Deployed in 0.9s
37
16
 
38
17
  ────────────────────────────────────────────────────────
39
18
  ● Live
40
19
  https://ab12cd34.flypod.dev
41
20
  ────────────────────────────────────────────────────────
42
21
 
43
- expires in 14 days · ephemeral by default
22
+ expires in 14 days · `flypod login` keeps this and every other site you deployed here
44
23
 
45
24
  ship a change flypod update (new version of this site)
46
25
  roll back flypod rollback
47
26
  history flypod versions
48
27
  ```
49
28
 
50
- `flypod` always creates a **new site**. To ship changes to the *same* site as a
51
- new version, use `flypod update` (see below) — not `flypod` again.
29
+ That URL is real, public, and HTTPS. Send it to someone. (The elapsed time above
30
+ is one illustrative run, not a benchmark — your line shows whatever your deploy
31
+ actually took.)
52
32
 
53
- ### Agent-friendly modes
33
+ **Nothing has to be set up first.** No account, no config file, no project to
34
+ create, no framework to detect, no dashboard to learn. Which is the interesting
35
+ part: take the human step out of the deploy path and the deploy path becomes
36
+ automatable. A person, a shell script, a CI job, or a coding agent can all
37
+ finish a deploy unattended, in one call, with nothing provisioned in advance.
54
38
 
55
- The CLI detects whether stderr is a TTY. When piped (or under an agent), the
56
- animations and decorations are stripped automatically. Two flags give you
57
- stable machine output:
39
+ **And nothing is stuck.** Every deploy is a version, so shipping a change keeps
40
+ the same URL and a bad ship is one command from undone:
58
41
 
59
42
  ```sh
60
- npx flypod --json
61
- # {
62
- # "ok": true,
63
- # "url": "https://ab12cd34.flypod.dev",
64
- # "site_id": "ab12cd34",
65
- # "version_id": "...",
66
- # "expires_at": 1782929906088,
67
- # "manage_token": "...",
68
- # "source": "dist",
69
- # "files": 12,
70
- # "bytes": 1234567,
71
- # "elapsed_ms": 812
72
- # }
73
-
74
- npx flypod --quiet
75
- # stdout: https://ab12cd34.flypod.dev
76
- # stderr: <manage_token>
77
- ```
78
-
79
- The URL is always printed alone on stdout in pretty and quiet modes, so
80
- `URL=$(npx flypod --quiet)` and `npx flypod | tee url.txt` both work.
81
-
82
- ### Flags
43
+ flypod update # new version, same URL
44
+ flypod versions # every version, newest first
45
+ flypod rollback # the previous one is live again
46
+ ```
83
47
 
84
- | Flag | Description |
85
- |------|-------------|
86
- | `--json` | Emit a complete JSON result on stdout (replaces pretty output) |
87
- | `-q, --quiet` | Print only the URL on stdout and the manage token on stderr |
88
- | `-h, --help` | Show usage |
89
- | `-v, --version` | Print the version |
48
+ A deploy made without an account is **temporary** — it expires in 14 days, which
49
+ is right for a preview or a demo. `flypod login` makes it **yours**: no expiry,
50
+ listed under `flypod list`.
90
51
 
91
- ### Environment
52
+ | State | What it means |
53
+ |-------|---------------|
54
+ | **Temporary** | An anonymous deploy. Live immediately, expires in 14 days. |
55
+ | **Yours** | Attached to an account. No expiry, listed under `flypod list`. |
92
56
 
93
- | Variable | Description |
94
- |----------|-------------|
95
- | `FLYPOD_TOKEN` | Use an existing account session token without writing a login file (agents / CI). Takes precedence over a saved session |
96
- | `DEPLOY_URL` | Override the deploy server (default: `https://flypod.dev`) |
97
- | `NO_COLOR` | Disable ANSI colors |
98
- | `FORCE_COLOR` | Force colors even when stderr is not a TTY |
57
+ ```sh
58
+ flypod ./dist # temporary
59
+ flypod login # everything you deployed on this machine becomes yours
60
+ ```
61
+
62
+ That's the whole ownership model. `flypod login` claims **every** anonymous site
63
+ this machine remembers, not just the last one — so "deploy now, log in whenever"
64
+ really is the path. You never have to learn what a token is.
65
+
66
+ Before you start, [flypod.dev/limits](https://flypod.dev/limits) is the honest
67
+ list of what flypod does and does not do — static files only, no server code, no
68
+ build step, 14-day anonymous expiry, and the upload sizes the service ships
69
+ with. It is worth ninety seconds; the short version is
70
+ [below](#what-flypod-doesnt-do).
99
71
 
100
- ### Install globally to skip the package runner
72
+ ---
73
+
74
+ ## Teach your coding agents to deploy
75
+
76
+ If you work with a coding agent, this is the command that matters. One run
77
+ writes an [Agent Skill](https://agentskills.io) into your repo, and from then on
78
+ the agent deploys without being told how:
101
79
 
102
80
  ```sh
103
- bun add --global flypod
104
- flypod
81
+ npx flypod install skill
105
82
  ```
106
83
 
107
- ### Exit codes
84
+ It writes into the two directories every major agent reads:
108
85
 
109
- | Code | Meaning |
110
- |------|---------|
111
- | `0` | Success |
112
- | `1` | Runtime error (no build folder, network failure, deploy rejected) |
113
- | `2` | Usage error (unknown flag) |
86
+ | Directory | Read by |
87
+ |-----------|---------|
88
+ | `.claude/skills/flypod/` | Claude Code |
89
+ | `.agents/skills/flypod/` | Codex, Cursor, Gemini CLI, GitHub Copilot |
90
+
91
+ Both get the same files, because `SKILL.md` is one open format now rather than a
92
+ different dialect per vendor. If you manage skills with the `skills` CLI
93
+ instead, the same payload installs from its public packaging repo:
94
+
95
+ ```sh
96
+ npx skills add flypod-dev/flypod-skill
97
+ ```
98
+
99
+ **What the agent learns.** A short `SKILL.md` it always loads: the deploy
100
+ command, how to read `--json` and surface the `url`, how to check `warnings`
101
+ before reporting success, why `flypod update` and not a second `flypod`, the
102
+ temporary → `flypod login` → yours model (and that tokens are secrets an agent
103
+ never needs to save), the `FLYPOD_TOKEN` path for headless runs, and the
104
+ static-only boundary so it doesn't pick flypod for an app with server routes.
105
+
106
+ Alongside it, reference docs the agent opens only when the task needs them — so
107
+ they cost nothing until they're wanted:
108
+
109
+ ```
110
+ .claude/skills/flypod/
111
+ ├── SKILL.md the deploy loop — always loaded
112
+ └── reference/
113
+ ├── updates-and-versions.md update, versions, rollback, --site
114
+ ├── publishing-markdown.md deploying .md as a rendered site
115
+ ├── comments.md review loop on a deployed preview
116
+ └── troubleshooting.md exit codes, warnings, CI, env vars
117
+ ```
118
+
119
+ In a terminal you get a checklist:
120
+
121
+ ```
122
+ flypod · teach your agents to deploy
123
+
124
+ Install the flypod skill into:
125
+
126
+ › ◉ Claude Code .claude/skills/flypod/ — loaded on demand
127
+ ◉ Agent Skills (shared) .agents/skills/flypod/ — Codex, Cursor, Gemini CLI, Copilot
128
+
129
+ ↑/↓ move · space toggle · a all · enter confirm · esc cancel
130
+ ```
131
+
132
+ Piped, or run by an agent, it's non-interactive and writes both — so it drops
133
+ cleanly into a setup script.
134
+
135
+ ```sh
136
+ flypod install skill # both directories
137
+ flypod install skill --claude # just the Claude Code skill
138
+ flypod install skill --agents # just .agents/skills/
139
+ flypod install skill --global # user level: ~/.claude, ~/.agents
140
+ flypod install skill --list # where each target would go
141
+ flypod install skill --dry-run # print the planned paths, write nothing
142
+ flypod install skill --all # skip the picker, write everything
143
+ ```
144
+
145
+ `--cursor`, `--codex`, `--copilot`, `--gemini`, `--windsurf`, `--cline`, and
146
+ `--roo` remain as aliases for `--agents`; those agents all read
147
+ `.agents/skills/` now.
148
+
149
+ It's idempotent. Every file inside a skill directory is flypod-owned and
150
+ rewritten wholesale; files that are already correct are reported as up to date
151
+ and left alone. Nothing outside those two directories is touched — if you still
152
+ have flypod instructions in an `AGENTS.md` or a `.cursor/rules/` file from an
153
+ earlier version, the command points them out and leaves the removal to you.
114
154
 
115
155
  ---
116
156
 
117
- ## Versions and rollback
157
+ ## Contents
158
+
159
+ - [How do I deploy a folder?](#how-do-i-deploy-a-folder)
160
+ - [How do I ship a change to the same site?](#how-do-i-ship-a-change-to-the-same-site)
161
+ - [How do I roll back?](#how-do-i-roll-back)
162
+ - [How do I use flypod from an agent or CI?](#how-do-i-use-flypod-from-an-agent-or-ci)
163
+ - [Deploying Markdown](#deploying-markdown)
164
+ - [Flags](#flags)
165
+ - [Environment variables](#environment-variables)
166
+ - [Exit codes](#exit-codes)
167
+ - [How long does a deploy last?](#how-long-does-a-deploy-last)
168
+ - [What flypod doesn't do](#what-flypod-doesnt-do)
169
+ - [Comments on a deployed site](#comments-on-a-deployed-site)
170
+ - [Accounts](#accounts)
171
+ - [What does flypod write to disk?](#what-does-flypod-write-to-disk)
172
+ - [Library API](#library-api)
173
+ - [HTTP API](#http-api)
174
+
175
+ ## How do I deploy a folder?
176
+
177
+ Point `flypod` at the folder of built files. It zips them, uploads them, and
178
+ prints the live URL.
118
179
 
119
- Every deploy is a **version**, identified by the content hash of its files.
120
- `flypod` creates a brand-new site; `flypod update` adds a version to a site you
121
- already made and points the live URL at it. Old versions are kept, so rollback
122
- is instant. Re-deploying identical content is a no-op (same hash → same
123
- version).
180
+ ```sh
181
+ npx flypod ./dist # a folder
182
+ npx flypod index.html # a single file
183
+ npx flypod # auto-detect the build folder
184
+ ```
185
+
186
+ With no path, flypod tries these in order and takes the first one that exists
187
+ **and contains an `index.html`**:
188
+
189
+ ```
190
+ dist · build · out · .output/public · .vercel/output/static · public · _site
191
+ ```
192
+
193
+ The URL is always printed alone on **stdout**; everything else goes to stderr.
194
+ `URL=$(npx flypod -q)` and `npx flypod | tee url.txt` both work.
195
+
196
+ `flypod` always creates a **new site**. To ship changes to a site you already
197
+ made, use [`flypod update`](#how-do-i-ship-a-change-to-the-same-site) — not
198
+ `flypod` again.
199
+
200
+ To skip the package runner:
124
201
 
125
202
  ```sh
126
- flypod ./dist # deploy v1 → new site, prints the URL
127
- flypod update # ship changes to that same site → v2 (now live)
128
- flypod versions # list every version, newest first (live one marked)
129
- flypod rollback # make the previous version live again
130
- flypod rollback <id> # roll back to a specific version (full id or a prefix)
203
+ npm install -g flypod # or: bun add --global flypod
204
+ flypod ./dist
131
205
  ```
132
206
 
133
- **How `update`/`versions`/`rollback` find the site.** On the first deploy,
134
- flypod records which site a folder maps to under your config dir
135
- (`projects.json`, next to the session — **never written into your repo**). From
136
- that folder the commands need no flags. The registry is self-cleaning: entries
137
- for expired sites are pruned automatically and it is capped at 64 projects.
207
+ ## How do I ship a change to the same site?
208
+
209
+ Run `flypod update` from the same folder. It adds a new **version** to the
210
+ existing site and points the live URL at it — the URL doesn't change.
138
211
 
139
- To act on a site from anywhere — or in a stateless agent that kept the
212
+ ```sh
213
+ flypod ./dist # v1 → new site, prints the URL
214
+ flypod update # ship changes → v2 (now live, same URL)
215
+ flypod update ./dist # same, with an explicit path
216
+ ```
217
+
218
+ Every deploy is a version, identified by the content hash of its files.
219
+ Re-deploying byte-identical content resolves to the **same version id** and adds
220
+ nothing to the history — the CLI just reports that version as live. Old versions
221
+ are kept, which is what makes rollback instant.
222
+
223
+ **How `update` knows which site.** On the first deploy, flypod records the
224
+ folder → site mapping in its own config dir (`projects.json`, next to the
225
+ session — **never written into your repo**). From that folder, `update`,
226
+ `versions`, and `rollback` need no flags.
227
+
228
+ To act on a site from anywhere — or from a stateless agent that kept the
140
229
  `site_id` from the deploy output — pass `--site`:
141
230
 
142
231
  ```sh
143
232
  flypod update --site <id> ./dist
144
233
  flypod versions --site <id>
145
234
  flypod rollback --site <id> <version>
146
- flypod forget [--site <id>] # drop the folder→site memory
235
+ flypod forget [--site <id>] # drop the folder → site memory
147
236
  ```
148
237
 
149
- **Auth.** Owned sites (after `flypod login`) authorize by your account key.
150
- Anonymous sites use a per-site manage token, which flypod stashes in the
151
- registry for you — pass `--token <manage_token>` to use one from a machine that
152
- doesn't remember it.
238
+ **Authorization.** Owned sites (after `flypod login`) authorize with your
239
+ account session. Anonymous sites use a per-site `manage_token`, which flypod
240
+ stashes in the registry for you — pass `--token <manage_token>` to act on one
241
+ from a machine that doesn't remember it.
153
242
 
154
- `--json` is supported on all three for stable, scriptable output.
243
+ **Deploy output doesn't print the manage token at all.** With no account,
244
+ possession of that token *is* ownership: whoever has it can update, roll back, or
245
+ claim the site. The server stores only its hash, so a leaked token can't be
246
+ revoked — only outlived.
155
247
 
156
- ---
248
+ You don't need to see it, and you don't need to save it anywhere. flypod writes
249
+ it to `projects.json` (mode 0600) keyed by the folder you deployed from, so
250
+ `update`, `rollback`, and `versions` just work. And `flypod login` uses those
251
+ stored tokens to attach **every** anonymous site this machine remembers, in one
252
+ step — so the whole ownership story is *deploy now, log in whenever*.
253
+
254
+ Run `flypod token` for the one case that needs the plaintext — acting on a site
255
+ from a machine that doesn't remember it:
256
+
257
+ ```sh
258
+ flypod token # prints it to stdout, so `TOKEN=$(flypod token)` works
259
+ flypod token --site <id>
260
+ ```
157
261
 
158
- ## Teach your coding agents
262
+ (If the site is *yours*, running `flypod login` on the second machine is the
263
+ better move: a session can be replaced, a `manage_token` cannot.)
159
264
 
160
- One command writes a small instruction file into your coding agents so they know
161
- how to deploy with flypod — no config, no copy-paste.
265
+ **The one exception: if flypod couldn't save the link, it tells you.** On a
266
+ read-only or ephemeral config dir — the classic CI container — the registry
267
+ write fails and nobody is holding the site's credential. flypod then prints a
268
+ loud warning plus the token in normal output, and emits the token on **stderr**
269
+ under `-q`. It will never leave you with a live site it can't get back to,
270
+ silently.
271
+
272
+ `--json` still includes `manage_token` for programmatic use, and
273
+ `FLYPOD_SHOW_TOKEN=1` restores the old inline output.
274
+
275
+ ## How do I roll back?
276
+
277
+ `flypod rollback` makes the previous version live again, immediately.
162
278
 
163
279
  ```sh
164
- npx flypod install skill
280
+ flypod versions # every version, newest first (the live one is marked)
281
+ flypod rollback # previous version becomes live
282
+ flypod rollback <id> # a specific version — full id or an unambiguous prefix
165
283
  ```
166
284
 
167
- Run in a terminal, it shows a checklist of the agents it found. It always writes
168
- the universal [`AGENTS.md`](https://agents.md) (read by Codex, Cursor, Copilot,
169
- Gemini, Zed, Jules, and ~20 more) plus a first-class **Claude Code** skill at
170
- `.claude/skills/flypod/SKILL.md`, and pre-selects any other agents it detects in
171
- your repo (Cursor, Windsurf, Cline, Roo, …).
285
+ `versions` prints tab-separated `version_id created_at live` on stdout,
286
+ with `created_at` as a readable UTC date. `--json` keeps it as epoch
287
+ milliseconds, so scripts and agents parse the same value they always did.
288
+ `--json` is supported on `update`, `versions`, and `rollback` for stable,
289
+ scriptable output.
290
+
291
+ ## How do I use flypod from an agent or CI?
172
292
 
293
+ Use `--json` and read the `url` field. The CLI also detects when stderr isn't a
294
+ TTY and strips animations automatically.
295
+
296
+ ```sh
297
+ npx flypod ./dist --json
173
298
  ```
174
- flypod · teach your agents to deploy
175
299
 
176
- Install the flypod skill into:
300
+ ```json
301
+ {
302
+ "ok": true,
303
+ "url": "https://ab12cd34.flypod.dev",
304
+ "site_id": "ab12cd34",
305
+ "version_id": "…",
306
+ "expires_at": 1782929906088,
307
+ "manage_token": "…",
308
+ "claim_token": "…",
309
+ "source": "dist",
310
+ "files": 12,
311
+ "bytes": 1234567,
312
+ "elapsed_ms": 812,
313
+ "healed": ["spa-fallback"],
314
+ "warnings": []
315
+ }
316
+ ```
177
317
 
178
- › ◉ AGENTS.md universal — Codex, Cursor, Copilot, Gemini, Zed, Jules, +more
179
- ◉ Claude Code .claude/skills/flypod/SKILL.md — loaded on demand
180
- ◉ Cursor .cursor/rules/flypod.mdc · detected
181
- ◯ Windsurf .windsurf/rules/flypod.md
318
+ **Read `warnings` before you report success.** A deploy can exit 0 and still
319
+ serve a site that's broken for visitors, and this array is the only signal that
320
+ says so. Each entry carries a `code` and a `fix_recipe` naming the change to
321
+ make — `missing-index` when nothing is served at `/`, `not-spa` when the build
322
+ ships scripts alongside visible body content, so client-side routing fallback
323
+ stays off and deep links will 404 on refresh.
182
324
 
183
- ↑/↓ move · space toggle · a all · enter confirm · esc cancel
325
+ `healed` is the other half: problems flypod fixed on your behalf. `spa-fallback`
326
+ there means it recognised a single-page app, so unknown paths serve `index.html`
327
+ and client-side routing works with nothing configured.
328
+
329
+ For an agent, that pair is a closed loop — deploy, read the receipt, apply the
330
+ `fix_recipe`, `flypod update` — without a human in it.
331
+
332
+ `expires_at` is epoch **milliseconds** while the site is temporary, and `null`
333
+ once it's yours. On an authenticated deploy `owner_account_id` is present and
334
+ `claim_token` is absent — keys that don't apply are omitted rather than emitted
335
+ as `null`. On failure: `{"ok": false, "error": "…"}` with exit code 1 — so
336
+ `--json` is safe to parse unconditionally.
337
+
338
+ Or capture just the URL:
339
+
340
+ ```sh
341
+ URL=$(npx flypod ./dist --quiet) # stdout: the URL, and nothing else
184
342
  ```
185
343
 
186
- It's idempotent — shared files (`AGENTS.md`, `copilot-instructions.md`, `GEMINI.md`)
187
- get a fenced `flypod` block that re-runs replace in place, never clobbering your
188
- own content. Dedicated rule files are flypod-owned and rewritten wholesale.
344
+ `-q` prints no credential. It's the CI and agent mode, which is exactly where a
345
+ secret on stderr ends up in a build log that outlives the site — and a
346
+ `manage_token` can't be rotated. Machines that need it use `--json`. (The single
347
+ exception is the couldn't-save-the-link case above, where `-q` does emit the
348
+ token on stderr, because otherwise nobody would hold it.)
189
349
 
190
- Non-interactive when piped or under an agent (writes the same defaults), so it
191
- drops cleanly into setup scripts and CI.
350
+ For an attributed deploy with no login file and no browser, set a session
351
+ token in the environment:
192
352
 
193
353
  ```sh
194
- flypod install skill --all # write files for every supported agent
195
- flypod install skill --claude # just the Claude Code skill
196
- flypod install skill --global # install at the user level (~/.claude + ~/.codex; add --all for ~/.gemini)
197
- flypod install skill --list # show what's detected and where it would go
198
- flypod install skill --dry-run # print the planned paths, write nothing
199
- ```
200
-
201
- | Target | File written |
202
- |--------|--------------|
203
- | `--agents` | `AGENTS.md` (universal) |
204
- | `--claude` | `.claude/skills/flypod/SKILL.md` |
205
- | `--cursor` | `.cursor/rules/flypod.mdc` |
206
- | `--copilot` | `.github/copilot-instructions.md` |
207
- | `--windsurf` | `.windsurf/rules/flypod.md` |
208
- | `--cline` | `.clinerules/flypod.md` |
209
- | `--roo` | `.roo/rules/flypod.md` |
210
- | `--gemini` | `GEMINI.md` |
354
+ FLYPOD_TOKEN=<session-token> npx flypod ./dist --json
355
+ ```
211
356
 
212
- ---
357
+ ## Deploying Markdown
358
+
359
+ Point flypod at `.md` files and it renders them into a browsable site — no
360
+ static-site generator, no theme, no build step.
361
+
362
+ ```sh
363
+ npx flypod ./report.md # one document
364
+ npx flypod ./notes # a folder of documents
365
+ ```
366
+
367
+ Rendering kicks in when the deploy has **no `index.html` at its root** and at
368
+ least one `.md`, `.markdown`, or `.mdx` file. That condition is deliberate: a
369
+ real static site that happens to ship a stray `README.md` is never hijacked.
370
+
371
+ You get one page per document, navigation across all of them, a title from the
372
+ first `#` heading, light and dark themes applied before first paint, and
373
+ sanitized HTML — inline `<script>`, `on*` attributes, and `javascript:` links
374
+ are stripped.
375
+
376
+ The Markdown sources survive. A browser opening the URL gets the styled page; a
377
+ client that asks for Markdown gets the original back from the same URL:
378
+
379
+ ```sh
380
+ curl -H 'Accept: text/markdown' https://ab12cd34.flypod.dev/guide.html
381
+ ```
382
+
383
+ ## Flags
384
+
385
+ Deploy flags:
386
+
387
+ | Flag | Description |
388
+ |------|-------------|
389
+ | `--json` | Emit a complete JSON result on stdout (replaces the pretty output) |
390
+ | `-q`, `--quiet` | Print only the URL on stdout, and nothing else |
391
+ | `--comments` | Enable comments on the new site (requires being signed in) |
392
+ | `--mode <mode>` | With `--comments`: `anonymous` (default), `passcode`, or `approved` |
393
+ | `-h`, `--help` | Show usage |
394
+ | `-v`, `--version` | Print the version |
395
+
396
+ Targeting flags, on `update` / `versions` / `rollback` / `forget`:
397
+
398
+ | Flag | Description |
399
+ |------|-------------|
400
+ | `--site <id>` | The site to act on, instead of the folder's remembered site |
401
+ | `--token <tok>` | A site's `manage_token`, for anonymous sites on a machine that doesn't remember it |
402
+ | `--json` | Stable JSON on stdout |
403
+ | `-q`, `--quiet` | Minimal output (`update` only) |
404
+
405
+ ## Environment variables
406
+
407
+ | Variable | Description |
408
+ |----------|-------------|
409
+ | `FLYPOD_TOKEN` | Deploy as your account without logging in (agents / CI). Takes precedence over a saved session |
410
+ | `DEPLOY_URL` | The deploy server (default: `https://flypod.dev`) |
411
+ | `FLYPOD_CONFIG_DIR` | Where the CLI keeps its session + folder memory |
412
+ | `FLYPOD_SOURCE` | Override how the deploy reports its surface (`cli`, `skill`, `library`) |
413
+ | `FLYPOD_SHOW_TOKEN` | Set to `1` to print the site's manage token inline on deploy (off by default) |
414
+ | `NO_COLOR` | Disable ANSI colors |
415
+ | `FORCE_COLOR` | Force colors even when stderr is not a TTY |
416
+
417
+ `FLYPOD_API_KEY` is still read as a last-resort fallback for older setups; new
418
+ setups should use `FLYPOD_TOKEN`.
419
+
420
+ ## Exit codes
421
+
422
+ | Code | Meaning |
423
+ |------|---------|
424
+ | `0` | Success |
425
+ | `1` | Runtime error — no build folder, network failure, deploy rejected, unauthorized |
426
+ | `2` | Usage error — unknown flag, unknown subcommand, missing argument |
427
+ | `3` | `flypod comments`: not signed in, or the token can't perform comment writes |
428
+ | `4` | `flypod comments`: the server returned 5xx |
429
+ | `130` | The interactive skill picker was cancelled; nothing was written |
430
+
431
+ ## How long does a deploy last?
432
+
433
+ Anonymous deploys are **temporary**: they expire 14 days after they're created.
434
+ Signed-in deploys never expire.
213
435
 
214
- ## Library
436
+ The exact moment is in `expires_at` (unix ms) on every deploy result, and the
437
+ days remaining are printed in the CLI output. To make a site permanent, run:
438
+
439
+ ```sh
440
+ flypod login
441
+ ```
442
+
443
+ That's it, and it works in either order. Log in first and every deploy is
444
+ attributed to your account from the start (`expires_at` is `null`). Log in
445
+ afterwards and flypod attaches **every** anonymous site this machine still
446
+ remembers — the whole backlog, in one command, using the tokens it stored for
447
+ you.
448
+
449
+ (`flypod claim <site_id> <claim_token>` still exists for attaching a single site
450
+ by hand, and refuses if that site already belongs to another account. `flypod
451
+ login` is the path you want.)
452
+
453
+ ## What flypod doesn't do
454
+
455
+ Stated up front, as design decisions, so nothing is a surprise on day two. The
456
+ long version, with the reasoning attached, is at
457
+ [flypod.dev/limits](https://flypod.dev/limits).
458
+
459
+ - **Static files only.** HTML, CSS, JS, images, Markdown, assets. If a browser
460
+ can render it, it ships.
461
+ - **No server code.** No functions, no edge middleware, no request handlers.
462
+ - **No databases.** Nothing stateful behind the site.
463
+ - **No build step, and no CI/CD integration.** flypod ships your build *output*;
464
+ it never runs your bundler and has no opinions about your git history. Point
465
+ it at `dist/`, not at the project root.
466
+ - **No custom domains.** Every site lives at `<site-id>.flypod.dev`. There is no
467
+ DNS change to make, which is exactly why a script or an agent can produce a
468
+ working URL unattended.
469
+ - **No dashboard you're expected to live in.** The CLI and the URL are the
470
+ product.
471
+ - **Not permanent by default.** Anonymous deploys last 14 days.
472
+ - **Not anonymous-forever.** Skipping the login removes a blocking step; it
473
+ isn't a hiding place. Deploys are screened and reportable.
474
+
475
+ If you need a running server or a database, flypod is the wrong tool — deploy
476
+ the static output and host the backend elsewhere.
477
+
478
+ ## Comments on a deployed site
479
+
480
+ Deployed sites can carry a comment layer, anchored to text rather than
481
+ coordinates, so notes survive a redeploy. Enabling comments requires an account
482
+ session (`flypod login` or `FLYPOD_TOKEN`).
483
+
484
+ ```sh
485
+ flypod ./dist --comments --mode passcode # on at deploy time
486
+ flypod comments enable --site <id> # on an existing site
487
+ flypod comments mode approved --site <id> # anonymous | passcode | approved
488
+ flypod comments off --site <id> # disable; existing data is kept
489
+ flypod comments list <site> # threads (--json for ND-JSON)
490
+ flypod comments show <site> <thread_id> # a thread with its replies
491
+ flypod comments post <site> --page <p> --target <json> --body <text>
492
+ flypod comments resolve <site> <thread_id>
493
+ flypod comments reopen <site> <thread_id>
494
+ ```
495
+
496
+ Modes: `anonymous` (anyone can comment), `passcode` (a shared passcode gates
497
+ posting), `approved` (comments appear after review).
498
+
499
+ Reviewers need no account in `anonymous` mode, which is the point: ship a
500
+ preview, collect what came back as JSON, fix, `flypod update`, resolve the
501
+ thread.
502
+
503
+ ## Accounts
504
+
505
+ Accounts are the upgrade, not the entry fee. Everything above works without
506
+ one; signing in turns temporary sites into yours.
507
+
508
+ ```sh
509
+ flypod login # approve this CLI in your browser (device flow)
510
+ flypod login --token <t> # save a session token directly, no browser
511
+ flypod list # your sites (JSON on stdout)
512
+ flypod claim <id> <token> # attach one anonymous deploy by its claim token
513
+ flypod logout # forget the local session
514
+ ```
515
+
516
+ `flypod login` does two things at once: it attaches every anonymous site this
517
+ machine still remembers, and it makes every *subsequent* deploy yours from the
518
+ start — no expiry, no `claim_token`, listed under `flypod list`.
519
+
520
+ ## What does flypod write to disk?
521
+
522
+ Two files, both in the CLI's own config directory — **never in your repo**:
523
+
524
+ | File | What's in it |
525
+ |------|--------------|
526
+ | `session.json` | Your session token and the host it belongs to, after `flypod login` |
527
+ | `projects.json` | The folder → site map, plus the `manage_token` for anonymous sites |
528
+
529
+ Location: `~/Library/Application Support/flypod` (macOS),
530
+ `$XDG_CONFIG_HOME/flypod` or `~/.config/flypod` (Linux), `%APPDATA%\flypod`
531
+ (Windows). Override with `FLYPOD_CONFIG_DIR`. Both are written atomically with
532
+ mode `0600`. The project registry is self-cleaning: entries for expired sites
533
+ are pruned on every load, and it's capped at the 64 most recently used.
534
+
535
+ `flypod install skill` is the exception — that command writes agent
536
+ instruction files into the repo, by design, and tells you every path it touched.
537
+
538
+ ## Library API
215
539
 
216
540
  ```ts
217
- import { deploySite, collectDist } from "flypod";
541
+ import { collectDist, deploySite, resolveDeployDir } from "flypod";
218
542
 
219
- // collect a local directory
543
+ // read a directory (or a single file) into a files map
220
544
  const files = await collectDist("./dist");
221
545
 
222
- // or build the files map yourself
546
+ // or build the map yourself
223
547
  const files = {
224
548
  "index.html": new TextEncoder().encode("<h1>hello</h1>"),
225
549
  };
226
550
 
227
551
  const result = await deploySite({ files });
228
-
229
- console.log(result.url); // https://ab12cd34.flypod.dev
230
- console.log(result.manage_token); // one-time — save to redeploy / rollback / delete
552
+ console.log(result.url);
231
553
  ```
232
554
 
233
555
  ### `deploySite(opts)`
234
556
 
235
557
  | Option | Type | Default | Description |
236
558
  |--------|------|---------|-------------|
237
- | `files` | `Record<string, Uint8Array>` | — | File path → bytes map |
238
- | `baseUrl` | `string` | `https://flypod.dev` | Override the deploy server |
559
+ | `files` | `Record<string, Uint8Array>` | — | File path → bytes |
560
+ | `baseUrl` | `string` | `https://flypod.dev` | The deploy server |
561
+ | `apiKey` | `string` | — | Sent as `Authorization: Bearer …`, so the deploy is attributed |
562
+ | `source` | `"cli" \| "skill" \| "library"` | `"library"` | Reported as `x-flypod-source` |
239
563
  | `handle` | `(req) => Promise<Response>` | `fetch` | Injectable transport (used in tests) |
240
564
 
565
+ Called directly, `deploySite` never reads a saved session or ambient env vars —
566
+ pass `apiKey` explicitly if you want an attributed deploy.
567
+
241
568
  Returns a `DeployResult`:
242
569
 
243
570
  ```ts
@@ -246,29 +573,45 @@ interface DeployResult {
246
573
  slug: string;
247
574
  url: string; // live URL
248
575
  version_id: string;
249
- expires_at: number | null; // unix ms when anonymous, null when owned (authenticated)
250
- claim_token?: string; // per-site claim token when anonymous; omitted when owned
251
- manage_token: string; // one-time; redeploy, rollback, delete
252
- owner_account_id?: string; // present on authenticated deploys (cookie or session token)
576
+ expires_at: number | null; // unix ms when anonymous, null when owned
577
+ claim_token?: string; // anonymous only — attaches the site to an account
578
+ manage_token: string; // redeploy / rollback / claim
579
+ owner_account_id?: string; // present on authenticated deploys
580
+ healed?: string[]; // problems the deploy pipeline fixed for you
581
+ warnings?: Array<{ code: string; fix_recipe: string }>;
253
582
  next_actions: unknown[];
254
583
  }
255
584
  ```
256
585
 
257
- ### `collectDist(dir)`
586
+ The `manage_token` authorizes redeploy, rollback, and claim — deleting a site is
587
+ account-only, so it can't do that. The CLI stashes it in `projects.json` and you
588
+ rarely need to handle it yourself, but **the library has no registry**: called
589
+ directly, `deploySite` hands you the only copy, so if you want to reach that
590
+ site again, you have to keep it. Treat it and `claim_token` as secrets.
258
591
 
259
- Reads a local directory into a `Record<string, Uint8Array>` map for `deploySite`.
592
+ ### `collectDist(path)`
260
593
 
261
- ---
594
+ Reads a directory recursively — or a single file — into a
595
+ `Record<string, Uint8Array>` for `deploySite`.
596
+
597
+ ### `resolveDeployDir({ cwd?, explicit? })`
262
598
 
263
- ## Managing a site (HTTP)
599
+ Returns the directory to deploy: `explicit` if given, otherwise the first build
600
+ folder found under `cwd` that contains an `index.html`. Throws if none match.
264
601
 
265
- The CLI commands above (`update`, `versions`, `rollback`) wrap these endpoints —
266
- reach for raw HTTP only when scripting against the API directly. All management
267
- calls authorize with the `manage_token` returned on first deploy (or an account
268
- account session for owned sites).
602
+ ## HTTP API
603
+
604
+ The CLI wraps these. Reach for raw HTTP only when scripting against the API
605
+ directly. Management calls authorize with the site's `manage_token`, or with an
606
+ account session for owned sites.
269
607
 
270
608
  ```sh
271
- # redeploy a new version
609
+ # create a site (anonymous — no credentials required)
610
+ curl -X POST https://flypod.dev/sites \
611
+ -H "content-type: application/zip" \
612
+ --data-binary @site.zip
613
+
614
+ # ship a new version of an existing site
272
615
  curl -X POST https://flypod.dev/sites/<id>/deploys \
273
616
  -H "authorization: Bearer <manage_token>" \
274
617
  -H "content-type: application/zip" \
@@ -278,7 +621,7 @@ curl -X POST https://flypod.dev/sites/<id>/deploys \
278
621
  curl https://flypod.dev/sites/<id> \
279
622
  -H "authorization: Bearer <manage_token>"
280
623
 
281
- # rollback to a previous version
624
+ # roll back to a previous version
282
625
  curl -X POST https://flypod.dev/sites/<id>/rollback \
283
626
  -H "authorization: Bearer <manage_token>" \
284
627
  -H "content-type: application/json" \
@@ -287,34 +630,10 @@ curl -X POST https://flypod.dev/sites/<id>/rollback \
287
630
 
288
631
  ---
289
632
 
290
- ## Accounts and bulk claim (v0.2)
291
-
292
- The `manage_token` keeps working exactly as v0.1 — accounts are an
293
- upgrade path, not a replacement.
294
-
295
- ```sh
296
- flypod login # approve this CLI in your browser
297
- flypod list # your sites (JSON)
298
- flypod claim <id> <token> # attach an anonymous deploy by its claim token
299
- flypod logout # forget the local session
300
- ```
301
-
302
- After running `flypod login` once, every subsequent `flypod` deploy is
303
- attributed to your account: no expiry, no claim_token, listed under
304
- `flypod list`. The same applies in the browser: sign in at
305
- `flypod.dev/account` and every site you've deployed from that browser
306
- gets absorbed in one bulk-UPDATE.
307
-
308
- For a stateless agent or CI job, set `FLYPOD_TOKEN` to a Better Auth session
309
- token. The CLI sends it as `Authorization: Bearer <token>`. The legacy
310
- `FLYPOD_API_KEY` variable is still accepted for compatibility, but new setups
311
- should use `FLYPOD_TOKEN`.
312
-
313
- Login on the web uses **magic link** or **email + password** — pick the one you
314
- prefer; both land you in the same account.
315
-
316
- ---
317
-
318
- ## License
633
+ Docs: [flypod.dev](https://flypod.dev) · [docs.flypod.dev](https://docs.flypod.dev) ·
634
+ [limits](https://flypod.dev/limits) · [report abuse](https://flypod.dev/abuse)
319
635
 
320
- MIT
636
+ flypod is a hosted service. This package is published so it can be installed and
637
+ run — see [`LICENSE`](./LICENSE) for the terms. The agent-skill files it writes
638
+ are MIT-licensed separately, at
639
+ [flypod-dev/flypod-skill](https://github.com/flypod-dev/flypod-skill).