CLI reference

The pylon binary covers every operator task: the dev loop, deploys, secrets, logs, db, data, domains, deployments, members, and project health. Anything you do from the Stack0 Cloud dashboard, you can do from the CLI and pipe to other shell tools.

pylon --help        # full command list
pylon <cmd> --help  # per-command flags

curl -fsSL https://www.pylonsync.com/install.sh | bash

pylon login        # device-authorization flow: prints a login code, opens
                   # www.pylonsync.com/cli, and polls until you type + approve
                   # that code in the browser. No token paste.

pylon login --token <token>        # non-interactive: pass a token directly
pylon login --token-stdin          # read the token from stdin (CI / pipes)
                                   # (PYLON_CLI_TOKEN=… also works)

pylon login --code XXXX-XXXX
                   # agent-handoff path: redeems a one-time code minted by
                   # the dashboard's "Hand off to your coding agent" card.
                   # See /operations/agent-handoff.

pylon logout       # delete ~/.config/pylon/credentials.json

PYLON_CLOUD_URL overrides the default https://www.pylonsync.com for staging or self-hosted Stack0 Cloud installs.

Project context

Most commands target a single project. Resolution order (first match wins):

--project <slug> flag on the command
PYLON_PROJECT env var
.pylon/project file in cwd or any ancestor (written by pylon projects use)
Interactive picker (TTY only)

pylon projects list                # all projects you can see
pylon projects create my-app       # create + provision a project, set it as context
pylon projects use my-app          # writes .pylon/project + adds to .gitignore
pylon projects current             # what's the current context?
pylon projects use ""              # clear the context

Create

pylon projects create <slug> provisions a project on Stack0 Cloud without the dashboard. It creates the project in your org, waits for the machine to start (usually under a minute; --db postgres adds a managed-database provision first), pins the slug as your local context, and prints the live https://<slug>.stack0.app URL.

pylon projects create my-app                       # SQLite, region iad, waits until live
pylon projects create my-app --name "My App"       # display name (defaults to the slug)
pylon projects create my-app --org acme            # required only if you're in multiple orgs
pylon projects create my-app --db postgres         # managed Postgres instead of SQLite
pylon projects create my-app --region ord          # Fly region
pylon projects create my-app --no-wait             # return immediately; check with `pylon status`

With --json the final line is a single machine-readable object ({"ok":true,"slug":"my-app","status":"running","url":"https://my-app.stack0.app",...}), so agents and scripts can chain directly into pylon deploy.

Test

pylon test                         # run *.test.ts / *.test.tsx under tests/ (or functions/)
pylon test credits                 # only files whose path contains "credits"
pylon test --json                  # machine-readable summary
pylon test:security                # adversarial auth/policy probe vs a running app
pylon test:security --target https://api.example.com --json

pylon test runs each test file with Bun against an in-memory Pylon. It exits non-zero on failure, so it fits into CI. pylon test:security is a separate probe that calls a running app and reports auth/policy holes. See the Testing guide for the unit, component, and HTTP patterns.

Audit

pylon audit checks a running app for search and page-quality problems. Run it before you finish a public site.

pylon audit                          # the local app: http://localhost:<PYLON_PORT or 4321>
pylon audit https://rosas.example    # a deployed site
pylon audit --max-pages 10           # audit fewer pages (default: 50)
pylon audit --lighthouse-pages 5     # run Lighthouse on more pages (default: 3)
pylon audit --no-lighthouse          # HTML checks only
pylon audit --json                   # machine-readable report

The audit gets the page list from the sitemap (the robots.txt Sitemap lines, else /sitemap.xml). Without a sitemap, it uses the static routes in pylon.manifest.json. Without those, it uses the links on the home page. It checks each page for these problems:

An HTTP status of 400 or more.
A missing, duplicate, too short, or too long <title>.
A missing, duplicate, too short, or too long meta description.
No <h1>, or more than one.
A missing, relative, or duplicate canonical link.
No lang on <html>, and no viewport meta tag.
No og:title, og:description, or og:image. The og:image URL must return 200 with an image content type.
Images without an alt attribute.
JSON-LD that does not parse. The home page must have JSON-LD with an Organization or LocalBusiness (or a subtype such as Restaurant).
Internal links that return 404 or another error.
noindex on a page that the sitemap lists.

It also checks robots.txt (present, not blocking the site, has a Sitemap line), the sitemap XML, and pages that the app links to but the sitemap leaves out. When Chrome or Chromium and Node.js 22.19 or newer are present, the audit runs Lighthouse 13.5.0 for performance and accessibility, through bun x. It finds Chrome from CHROME_PATH, then chromium or google-chrome on PATH. Without Chrome or Node.js, the report says so and the other checks still run. pylon dev adds dev-only scripts to each page. For performance numbers that match production, audit pylon start or the deployed URL. Each problem has a one-line fix. The exit code is 1 when there are errors and 0 when there are only warnings. It is 69 when nothing answers at the URL.

Deploy

pylon deploy                       # default → Stack0 Cloud (packages local
                                   # source, uploads via the cli-tokens flow)

pylon deploy --target docker       # generate Dockerfile to ./deploy/
pylon deploy --target fly          #            Dockerfile + fly.toml
pylon deploy --target compose      #            docker-compose.yml + Dockerfile
pylon deploy --target workers      #            wrangler.toml (experimental)
pylon deploy --target systemd      #            systemd unit file
pylon deploy --target manifest     #            just manifest + client bindings

pylon deploy (no flag) runs the hosted deploy. The other targets write IaaS config files to ./deploy/.

What the hosted deploy uploads

pylon deploy uploads the project directory, at most 50 MB, minus:

