Command reference

Sign in through the browser, or with --token for CI

Usage: pyo login [OPTIONS]

Options:
      --expires <EXPIRES>  When the new API key expires [default: 1y] [possible values: 30d, 90d, 1y, never]
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

Forget this computer's sign-in

Usage: pyo logout [OPTIONS]

Options:
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Who you're signed in as

Usage: pyo whoami [OPTIONS]

Options:
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Whether observability (analytics, request logs, usage history) is on for this Pyo, or turn it on or off. Turning it is for the installation's admin, with a full-access key

Usage: pyo observability [OPTIONS] [STATE]

Arguments:
  [STATE]  [possible values: on, off]

Options:
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Link this folder to a service (writes pyo.toml)

Usage: pyo link [OPTIONS] [SERVICE]

Arguments:
  [SERVICE]  "api", "shop/api" or "team/shop/api". Without it, pick from a list

Options:
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Apply pyo.toml and deploy, then follow it to the end. With -f, import a Docker Compose file instead: see what it makes, then deploy it

Usage: pyo deploy [OPTIONS]

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --detach             Start it and exit, without following it
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -f, --file <FILE>        A Docker Compose file to import as a new project (a .env next to it is read too)
      --team <TEAM>        The team to import into (slug or id). Defaults to your first team
      --cluster <CLUSTER>  The cluster to run it on (name or id). Defaults to the team's default cluster
  -y, --yes                Don't ask: import the Compose file, or go ahead with a very large replica change from pyo.toml
  -h, --help               Print help
  -V, --version            Print version

The service's state, live version and domains

Usage: pyo status [OPTIONS]

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --json               The whole service, as JSON
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

The service's recent logs

Usage: pyo logs [OPTIONS]

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
  -f, --follow             Keep printing new lines
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

Environment variables

Usage: pyo env [OPTIONS] [COMMAND]

Commands:
  list   List variables (secrets stay hidden)
  set    Set KEY=value pairs
  unset  Remove variables
  push   Set the variables of a .env file
  pull   Write the variables to a .env file
  help   Print this message or the help of the given subcommand(s)

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

List variables (secrets stay hidden)

Usage: pyo env list [OPTIONS]

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Set KEY=value pairs

Usage: pyo env set [OPTIONS] <KEY=VALUE>...

Arguments:
  <KEY=VALUE>...  

Options:
      --secret             Store them as secrets: encrypted, never shown again
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --deploy             Deploy right away
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Remove variables

Usage: pyo env unset [OPTIONS] <KEY>...

Arguments:
  <KEY>...  

Options:
      --deploy             Deploy right away
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Set the variables of a .env file.

New keys are variables unless marked secret. A secret that's overwritten stays a secret. In a terminal, you're asked about keys that are already set. Elsewhere, pass --overwrite or --skip-existing.

Usage: pyo env push [OPTIONS] [FILE]

Arguments:
  [FILE]
          [default: .env]

Options:
      --overwrite
          Overwrite keys that are set already

      --url <URL>
          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to)
          
          [env: PYO_URL]

      --skip-existing
          Keep keys that are set already

      --token <TOKEN>
          An API key, for CI (default: the one `pyo login` saved)
          
          [env: PYO_TOKEN]

      --secret <KEY>
          Make this key a secret (repeatable)

      --secrets
          Make every key a secret

      --dry-run
          Show what would change, without saving

      --deploy
          Deploy right away

  -s, --service <SERVICE>
          The service: a name ("api", "shop/api") or id. Default: pyo.toml's

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Write the variables to a .env file

Usage: pyo env pull [OPTIONS] [FILE]

Arguments:
  [FILE]  [default: .env]

Options:
      --force              Overwrite the file
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Put back the previous version (or a deployment by id)

Usage: pyo rollback [OPTIONS] [DEPLOYMENT]

Arguments:
  [DEPLOYMENT]  A deployment id. Defaults to the previous version

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

Restart the service, one replica at a time

Usage: pyo restart [OPTIONS]

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

A shell in the service

Usage: pyo exec [OPTIONS]

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --replica <REPLICA>  A replica name. Defaults to any ready replica
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
      --shell <SHELL>      bash, sh, zsh or ash. Defaults to whichever the service has
  -h, --help               Print help
  -V, --version            Print version

Open the service on the dashboard

Usage: pyo open [OPTIONS]

Options:
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

Pyo registry, for the team's own images

Usage: pyo registry [OPTIONS] <COMMAND>

Commands:
  login  Log Docker in with a new 30-day token, to push <team>/<project>/<service> images. Only works from a device on Pyo's tailnet
  help   Print this message or the help of the given subcommand(s)

Options:
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Log Docker in with a new 30-day token, to push <team>/<project>/<service> images. Only works from a device on Pyo's tailnet

Usage: pyo registry login [OPTIONS]

Options:
      --team <TEAM>    The team (slug or id). Defaults to your first team
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --pull-only      A token that can only pull
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Built-in databases

Usage: pyo db [OPTIONS] <COMMAND>

Commands:
  import  Copy a Postgres or MySQL database, or a dump file, into an empty database, and follow it. Owners and admins
  help    Print this message or the help of the given subcommand(s)

Options:
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help           Print help
  -V, --version        Print version

Copy a Postgres or MySQL database, or a dump file, into an empty database, and follow it. Owners and admins

Usage: pyo db import [OPTIONS] <DATABASE>

Arguments:
  <DATABASE>  The database to import into: its name or id

