Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command Reference

This page documents every paas command. Install the CLI and log in first — see Installing the CLI and CLI Overview & Authentication. Most of what the CLI can do is also available in the dashboard; the guide pages cover both paths side by side. A few operations — managing API tokens and printing a bucket’s S3 credentials — are currently CLI-only.

Run paas --help for the full command tree, or paas <command> --help for any command’s own flags and arguments.

Global flags

Every command accepts the same set of global flags:

  • --host <HOST> — the platform address to talk to (the address you open the dashboard at, including https://, written as <your-platform-url> in these docs). Overrides the PAAS_API_URL environment variable and the configured current host, so you can target a different installation for a single command.
  • --json — print the raw API JSON response instead of a table. Useful for scripting, for example piping into jq.
  • -o, --org <ORG> — the Organization to act on (its slug, e.g. acme).
  • -p, --project <PROJECT> — the Project within that Organization (e.g. shop).
  • -e, --env <ENV> — the Environment within that Project (e.g. production).
  • -a, --app <APP> — the app (a Web Application or Background Worker Resource) within that Environment (e.g. web); bucket commands use the same flag to select a bucket.
  • -h, --help — print help. paas -V prints the CLI version.

Most commands need some or all of the -o/-p/-e/-a context to know what to act on. You can save a default Organization and Project with paas orgs set-default and paas projects set-default so you do not have to repeat the flags in every command. The examples below spell the flags out in full the first time each appears, then rely on context where it keeps the example readable.

paas login

paas login [--name <NAME>] [--host <your-platform-url>]

Logs you in via your browser: the CLI opens the platform’s sign-in page, you approve the request, and the CLI stores an API token for that host. Accounts on the platform are created by invitation, so you need an invitation before your first login — see CLI Overview & Authentication.

  • --name <NAME> — the token name shown in paas auth tokens list (default: cli {hostname}), handy for telling machines apart later.
paas login --host <your-platform-url> --name "work laptop"

paas logout

paas logout

Revokes this host’s token and forgets it locally. Run it on any machine you no longer want to have access.

paas whoami

paas whoami

Shows the logged-in user. A quick way to confirm which account (and, with --host, which installation) you are talking to.

paas whoami --json

paas auth

Manage authentication and API tokens.

  • paas auth token — print the current API token, for scripting. For example, to hand it to another tool:

    TOKEN=$(paas auth token)

  • paas auth tokens — manage this user’s API tokens. paas auth tokens list shows every token on your account with the name each was given at login. Revoke a token you no longer need with paas auth tokens revoke <ID>, using the ID shown by paas auth tokens list; paas logout revokes the current machine’s token.

Treat the printed token like a password: anyone holding it can act as you.

paas orgs

paas orgs <list|info|create|update|transfer|delete|set-default>

Manage Organizations. paas orgs info shows one Organization, falling back to the resolved -o context when you do not name one. paas orgs set-default saves the Organization the CLI should assume when -o is omitted. Deleting an Organization is permanent — the dashboard’s Organization settings page walks you through the same operation with a confirmation step.

  • create <SLUG> and update <SLUG> take --name <NAME> (the display name) and --description <DESCRIPTION>.
  • transfer <SLUG> --to <EMAIL_OR_USER_ID> transfers ownership to an existing member. The organization slug is required explicitly; the recipient can be identified by a case-insensitive email match or user UUID. Only the owner can transfer a team organization; personal organizations cannot be transferred. The previous owner becomes an Admin immediately. Type the organization slug at the prompt, or pass --confirm <SLUG> for non-interactive use. --json prints the updated organization returned by the API.
  • delete <SLUG> asks you to type the slug to confirm. The prompt names what will be deleted and the platform it is on, so you can tell staging from production. Pass --confirm <SLUG> to skip the prompt in scripts; without it, a delete run outside a terminal is refused rather than guessed.
paas orgs list
paas orgs info -o acme
paas orgs create acme-labs --name "Acme Labs" --description "Experiments"
paas orgs transfer acme-labs --to new-owner@example.com --confirm acme-labs
paas orgs delete acme-labs --confirm acme-labs

See Managing Your Organization for what lives at the Organization level.

For prerequisites and the equivalent dashboard flow, see Transferring ownership.

paas projects

paas projects <list|info|create|update|delete|set-default>

Manage Projects within an Organization. paas projects info falls back to the resolved -p context when you omit a name, and paas projects set-default saves your usual Project and makes its Organization the default too. A default Project applies only within its own Organization: with -o naming another, it isn’t used, and paas orgs set-default to a different Organization clears it.

create, update and delete take the same flags as paas orgs: --name, --description, and --confirm <SLUG> on delete.

paas projects list -o acme
paas projects create shop -o acme --name "Shop" --description "Storefront and API"

paas envs

paas envs <list|info|create|update|delete>

Manage Environments within a Project. paas envs info falls back to the resolved -e context when you omit a name; list and info show each Environment’s release source.

  • create <NAME> requires --type development|staging|production. It also takes --branch <BRANCH>, --no-auto-deploy (create with automatic deployments turned off) and --release-source build|promote.
  • update <NAME> takes --branch <BRANCH>, --auto-deploy true|false and --release-source build|promote.
  • delete <NAME> asks you to confirm; pass --confirm <NAME> in scripts.

info also shows whether the Environment is protected. Protection is turned on in the dashboard (Environment settings → Protected); the CLI has no flag for it.

build Environments build their apps from git; promote Environments only run images promoted from another Environment — see Pipelines, Promotion & Rollback.

paas envs list -o acme -p shop
paas envs create staging -o acme -p shop --type staging --release-source promote
paas envs update production -o acme -p shop --auto-deploy false

paas apps

paas apps <list|info|create|update|delete|attachments|attach|detach>

Manage apps — your Web Application and Background Worker Resources — within an Environment. paas apps info falls back to the resolved -a context when you omit a name.

list and info show each app’s status, with (blocked - over monthly transfer allocation) appended when the app has been scaled to zero for being over its monthly transfer allocation — see Troubleshooting & FAQ.

create <NAME> and update <APP> take the same settings as the dashboard form:

  • --framework <FRAMEWORK> — required on create: one of nodejs, rails, python, go, rust, static (see Supported Frameworks). An unknown value is rejected with an error naming the field and the accepted values.
  • --port <PORT> — the web app’s HTTP port, or the port used by a worker’s HTTP health check. Defaults to 3000 when omitted.
  • --health-check-path <PATH> — for a Web Application, the path a new version must answer on before it takes traffic. New Static Files web apps default to / when this is omitted. Background Workers can set one too, as an alternative to --health-check-command. On update, pass "" to clear it.
  • --health-check-command <COMMAND> — Background Workers only: a command that must exit 0 for a new instance to count as healthy. Without a path or a command, a worker counts as healthy once it runs for 30 seconds without restarting. On update, pass "" to clear it.
  • --replicas <N>, --cpu <CPU> (e.g. 500m, 1), --memory <MEMORY> (e.g. 512Mi, 1Gi).
  • --autoscaling-min <N>, --autoscaling-max <N>, --autoscaling-cpu-target <PERCENT> — any of them turns autoscaling on. --autoscaling true|false (update only) turns it on or off explicitly; false can’t be combined with the other three. See Scaling & Autoscaling.
  • --worker (create only) — create a Background Worker instead of a Web Application.
  • --git-repo, --git-branch and --source-mode push|external (create only) appear in the help but building from an arbitrary git URL isn’t supported; apps deploy from their platform-hosted repository.
  • --shared-source — build from the Environment’s shared repository instead of one of the app’s own; update --own-source switches back. See One remote for several apps.
  • --source-dir <DIR> — with a shared source: the directory inside the repository the app’s build starts in (default: the repository root; . on update resets it).
  • --process <NAME> — the Procfile process to run when the build produces several (for example web or worker). On update, pass an empty string (--process "") to clear it. --start-command still works as an older name for the same flag.
  • --release-command <COMMAND> — runs once against each deployment’s new version, before any instance starts; see Release command. On update, pass "" to clear it and fall back to a Procfile release: line, if any.
  • --auto-rollback true|false — whether a version that never becomes healthy is automatically replaced with the last version that was Live; on by default. See When a new version isn’t healthy.

Any of --process, --port, --health-check-path, --health-check-command, --auto-rollback, or --singleton can instead be set by the app’s own d2o-paas.yaml; --release-command can be set there too, or by the Procfile’s release: line — the Procfile has no effect on the others (process name matching doesn’t count as setting --process; see Procfile). While a deployed version sets one of these that way, update on it fails instead of silently being overridden on the next deployment:

`health_check` is set in d2o-paas.yaml at abc1234; change it there

delete <APP> asks you to confirm; pass --confirm <APP> in scripts.

create and update also take --singleton true|false. A singleton runs at most one instance; deployments and restarts stop the old instance before starting the new one, so expect a few seconds of downtime. Use it for bots and other apps that must never run twice. It can’t be combined with autoscaling or more than one replica — see Singleton apps.

paas apps info -o acme -p shop -e production -a web
paas apps create web -o acme -p shop -e production --framework nodejs --port 3000
paas apps update web -o acme -p shop -e production --memory 1Gi

See Creating a Web Application for the full create flow, and Deploying with Git Push or Deploy from GitHub or GitLab for getting code to it.

App attachments

paas apps attachments APP
paas apps attach APP RESOURCE [--env-var NAME | --prefix PREFIX]
paas apps detach APP ATTACHMENT_ID

Use -o, -p, and -e to select the Environment. APP resolves to a Web Application or Background Worker; RESOURCE resolves to a Database or Object Storage resource in that Environment. For databases, --env-var defaults to DATABASE_URL. For buckets, omit --prefix for the primary S3 variables or provide a prefix for another bucket. Wrong-type flags are rejected, and the API enforces the relevant project permissions. The attachment list includes the ID required by detach and never prints credentials. Detaching affects the app’s connection only; it does not delete the backing resource. All three commands support --json.

paas manifest check

paas manifest check [FILE] -o acme -p shop -e production

Validates a d2o-paas.yaml file against an Environment’s apps, without pushing. FILE defaults to d2o-paas.yaml in the current directory.

$ paas manifest check -o acme -p shop -e production
d2o-paas.yaml is valid for production

Errors print the same way a failed deployment’s would, with the line and field at fault; warnings print as warning: … lines and don’t affect the exit code. Exits 1 if the file is invalid and 2 if it can’t be read, so it’s usable as a CI gate before pushing:

paas manifest check -o acme -p shop -e production && git push paas main

See d2o-paas.yaml Reference for every field, error, and warning.

paas dbs

paas dbs <list|info|create|update|delete>

Manage Database Resources within an Environment. Available engines are PostgreSQL, Redis, MongoDB, and MariaDB. Backups run automatically for PostgreSQL and MariaDB; restoring from a backup requires contacting support. See Databases and Database Backups.

  • create <NAME> requires --type postgresql|redis|mongodb|mariadb, and takes --version <VERSION> and --storage-gb <GB>.
  • create also takes --ha, turning on high availability for a PostgreSQL database. Any other --type with --ha is rejected.
  • update <DB> takes --ha true|false, toggling high availability on an existing PostgreSQL database. Enabling it copies the data to the new standby in the background with no downtime; disabling it removes the standby. The connection string and any attachments are unaffected.
  • delete <DB> asks you to type the name to confirm; pass --confirm <DB> in scripts.
paas dbs list -o acme -p shop -e production
paas dbs create shop-db -o acme -p shop -e production --type postgresql --storage-gb 10
paas dbs create shop-db -o acme -p shop -e production --type postgresql --ha
paas dbs update shop-db -o acme -p shop -e production --ha true

paas config

paas config <list|set|unset> [--scope org|env|app]

Manage environment variables for the app selected with -a, or — with --scope — the plain variables every app inherits from its Organization or Environment.

  • --scope app (the default) acts on the app’s own variables and needs the full -o/-p/-e/-a context.
  • --scope env acts on the Environment’s variables (-o/-p/-e), which every app in that Environment inherits.
  • --scope org acts on the Organization’s variables (-o), which every app in the Organization inherits.

An app’s own variable overrides an Environment variable with the same key, which in turn overrides an Organization variable.

  • paas config set takes one or more KEY=VALUE pairs, applied in order; it stops at the first failure. Alternatively, --secret-ref NAME KEY points a single bare key at a platform-managed secret instead of a literal value, so the secret’s value reaches your app without ever appearing on your command line or in your shell history.
  • --hidden stores each value as a hidden value, like the dashboard’s Secret value (hidden): nobody can read it back, and it needs the Manage secrets capability. KEY=- reads that value from stdin, so it stays out of your shell history; on a terminal it’s typed without echo. An empty value is refused. A plain value can’t be saved over a hidden one.
  • For --scope env and --scope org, a value that was saved but that some apps couldn’t take yet prints a warning naming those apps, and the CLI carries on with the next key. Run the same command again to retry them.
  • paas config unset <KEY> removes one variable.
  • paas config list shows the variables in scope. For an app it includes the ones inherited from its Environment and Organization, with a SOURCE column and (overridden) on any an app variable replaces (secret links show as <secret:NAME>); --json prints only the app’s own.
paas config set -a web LOG_LEVEL=info FEATURE_FLAGS=beta
paas config set -a web --secret-ref DB_PASSWORD DATABASE_PASSWORD
printf %s "$API_TOKEN" | paas config set -a web --hidden API_TOKEN=-
paas config set --scope env -e staging LOG_LEVEL=debug
paas config unset --scope org LOG_LEVEL

--secret-ref and --hidden work with the app scope only; Organization and Environment variables are plain values.

See Environment Variables and Managing Secrets.

paas domains

paas domains <list|add|verify|remove|release>

Manage the custom domains of the Web Application selected with -a.

  • list — show the app’s custom domains, the status of each (unverified, verifying, active, error) and when it was added. The reason behind an error is printed under the table.
  • add <DOMAIN> — claim a hostname, for example app.example.com, and print both DNS records to create for it: the ownership TXT and the traffic CNAME (or ALIAS, which some DNS providers call ANAME, for a root domain). The domain is not served and gets no certificate until it is verified.
  • verify <DOMAIN> — check the ownership record and, when it matches, verify the domain. On a mismatch the record that has to exist is printed again.
  • remove <DOMAIN> — detach a hostname from the app.
  • release <DOMAIN> — free a domain another organization is serving, by proving you own it. Organization-scoped: it takes -o only, not -p/-e/-a.
paas domains add app.example.com -o acme -p shop -e production -a web
paas domains verify app.example.com -a web
paas domains list -a web
paas domains remove app.example.com -a web
paas domains release example.com -o acme

Adding, verifying or removing a domain needs the Manage web apps capability; release needs organization Owner or Admin. Verifying a domain, and removing a verified one, redeploy the app; adding one does not — an unverified claim changes nothing. Only one organization can hold a domain verified, so adding a name another organization is already serving fails with “That domain is already in use on the platform.” — take it back with paas domains release, then add it again. A claim left unverified for 7 days is dropped, and an apex domain does not cover its subdomains: each hostname is verified on its own.

See Custom Domains & TLS. Background Workers, Databases, and buckets have no custom domains.

paas buckets

paas buckets <list|info|create|delete|migrate|ls|url|visibility|creds|put|get|rm>

Manage Object Storage resources within an Environment. list, create and delete act on -o/-p/-e alone, like paas dbs. migrate takes a positional bucket name; the remaining subcommands select a bucket with -a.

  • list — list the Environment’s buckets, with a TIER column (capacity or ha, or <tier> -> <target> (<phase>) while a tier move is in progress) and a STATUS column that appends (blocked - over monthly transfer allocation) when the bucket’s public visibility is currently suspended — see Plans, Limits & Usage.
  • create <NAME> — create a bucket. Takes --public to make it public immediately, --tier capacity|ha (large, low-cost, single-node storage by default; ha replicates it so it survives node loss), and --quota-gb for a cap on the bucket’s total stored data (10 GB when you leave it out). The tier is only the starting point — move it later with migrate.
  • delete <NAME> — asks you to type the name to confirm; pass --confirm <NAME> in scripts. Refused while a tier move is in progress.
  • migrate <NAME> --tier capacity|ha — move the bucket to a different storage tier; see Moving a bucket to a different tier. Takes --yes to skip the confirmation prompt (required in a non-interactive session) and --wait to poll until the move finishes instead of returning immediately.
  • info — show the bucket’s details, including its tier (same <tier> -> <target> (<phase>) format while moving) and, if the bucket is blocked, a status: blocked - over monthly transfer allocation line and a public: line reading private (blocked; public once unblocked) if its stored visibility is public.
  • ls [PREFIX] — list objects, optionally under a prefix. Only the first page is shown; a note says when more objects exist — narrow it with a prefix.
  • url — print the bucket’s public URL (fails if none is assigned yet).
  • visibility public|private — make the bucket public or private.
  • creds — print S3-compatible credentials as shell export statements (--format env, the only format and the default), so you can use any standard S3 tool against the bucket.
  • put <FILE> [KEY] — upload a file. KEY defaults to the file’s own name. --content-type overrides the guess the CLI makes from FILE’s extension.
  • get <KEY> [FILE] — download an object. FILE defaults to KEY’s base name; pass - to write the object’s bytes to stdout instead.
  • rm <KEY> — delete one object.

put and get transfer the file directly to and from storage over a short-lived signed link. The link itself is never printed except in --json output, where it stays valid for 15 minutes — treat that output as a secret. A get that fails partway never touches an existing file at the destination.

paas buckets create media -o acme -p shop -e staging --tier ha --quota-gb 50
paas buckets migrate media --tier ha -o acme -p shop -e staging --wait
eval "$(paas buckets creds -a media)"
paas buckets ls -a media
paas buckets ls images/ -a media
paas buckets put ./banner.png -a media
paas buckets get banner.png ./local-banner.png -a media
paas buckets rm old-banner.png -a media
paas buckets visibility public -a media
paas buckets delete media --confirm media

See Object Storage Buckets.

paas attach / paas detach / paas attachments

paas attach <DB_OR_BUCKET> [--as <NAME>] -a <APP>
paas detach <DB_OR_BUCKET> [--as <NAME>] -a <APP>
paas attachments -a <APP>

Attach or detach a Database or Object Storage bucket from the app selected with -a. The Database/bucket and the app must be in the same Environment.

  • attach <DB_OR_BUCKET> — for a Database, --as <NAME> sets the injected connection-string variable’s name (default DATABASE_URL); for a bucket, --as <PREFIX> sets the credential-variable prefix (default: none, the app’s primary bucket, using the plain AWS_*/S3_* names). Prints what the app now receives.
  • detach <DB_OR_BUCKET> — removes the attachment. The Database or bucket itself is untouched. If the same source is attached to the app more than once (under different names/prefixes), --as <NAME> says which one to remove; without it, the CLI lists the names in use and refuses to guess. A --as that names no attachment is refused, even when there is only one.
  • attachments — list what’s attached to the app: source, type, variable name or prefix, and when it was attached.
paas attach shop-db -a web
paas attach shop-db --as REPORTING_DB_URL -a worker
paas attach media --as ASSETS -a web
paas attachments -a web
paas detach media -a web

See Attaching a Database and Object Storage Buckets.

paas git

paas git remote [-a <APP>] [--https] [--print]

Without -a, prints — and by default configures — the Environment’s shared remote as d2o. With -a, the app’s own remote as paas (a shared-source app’s remote is the Environment’s, so it is set as d2o). Outside a git repository it only prints the URL. Run it inside your repository, then deploy with an ordinary push:

paas git remote -e production
git push d2o main
  • --print — only print the URL; don’t touch the local git remote.
  • --https — use the HTTPS remote instead of SSH. The push token (valid for 30 days) is stored with git’s credential helper, never in the remote URL; re-run the command to get a fresh one. It needs a credential helper, such as your OS keychain or git config --global credential.helper store, and stops with an error when none is configured. Before CLI 0.11.0 the token was written into the remote URL.

A promote-only Environment has no remote: pushes to it are refused with the upstream Environment to push to. Pushing over SSH uses the keys you register with paas keys. See Deploying with Git Push.

paas keys

paas keys <list|add|remove>

Manage your SSH keys, used to authenticate git push deployments. paas keys add [FILE] uploads an SSH public key and defaults to the first of ~/.ssh/id_ed25519.pub, id_ecdsa.pub or id_rsa.pub it finds, so on most machines this is all it takes:

paas keys add
paas keys add ~/.ssh/work_ed25519.pub

paas keys remove <ID> deletes a key from your account, using the ID from paas keys list:

paas keys list
paas keys remove <ID>

You can also manage keys in the dashboard under your account settings — see Account, SSH Keys & API Tokens.

paas deploy-tokens

paas deploy-tokens <create|list|revoke>

Push credentials for CI, scoped to the environment’s remote, or to an app’s own remote with -a. create <name> [--expires 30|90|365] (default: never expires) prints the token once, with the remote URL and a ready-made git push line; CI needs full git history (fetch-depth: 0 on GitHub Actions, GIT_DEPTH: 0 on GitLab CI). list shows name, creator, expiry and last use, never the token. revoke <name|id> stops a token immediately; pass -a for a token scoped to an app. See Deploying from CI.

paas connections

paas connections <list|connect>

list prints a table of the Organization’s GitHub and GitLab connections — ID, PROVIDER, HOST, ACCOUNT and STATUS. Use the ID with paas links set --connection. Connecting is browser-only: connect prints:

Connect from the dashboard: <dashboard URL>/orgs/<org>/settings/integrations

See Deploy from GitHub or GitLab.

paas links <get|set|unset|deploy-latest>

Links an Environment’s or an app’s (-a) deployment target to a repo and branch on a connected provider.

  • get prints the current link, for example “Deploys from GitHub acme/shop@production”, plus its settings (whether direct pushes are allowed, whether it waits for CI), the last push and its state (Last push: abc1234 Waiting for checks), and a warning if the provider connection is broken — or that nothing is linked.
  • set --connection <id> --repo <owner/name|id> --branch <branch> [--allow-direct-push] [--wait-for-ci [<true|false>]] creates or updates the link, using the connection ID from paas connections list. --repo resolves owner/name against the connection’s repos. set replaces the whole link, so leaving out --allow-direct-push or --wait-for-ci on an existing link turns each one off again, even if it was previously on. A bare --wait-for-ci (no value) means true, same as --allow-direct-push. See Wait for CI for what it waits for.
  • unset removes the link; direct pushes are allowed again immediately.
  • deploy-latest deploys the linked branch’s current head on demand. It prints Deploying <sha>, Already deployed <sha> when that commit is already live (nothing is redeployed), or — with Wait for CI on — Waiting for checks on <sha>.

For a GitLab repository, verify your GitLab account in the dashboard first (Settings → Deploy from GitHub/GitLab, then Edit settings if a repository is already linked → Choose with your GitLab account). That verification lasts about two hours and also lets paas links link GitLab repositories you maintain.

paas links set --connection <id> --repo acme/shop --branch production -e production
paas links set --connection <id> --repo acme/shop --branch production -e production --wait-for-ci true
paas links get -e production
paas links deploy-latest -e production

See Deploy from GitHub or GitLab.

paas deploy

paas deploy -a web

Triggers a deployment of the app selected with -a: the platform rolls the app forward to its current desired configuration. Useful when you want to roll out a change now rather than wait, or in an Environment where automatic deployments are turned off. It first deploys the app’s latest successful build, including one waiting as Built because automatic deployments are off. In a promote-only Environment it is refused; use paas promote instead. See Deployments, Health Checks & Rollback.

paas status

paas status -o acme -p shop -e production -a web

Shows the deployment status of the app selected with -a: whether what is running matches what you have configured, the app’s health, and its running instances.

paas deploys

paas deploys [list] [--before <N>] [--limit <N>] [-a <APP>] -e production
paas deploys info <N> -e production
paas deploys rollback [N] [--yes] -e production

list (the default) shows 25 deployments per page, newest first (--limit sets 1–100). When there may be more, it prints a More: paas deploys list --before <N> line to paste for the next page. With -a, only deployments that included that app are listed. Columns: number, stage, apps, commit, who pushed, age, and failure reason. Accepts --json. info <N> prints the full timeline for one deployment — every stage and app event it went through.

rollback [N] rolls back a deployment that failed; without a number, the Environment’s most recent deployment, if it ended Failed or Rollback failed (when a newer deployment is live, it exits and asks for a number). A manual rollback of deployment N goes back to the version that was live before N. Asks for confirmation unless you pass --yes. Only the most recent deployment can be rolled back this way — for an earlier one, push a fix (or revert the commit and push that) in a build Environment, or promote the version you want in a promote-only one. (This is different from paas rollback --to <id>, below, which re-pins a promote-only Environment to any earlier version regardless of health.)

paas releases is kept as an alias for paas deploys list. See Deployments, Health Checks & Rollback.

paas promote

paas promote <app> --from <env> --to <env> [--yes]
paas promote --all --from <env> --to <env> [--yes]

Copies an app’s built image from one Environment into the next — the image is never rebuilt. The target must be promote-only. With --all, every app present in both Environments is promoted. A protected target prompts for the Environment’s name unless you pass --yes. Prints one row per app with its outcome and code; exits 1 when any row errored, or when the single app you named was skipped for any reason other than ALREADY_CURRENT. See Pipelines, Promotion & Rollback.

paas rollback

paas rollback <app> --to <deployment-id>

Re-pins an app on a promote-only Environment to an earlier image. Take the id from paas deploys list --json. Refused on a build stage (BUILD_ENV) and when the app already runs that image (ALREADY_CURRENT).

paas ps

paas ps -a web

Lists the running instances of the app selected with -a. The instance names it prints are what the --instance flag on logs, run, and exec accepts when you need to target one specific instance. When no instance is running yet, it says why — for example, that the build is still running or failed.

paas watch

paas watch [--deploy <N>] [--quiet] [--timeout <SECONDS>]

Follows a deployment stage by stage — Received, Queued, Building, Built, Running release command, Releasing, Starting, Live — streaming its build and release logs as it goes, and prints the deployment page’s URL. Run it right after a push:

git push paas main
paas watch --deploy 42

Without --deploy, it follows the newest deployment for the app or Environment inferred from your paas git remote; inside an Environment’s shared repository with no -a, it follows every app the push affects.

  • --quiet — print stage changes only, without streaming the logs.
  • --timeout <SECONDS> — how long to wait before giving up, default 1800.

Exits 0 when the deployment reaches Live, 1 when it ends Failed, Rolled back, Rollback failed, or Replaced, and 2 on a timeout, a lost connection, or a usage error. It watches the deployment’s event stream rather than polling, so like paas logs --tail, it rejects --json. See Deployments, Health Checks & Rollback.

paas scale

paas scale <N> -a web

Sets the app’s replica count to N running instances.

paas scale 3 -a web

If autoscaling is enabled for the app, manual scaling is rejected — change the autoscaling bounds, or turn autoscaling off first with paas apps update web --autoscaling false. Scaling is also refused while the app is blocked for being over its monthly transfer allocation. A singleton app can be scaled to 0 or 1 only. See Scaling & Autoscaling.

paas restart

paas restart -a web

Restarts the app selected with -a, replacing its running instances. See Restarting an App.

paas logs

paas logs [--tail] [--instance <INSTANCE>] [--container <CONTAINER>] [-n <NUM>] -a web
paas logs --build <N> [--release] [--app <NAME>]

Shows logs for the app selected with -a: a snapshot by default, or a live stream with --tail.

  • --tail — follow logs live. Both the snapshot and the live stream show every running instance; once more than one instance has printed, each line is prefixed with [instance-name]. The stream starts from each instance’s last 200 lines, so combining --tail with --container, -n, or --json is a usage error.
  • --instance <INSTANCE> — show only one instance (names come from paas ps); works with snapshots and --tail.
  • --container <CONTAINER> — rarely needed; leave it unset unless support asks you to use it.
  • -n, --num <NUM> — how many lines the snapshot returns (default 500, maximum 10000).
  • --build <N> — a one-shot snapshot of the build log for deploy #N instead of app instance logs. Build logs are saved for the Environment’s 1000 most recent deploys (the last 1 MB of each); use paas watch to follow a build live.
    • --release — the deployment’s release command log instead of its build log.
    • --app <NAME> — which app’s log; required when the deployment covers more than one app (a shared build or a push to an Environment remote).
paas logs -a web -n 100
paas logs -a web --tail
paas logs --build 42
paas logs --build 42 --release --app worker

See Logs and Deployments, Health Checks & Rollback.

paas run

paas run [--instance <INSTANCE>] [--container <CONTAINER>] -a web -- <COMMAND> [ARGS...]

Runs a one-shot command in a running instance of the app and prints its output. The -- before the command is required so the command’s own flags are not parsed as paas run’s:

paas run -a web -- ls -la

Typical uses are database migrations, seed scripts, and quick inspections. See Console & One-off Commands.

paas exec

paas exec [--instance <INSTANCE>] [--container <CONTAINER>] [--command <COMMAND>] -a web

Opens an interactive terminal in a running instance of the app — the CLI equivalent of the dashboard’s web console. It requires stdin and stdout to be a real terminal, and --json is not supported (there is nothing to render as JSON in an interactive session). Use --instance to pick a specific instance and --command to choose the program to start in the session.

paas exec -a web

paas completions

paas completions <SHELL>

Generates shell completions for bash, elvish, fish, powershell, or zsh. Write the output where your shell loads completions from, for example:

paas completions zsh > ~/.zsh/completions/_paas

Next steps