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