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/LICENSE +42 -15
- package/README.md +512 -193
- package/dist/bin/deploy.js +323 -418
- package/dist/{cli-j9rxpfdv.js → cli-db9gcrd0.js} +621 -14
- package/dist/src/cli/client.d.ts +13 -1
- package/dist/src/cli/commands.d.ts +76 -0
- package/dist/src/cli/projects.d.ts +35 -0
- package/dist/src/cli/receipt.d.ts +155 -0
- package/dist/src/cli/skill.d.ts +135 -0
- package/dist/src/cli/source.d.ts +7 -0
- package/dist/src/cli.d.ts +18 -0
- package/dist/src/cli.js +4 -4
- package/dist/src/deploy-source.d.ts +28 -0
- package/package.json +6 -10
package/README.md
CHANGED
|
@@ -1,243 +1,570 @@
|
|
|
1
1
|
# flypod
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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.
|
|
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 ·
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
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
|
-
|
|
56
|
-
|
|
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
|
-
|
|
61
|
-
#
|
|
62
|
-
#
|
|
63
|
-
|
|
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
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
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
|
-
|
|
104
|
-
flypod
|
|
81
|
+
npx flypod install skill
|
|
105
82
|
```
|
|
106
83
|
|
|
107
|
-
|
|
84
|
+
It writes into the two directories every major agent reads:
|
|
108
85
|
|
|
109
|
-
|
|
|
110
|
-
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
127
|
-
flypod
|
|
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
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
-
|
|
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>]
|
|
235
|
+
flypod forget [--site <id>] # drop the folder → site memory
|
|
147
236
|
```
|
|
148
237
|
|
|
149
|
-
**
|
|
150
|
-
Anonymous sites use a per-site
|
|
151
|
-
registry for you — pass `--token <manage_token>` to
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
161
|
-
|
|
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
|
-
|
|
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
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
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
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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
|
-
|
|
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
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
|
|
191
|
-
|
|
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
|
|
195
|
-
|
|
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
|
-
|
|
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,
|
|
541
|
+
import { collectDist, deploySite, resolveDeployDir } from "flypod";
|
|
218
542
|
|
|
219
|
-
//
|
|
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
|
|
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
|
|
238
|
-
| `baseUrl` | `string` | `https://flypod.dev` |
|
|
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
|
|
250
|
-
claim_token?: string; //
|
|
251
|
-
manage_token: string; //
|
|
252
|
-
owner_account_id?: string; // present on authenticated deploys
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
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
|
-
#
|
|
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
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
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).
|