CLI

runlot — a CLI for deploying apps and managing PostgreSQL. Describes every command and option. Command syntax and options are taken from runlot --help.

The source of truth for this page is CLI help in web/apps/cli/src/index.ts. The docs build generates this content from that source.

Installation

npm i -g runlot
runlot login

runlot --help prints every command, and runlot <command> --help prints only that command group.

  runlot login                     log in via browser (GitHub, and so on)
  runlot login <name>              log in for local development (dev server only)
  runlot whoami                    show the current user

Running runlot login authenticates your account in the browser. Credentials are stored in ~/.runlot/credentials.json, keyed by control plane address.

Common options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)

The --org and --project options take precedence over the settings in runlot.json. For --api, specify the address of the control plane to connect to.

org — organization management

  runlot org create <slug> [name]  create an org (uses slug if name is omitted)
  runlot org list                  list orgs you belong to
  runlot org rename <new-name>     rename the display name (admin, address unchanged)
  runlot org delete                delete the org (admin, retype slug, --confirm)
  runlot org members               list org members (requires --org)
  runlot org add-member <p>:<s>    add an existing user to an org (requires --role, --org)
  runlot org set-role <uid> <role> change a member's role (requires --org)
  runlot org remove-member <uid>   remove a member from an org (requires --org)

  You cannot change the org slug — deployment addresses, certificates, git remotes, and runlot.json use that value.
  `org delete` requires typing the slug directly. You cannot skip this with -y; scripts use --confirm.

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --role <r>       admin | member | viewer (member invite·org add-member)
  --confirm <value>  Replaces retyping the slug for org delete or the project name for project delete
                   (used when not a terminal; not available with -y)

project — project management

  runlot project create <name>     create a project (requires --org)
  runlot project list              list projects (requires --org)
  runlot project delete <name>     delete the whole project (admin, retype name, --confirm)

  `project delete` permanently deletes deployments, the database, backup generations, objects, email, storage, and secrets.
  This does not leave a recovery backup, so export first with `runlot pg export` if you need one.
  Give the target as an argument (runlot.json is not used). You must type the name directly, and
  You cannot skip this with -y — scripts use --confirm <name>. `rm` is the same command.

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --confirm <value>  Replaces retyping the slug for org delete or the project name for project delete
                   (used when not a terminal; not available with -y)

deploy — deployment

  runlot deploy [dir]              builds a bundle and deploys it

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)

pg — database

  runlot pg connect [dir]          show connection info (includes password)
  runlot pg execute [dir]          run SQL (-c <sql> or -f <file>)
  runlot pg migrate [dir]          apply migrations/NNNN_*.sql
  runlot pg shell [dir] [-- ...]   connect via psql (args after -- pass through to psql)
  runlot pg export [dir]           create a diagnostic dump (not a backup)

  runlot pg generations [dir]      list backups (--json for raw output)
  runlot pg restore <e>/<s> [dir]  restore to that backup (latest works, admin)
  runlot pg delete [dir]           delete the database (admin)
  runlot pg abort <opId> [dir]     abort a running operation (admin)

  runlot pg token [dir]            issue a time-limited connection token (--ttl, --json)
  runlot pg token list [dir]       list issued connection tokens
  runlot pg token revoke <user>    revoke a connection token

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -c, --command    SQL to run (pg execute)
  -f, --file       SQL file to run (pg execute)
  --migrations <d> migrations directory (default <dir>/migrations)
  --ca-dir <path>  local CA directory (verifies TLS with verify-full if set)
                   (default $RUNLOT_CA_DIR)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --ttl <duration>  validity period for the pg token (default 1h, e.g. 30m, 12h, 7d)

storage — file storage

  runlot storage [status] [dir]    show storage capacity and usage limit (--json for raw output)
  runlot storage delete [dir]      release storage (admin)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,

auth — application user authentication

  runlot auth [status] [dir]       config, providers, callback URL (--json for raw output)
  runlot auth provider set <p>     registers a social login provider (--client-id, --client-secret, admin)
  runlot auth provider rm <p>      deletes a social login provider config (admin)
  runlot auth set <key> <value>    allow-signup, require-verified on|off, session-days <n>,
                                   brand-name·brand-color·brand-logo <value>
  runlot auth delete [dir]         disables the auth feature (the users table stays in the DB, admin)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --client-id <id> provider's public id for auth provider set
  --client-secret <value> client secret for auth provider set (prompts if omitted)
  --json           prints the raw server response JSON (all list commands, usage,

access — deployment access control

  runlot access [dir]              who can view this deployment (--json)
  runlot access set <mode> [dir]   public | org | password (--password, admin)
  runlot access bypass --new|--revoke  bypass secret for CI (Runlot-Access-Bypass header, admin)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --json           prints the raw server response JSON (all list commands, usage,

secret — secrets

  runlot secret set <NAME> [value]  save a secret (reads from stdin if value is omitted)
  runlot secret list [dir]         list secret names and versions (does not show values)
  runlot secret delete <NAME> [d]  delete a secret

  `secret set` does not take a directory argument (the second argument is the value).
  For a project in another directory, specify --org/--project.

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)

domain — custom domains

  runlot domain add <host> [dir]   connects a custom domain (shows CNAME, TXT instructions)
  runlot domain list [dir]         connected domains and their status
  runlot domain verify <h> [dir]   checks the DNS setup (auto-check runs every minute)
  runlot domain rm <host> [dir]    disconnects a domain

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)

