CLI reference

flypod is a zero-auth static-site deploy primitive. One command ships a directory or single file to a public URL. Logged in, deploys are permanent and owned; anonymous, they live 14 days.

InstallCopy Anchor Link

npx flypod

Or install globally:

npm i -g flypod

The binary is flypod. The first positional argument that names a subcommand is dispatched (a flag's value never counts, so flypod --site list update is update for the site list); otherwise the argument is treated as a deploy path. flypod deploy [path] is the same as flypod [path]. A bare word that is not a path but is close to a verb (flypod verisons) fails with unknown_command and names the verb you probably meant, rather than deploying a folder that does not exist.

An unknown flag is refused on every command, top-level or subcommand, with the code unknown_flag and exit 2 — nothing is silently ignored. A flag that takes a value and is given none fails with usage. --help never runs the command it is attached to: it prints help on stdout and exits 0 (under --json, as {"ok":true,"help":"…"}). Success exits 0; see Errors and exit codes for the rest.

CommandsCopy Anchor Link

Global flagsCopy Anchor Link

Errors and exit codesCopy Anchor Link

Every command fails the same way. In a terminal the reason is on a line starting with ✗, with the next step underneath it. With --json the failure is one line of JSON on stdout and nothing on stderr:

{ "ok": false, "code": "rate_limited", "error": "Too many requests from this network right now.", "fix": "Wait a minute and retry the same command.", "retry_after_s": 30 }

Branch on code: it is stable. error is prose and may change. fix, when present, is the literal next step. A failure that came from the server also carries its HTTP status.

The exit code follows code, never the command:

Environment variablesCopy Anchor Link

The CLI counts deploys per install with a random id, says in one fixed word which coding agent ran it (claude_code, codex, cursor, gemini, opencode, other or none, read from variables those agents set: AI_AGENT, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CURSOR_AGENT, GEMINI_CLI, CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_THREAD_ID, CODEX_MANAGED_BY_NPM; never the variables' values) and whether CI did (CI, GITHUB_ACTIONS), how it was launched (npx, bunx, pnpm_dlx, yarn_dlx, script, local, global or other, from the shape of its own script path and the package manager's npm_lifecycle_event, npm_command, npm_config_user_agent, npm_execpath), and whether the project's agent instructions name flypod (skill, agents_md, claude_md, cursor_rules, copilot, gemini_md or none: which kind of file, among AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/*, .github/copilot-instructions.md and GEMINI.md in the project up to its repository root, has the word flypod in its first 32 KB), and when a command fails against flypod.dev it reports the error code and, for too_large, no_files and no_build_dir, the upload's shape (file count, kilobytes per kind of file, whether the folder has a package.json or a build folder); for no_site, which kind; for unauthorized, which kind of credential was refused, whether this machine knew the site, and whether it was named by the folder's link or --site. Never file names, paths or contents. Reports never print and give up after 1.5 s. The library (deploySite()) sends none of it.

Configuration filesCopy Anchor Link

flypod stores config in a per-user directory, never in your project repo. Override the location with FLYPOD_CONFIG_DIR.

These files are written with mode 0600:

• session.json: the account session created by flypod login.
• projects.json: the folder-to-site registry. LRU-capped at 64 entries; expired entries auto-prune.
• pending-login.json: only while a flypod login --json waits for its person. A device code, not a credential, so the next command can finish the sign-in; worthless after ten minutes.
• install.json: the random install id described above. Not written when DO_NOT_TRACK is set.

AuthenticationCopy Anchor Link

Connect the CLI through browser device authorization:

flypod login

For a stateless agent or CI job, provide an existing account session token:

FLYPOD_TOKEN=<session_token> npx flypod ./dist

FLYPOD_TOKEN takes precedence over a saved login. With neither, the deploy is anonymous. A credential that is sent and not accepted fails with token_rejected; it never silently becomes an anonymous deploy. See Account commands.