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 +425 -187
- package/dist/bin/deploy.js +499 -1038
- package/dist/cli-g2wb2hxm.js +1435 -0
- package/dist/src/cli/client.d.ts +99 -0
- package/dist/src/cli/commands.d.ts +68 -0
- package/dist/src/cli/paths.d.ts +17 -0
- package/dist/src/cli/projects.d.ts +35 -0
- package/dist/src/cli/session.d.ts +11 -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 +72 -0
- package/dist/src/cli.js +1 -1
- package/dist/src/deploy-source.d.ts +20 -0
- package/package.json +14 -16
- package/dist/cli-ynzcc4xy.js +0 -709
package/README.md
CHANGED
|
@@ -1,243 +1,495 @@
|
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
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.
|
|
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 ·
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
38
|
+
**Temporary, then yours.** There are only two states, and one command between
|
|
39
|
+
them:
|
|
54
40
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
-
|
|
80
|
-
|
|
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
|
-
|
|
73
|
+
---
|
|
83
74
|
|
|
84
|
-
|
|
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
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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)
|
|
180
|
+
npm install -g flypod # or: bun add --global flypod
|
|
181
|
+
flypod ./dist
|
|
131
182
|
```
|
|
132
183
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
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
|
-
|
|
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>]
|
|
212
|
+
flypod forget [--site <id>] # drop the folder → site memory
|
|
147
213
|
```
|
|
148
214
|
|
|
149
|
-
**
|
|
150
|
-
Anonymous sites use a per-site
|
|
151
|
-
registry for you — pass `--token <manage_token>` to
|
|
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
|
-
|
|
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
|
-
|
|
249
|
+
`--json` still includes `manage_token` for programmatic use, and
|
|
250
|
+
`FLYPOD_SHOW_TOKEN=1` restores the old inline output.
|
|
159
251
|
|
|
160
|
-
|
|
161
|
-
|
|
252
|
+
## How do I roll back?
|
|
253
|
+
|
|
254
|
+
`flypod rollback` makes the previous version live again, immediately.
|
|
162
255
|
|
|
163
256
|
```sh
|
|
164
|
-
|
|
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
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
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
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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
|
-
|
|
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
|
|
187
|
-
|
|
188
|
-
|
|
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
|
-
|
|
191
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
##
|
|
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,
|
|
466
|
+
import { collectDist, deploySite, resolveDeployDir } from "flypod";
|
|
218
467
|
|
|
219
|
-
//
|
|
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
|
|
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
|
|
238
|
-
| `baseUrl` | `string` | `https://flypod.dev` |
|
|
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
|
|
250
|
-
claim_token?: string; //
|
|
251
|
-
manage_token: string; //
|
|
252
|
-
owner_account_id?: string; // present on authenticated deploys
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
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
|
-
#
|
|
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
|
-
#
|
|
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
|
-
|
|
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.
|