dns — DNS zones

  runlot dns zones                 lists DNS zones managed by runlot (requires --org)
  runlot dns create <zone>         creates a zone (requires --org)
  runlot dns records <zone>        lists a zone's records
  runlot dns set <z> <n> <t> <value…> creates or updates a record (--ttl, give the full value)
  runlot dns rm <zone> <n> <t>     deletes a record
  runlot dns delete <zone>         deletes a zone

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --ttl <duration>  validity period for the pg token (default 1h, e.g. 30m, 12h, 7d)

domains — domain purchase and renewal

  runlot domains check <name...>    checks availability and price (requires --org)
  runlot domains buy <name>        buys a domain (--years, --contact-json, -y)
  runlot domains list              lists domains you own
  runlot domains show <name>       domain details and recent operation history
  runlot domains import <name>     adds a domain you already own to the managed list
  runlot domains renew <name>      renews it (--years)
  runlot domains lock|unlock <name> turns transfer lock on or off
  runlot domains auth-code <name>  get the code to transfer to another registrar

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --years <n>      registration or renewal period in years for domains buy, renew (1-10, default 1)
  --contact-json <f> registrant contact JSON file for domains buy (prompts if omitted)

logs — logs

  runlot logs [dir]                stream worker logs live (Ctrl-C to stop)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --tail <n>       lines logs fetches at first (default 200, max 2000)
  --no-follow      prints recent logs only and exits (default streams live)

usage — usage

  runlot usage [dir]               show usage by hour (--json for raw output)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --hours <n>      time range for usage to show (default 24, max 720)

port-forward — local port forwarding

  runlot port-forward [dir]        authenticate via the login session and forward a local port to the database
                                   (--port 15432, --listen 127.0.0.1, press Ctrl-C to stop)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --ca-dir <path>  local CA directory (verifies TLS with verify-full if set)
                   (default $RUNLOT_CA_DIR)
  --port <n>       local port for port-forward to open (default 15432)
  --listen <addr>  local address for port-forward to accept connections (default 127.0.0.1)

rollback — restore a previous version

  runlot rollback <version> [dir]  roll back to a previous version

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)

versions — deployment history

  runlot versions [dir]            show deployment history

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)

member

  runlot member [ls]               list org members (requires --org, --json)
  runlot member invite <email>     invite by email (--role, default member, admin)
  runlot member role <member> <role> change a member's role (admin)
  runlot member rm <member>        remove a member from the org (admin)
  runlot member leave              leave this org
  runlot member invites            list pending and expired invites (admin, --json)
  runlot member uninvite <email>   revoke the invite for that address (admin)

  <member> is a uuid, email, or login name. If it matches more than one, the command is rejected.

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,
                   pg generations·pg token)
  --role <r>       admin | member | viewer (member invite·org add-member)

email

  runlot email [status] [dir]      mail address and sent/received counts (--json for raw output)
  runlot email log [dir]           sent and received mail (--direction in|out, --cursor, --limit, --json)
  runlot email raw <mailId> [dir]  print the raw message (.eml) to stdout
  runlot email delete [dir]        turns off email (admin)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,

ai

  runlot ai models                 model catalogue and per-1M-token prices (--json for raw output)
  runlot ai [usage] [dir]          calls, tokens, spend, and limits (--json for raw output)
  runlot ai credit [dir]           org credit balance and automatic top-up (--org)
  runlot ai delete [dir]           disables AI (admin). Enable it with runlot.json
                                   "ai": true + runlot deploy
                                   (there is no model-call command: env.ai is worker-only)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)
  -y, --yes        skips the confirmation prompt (rollback, secret delete, domain rm,
                   dns rm·dns delete·pg restore·pg delete·domains buy·storage delete·
                   email delete·ai delete·auth delete·auth provider rm·member rm·
                   member leave·member uninvite)
  --json           prints the raw server response JSON (all list commands, usage,

repo

  runlot repo create <name> [dir]  create a repository in this project and set origin (--public)
  runlot repo [list]               list repositories in this project (--json)
  runlot repo rename <old> <new>   rename a repository (admin)
  runlot repo visibility <n> <v>   public | private (admin)
  runlot repo delete <name>        delete a repository (admin)
  runlot repo history <name>       push history (who moved which ref, and how)

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --project <name> project (overrides "name" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)

key

  runlot key add [path]            add an SSH public key (uses the default key if omitted)
  runlot key [list]                list registered public keys
  runlot key rm <keyId>            remove a public key

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)

token

  runlot token create <name>       issue a token for git over HTTPS (--read-only, --ttl)
  runlot token [list]              list issued tokens
  runlot token revoke <tokenId>    revoke a token

Options

  --org <slug>     org (overrides "org" in runlot.json)
  --api <url>      API server address (default https://dash.runlot.io, local uses RUNLOT_API_URL)

On this page