Options:
      --from <URL>     The database to copy, as a URL: postgres://user:password@host:5432/db or mysql://… (it must be reachable from the cluster). PYO_IMPORT_URL keeps the password out of your shell's history [env: PYO_IMPORT_URL]
      --url <URL>      Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
  -f, --file <FILE>    A dump instead: .sql, .sql.gz, or a Postgres .dump (pg_dump -Fc)
      --token <TOKEN>  An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
      --retry          Run the last failed import again, from the same source
      --team <TEAM>    The team (slug or id), when several have a database by that name
      --detach         Start it and exit, without following it
  -h, --help           Print help
  -V, --version        Print version

Volumes: their backups, restoring and growing them, attaching them

Usage: pyo volume [OPTIONS] <COMMAND>

Commands:
  list           Your teams' volumes
  snapshots      A volume's backups, newest first
  restore        Replace a volume's data with one of its backups. Its service is stopped while it runs and started again after
  delete-backup  Delete one of a volume's backups for good. Owners and admins
  resize         Grow a volume (it never shrinks), where its storage class can
  attach         Attach a detached volume to a service on its cluster. For a service in another project, the volume moves there first
  help           Print this message or the help of the given subcommand(s)

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

Your teams' volumes

Usage: pyo volume list [OPTIONS]

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

A volume's backups, newest first

Usage: pyo volume snapshots [OPTIONS] <VOLUME>

Arguments:
  <VOLUME>  The volume: an id, "name" or "project/name"

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

Replace a volume's data with one of its backups. Its service is stopped while it runs and started again after

Usage: pyo volume restore [OPTIONS] <VOLUME> [SNAPSHOT]

Arguments:
  <VOLUME>    
  [SNAPSHOT]  A snapshot id (see `pyo volume snapshots`). Without it, pick from a list

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
  -y, --yes                Don't ask to confirm
      --detach             Start it and exit, without following it
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

Delete one of a volume's backups for good. Owners and admins

Usage: pyo volume delete-backup [OPTIONS] <VOLUME> [SNAPSHOT]

Arguments:
  <VOLUME>    
  [SNAPSHOT]  A snapshot id (see `pyo volume snapshots`). Without it, pick from a list

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
  -y, --yes                Don't ask to confirm
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

Grow a volume (it never shrinks), where its storage class can

Usage: pyo volume resize [OPTIONS] <VOLUME> <SIZE>

Arguments:
  <VOLUME>  
  <SIZE>    The new size in GB

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

Attach a detached volume to a service on its cluster. For a service in another project, the volume moves there first

Usage: pyo volume attach [OPTIONS] <VOLUME>

Arguments:
  <VOLUME>  

Options:
      --path <PATH>        The folder in the service (default: where it was, or /data)
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --detach             Start a move and exit, without following it
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service to attach a volume to (pyo volume attach): "api", "shop/api" or an id
  -h, --help               Print help
  -V, --version            Print version

The service's domains

Usage: pyo domain [OPTIONS] <COMMAND>

Commands:
  list    The service's domains and their status
  add     Serve the service on a hostname. It applies without a redeploy
  remove  Stop serving the service on a hostname
  help    Print this message or the help of the given subcommand(s)

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

The service's domains and their status

Usage: pyo domain list [OPTIONS]

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Serve the service on a hostname. It applies without a redeploy

Usage: pyo domain add [OPTIONS] [HOSTNAME]

Arguments:
  [HOSTNAME]  e.g. app.example.com

Options:
      --free               A free nip.io domain instead (no DNS record needed)
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --port <PORT>        The HTTP port to route to, by name or number (default: the first)
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
      --wait               Wait until it's live
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Stop serving the service on a hostname

Usage: pyo domain remove [OPTIONS] <HOSTNAME>

Arguments:
  <HOSTNAME>  e.g. app.example.com

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
  -y, --yes                Don't ask to confirm
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
  -h, --help               Print help
  -V, --version            Print version

Bring services over from Coolify or Dokploy: see what they become, then import them. Owners and admins

Usage: pyo import [OPTIONS] --from <FROM> --source-token <SOURCE_TOKEN> <PLATFORM>

Arguments:
  <PLATFORM>  The platform: coolify or dokploy [possible values: coolify, dokploy]

Options:
      --from <FROM>                  Its address, e.g. https://coolify.example.com
      --url <URL>                    Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
      --source-token <SOURCE_TOKEN>  Its API token (Coolify's with read and read:sensitive). Used for this import only [env: PYO_IMPORT_TOKEN]
      --token <TOKEN>                An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
      --team <TEAM>                  The team to import into (slug or id). Defaults to your first team
      --cluster <CLUSTER>            The cluster to run it on (name or id). Defaults to the team's default cluster
      --deploy                       Deploy the services once they're made
  -y, --yes                          Import without asking
  -h, --help                         Print help
  -V, --version                      Print version

Backups of volumes and databases

Usage: pyo backup [OPTIONS] <COMMAND>

Commands:
  now   Back up a volume or database now
  help  Print this message or the help of the given subcommand(s)

Options:
      --url <URL>          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to) [env: PYO_URL]
  -s, --service <SERVICE>  The service: a name ("api", "shop/api") or id. Default: pyo.toml's
      --token <TOKEN>      An API key, for CI (default: the one `pyo login` saved) [env: PYO_TOKEN]
  -h, --help               Print help
  -V, --version            Print version

Back up a volume or database now.

Without --volume or --db: the service's volume, when it has one.

Usage: pyo backup now [OPTIONS]

Options:
      --url <URL>
          Your Pyo, e.g. https://pyo.example.com (default: the one you signed in to)
          
          [env: PYO_URL]

      --volume <VOLUME>
          The volume: an id, "name" or "project/name"

      --db <DB>
          The database: its name or id

  -s, --service <SERVICE>
          The service: a name ("api", "shop/api") or id. Default: pyo.toml's

      --token <TOKEN>
          An API key, for CI (default: the one `pyo login` saved)
          
          [env: PYO_TOKEN]

      --wait
          Wait until it's done

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version