CLI reference

The pylon binary covers the full operator surface: dev loop, deploys, secrets, logs, db, data, domains, deployments, members, project health. Anything you can do from the Pylon 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 Pylon 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 Pylon Cloud without touching the dashboard: it creates the project in your org, waits for the machine to come up (usually well under a minute; --db postgres adds a managed-database provision first), pins the slug as your local context, and prints the live https://<slug>.pyln.dev 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.pyln.dev",...}), so agents and scripts can chain straight 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 (drops straight into CI). pylon test:security is a separate probe that hits a running app and reports auth/policy holes. See the Testing guide for the unit / component / HTTP patterns.

Deploy

pylon deploy                       # default → Pylon 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) does the actual hosted deploy. The other targets write IaaS config files to ./deploy/.

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.

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.

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

CLI reference

Project context

Create

Test

Deploy

Secrets

Logs

Database

Data browser

Domains

Deployments

Members

Status

JSON mode

Env vars

​Install + sign in

​Project context

​Create

​Test

​Deploy

​Secrets

​Logs

​Database

​Data browser

​Domains

​Deployments

​Members

​Status

​JSON mode

​Env vars

Install + sign in

Project context

Create

Test

Deploy

Secrets

Logs

Database

Data browser

Domains

Deployments

Members

Status

JSON mode

Env vars