whatever .gitignore and .pylonignore files in the project ignore. Both use gitignore syntax, including nested files, **, and ! negation. Put paths you commit but do not ship (videos, design files, agent worktrees) in .pylonignore. Rules above the project directory and your global git excludes do not apply.
always, whatever the ignore files say: .git, node_modules, .pylon, build output next to its manifest (target beside Cargo.toml; dist, build, .next, .turbo, .vercel, .cache beside package.json), .env and every .env.* except *.example, and .DS_Store / Thumbs.db.

pylon.manifest.json and the app’s shard modules ship even when ignored.

# .pylonignore
video/
.claude/worktrees/
design/**/*.psd

Secrets

pylon secrets list                 # keys + last-rotated dates (values never leave the cloud)
pylon secrets set STRIPE_KEY=sk_…  # one-liner
pylon secrets set OPENAI_KEY       # prompt for value on stdin
pylon secrets rm STRIPE_KEY
pylon secrets import .env          # bulk import from a dotenv file
pylon secrets import .env --replace  # allow overwriting existing keys

Every write fires syncSecretsToFly immediately so the running machine sees the new value within ~10s (no redeploy required).

Logs

pylon logs tail                    # 2s-polling tail of the project's request log,
                                   # Ctrl-C to stop. Pipe to grep/jq for filtering.

pylon logs tail --json | jq 'select(.status >= 500)'
                                   # all 5xx in real time

Auto-recovers on kind: unavailable (machine stopped, framework predates the tail endpoint, etc.) — backs off to 30s until the surface comes back.

Database

pylon db list                      # snapshot history
pylon db backup                    # take a fresh snapshot
pylon db restore <backup-id>       # restore from one

Watch the project’s Deployments tab for restore progress; restoring rolls the Fly machine.

Copy a SQLite app to Postgres

pylon db copy copies all of a SQLite app’s data into an empty Postgres database. It runs on the files, so it needs no login.

pylon db copy --from /data/pylon.db --to postgres://… --check   # report values Postgres refuses; write nothing
pylon db copy --from /data/pylon.db --to postgres://…           # copy

The copy includes:

the entity rows, with encrypted fields as they are stored
the auth state, jobs, workflow runs, CRDT documents and the change log
the search index, which it fills on Postgres

--to defaults to DATABASE_URL. --manifest defaults to pylon.manifest.json. The copy refuses a database that already has rows. It reads the SQLite files and does not change them. To copy when the server starts, set PYLON_IMPORT_FROM_SQLITE=/data/pylon.db together with a Postgres DATABASE_URL. The server copies the data before it accepts requests. If the copy fails, the server does not start, and it writes the error to _pylon_sqlite_import_failures. Later starts find the finished copy and skip it.

Data browser

pylon data entities                # every entity in the deployed schema
pylon data list Order              # first 50 rows
pylon data get Order ord_9f2a      # single row, pretty-printed JSON

Owner / admin only (same gate the dashboard data browser uses).

Domains

pylon domains list                 # custom hostnames + provisioning status
pylon domains add api.example.com  # adds row; prints the CNAME target
pylon domains verify api.example.com   # checks DNS + cert provisioning
pylon domains rm api.example.com

The default pylon-<slug>.fly.dev hostname is always available regardless.

Deployments

pylon deployments list             # 20 most recent
pylon deployments rollback <id>    # promote a previous deployment back to current

Members

pylon members list                                       # everyone in the project's org
pylon members invite [email protected] admin          # invite with role
pylon members invite [email protected]                # defaults to member

Roles: owner, admin, member.

Status

pylon status                       # uptime, requests, error rate, jobs, WS/SSE clients
pylon status --json                # structured output for monitoring scripts

One-glance project health — same surface the dashboard’s project overview shows.

Jobs

pylon jobs                         # 50 most recent jobs: name, status, tries, start, first error line
pylon jobs failed                  # only failed jobs
pylon jobs dead                    # the dead-letter queue
pylon jobs stats                   # pending / running / completed / failed / dead counts
pylon jobs get <id>                # one job with the full error text
pylon jobs --status retrying --queue mail --limit 200

Reads /admin/jobs on the project’s machine through Stack0 Cloud. Owner / admin only. A cron that stopped writing shows up here as a failed row with its function name and error.

JSON mode

Every command accepts --json and emits parseable output for scripts:

pylon projects list --json | jq -r '.projects[].slug'

# fail CI on any project not in 'running' status
pylon status --json | jq -e '.status == "running"'

# nightly backup of every project you can see
pylon projects list --json | jq -r '.projects[].slug' | \
  xargs -I{} pylon db backup --project {}

Env vars

Variable	Effect
`PYLON_CLOUD_URL`	Override the cloud origin (staging / self-hosted)
`PYLON_PROJECT`	Default project slug (overridden by `--project`)
`XDG_CONFIG_HOME`	Where `pylon login` stashes credentials (defaults to `~/.config`)

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

CLI reference

Project context

Create

Test

Audit

Deploy

What the hosted deploy uploads

Secrets

Logs

Database

Copy a SQLite app to Postgres

Data browser

Domains

Deployments

Members

Status

Jobs

JSON mode

Env vars

​Install + sign in

​Project context

​Create

​Test

​Audit

​Deploy

​What the hosted deploy uploads

​Secrets

​Logs

​Database

​Copy a SQLite app to Postgres

​Data browser

​Domains

​Deployments

​Members

​Status

​Jobs

​JSON mode

​Env vars

Install + sign in

Project context

Create

Test

Audit

Deploy

What the hosted deploy uploads

Secrets

Logs

Database

Copy a SQLite app to Postgres

Data browser

Domains

Deployments

Members

Status

Jobs

JSON mode

Env vars