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

Console & One-off Commands

Sometimes you need to get inside a running app: poke at the filesystem, open a framework console, or run a migration script. The platform gives you three ways in, for Web Applications and Background Workers:

  • an interactive Console in the dashboard,
  • paas exec for an interactive terminal from your own shell,
  • paas run for one-off, non-interactive commands.

Consoles are only available for resources that run your code. Databases and Object Storage buckets have no console — manage databases through attachments and buckets through the Files tab or paas buckets.

To open a console or run a command you need the deploy permission on the project, and the app needs at least one running instance — the dashboard’s Connect button is only enabled while the app’s status is running. See Access Control.

List running instances

Each app runs as one or more instances (set by its replica count or autoscaling). paas ps lists them:

$ paas ps -o acme -p shop -e production -a web
INSTANCE             PHASE    READY  CONTAINERS
web-7d9f6c5b48-2xqkm Running  true   web

If no instance is ready because a build is still in progress (or a build failed), paas ps prints the reason below the table. Add --json for the raw API response.

Inside a repository with a d2o (Environment) or paas (app) git remote, the CLI infers -o/-p/-e from it — and -a from the paas remote, or from the directory you’re in for apps built from the Environment’s remote — so a bare paas ps works. Elsewhere, pass the flags, or set defaults with paas orgs set-default and paas projects set-default (environment and app must always come from the flag or the remote).

Console in the dashboard

  1. In the dashboard, open the environment and click the app.
  2. Open the Console tab.
  3. Pick an instance from the dropdown — the first ready one is pre-selected.
  4. Click Connect.

You get a shell (/bin/sh by default — change the command field before connecting if you want something else, like a framework console). Run commands as you would in any terminal; press Ctrl+D or click Disconnect to end the session.

The session stays alive if you switch to another tab of the same app — for example to glance at Logs — and is still connected when you come back.

If the tab shows “Resource must be running to connect to console”, the app has no ready instance yet; check its status on the Overview tab and its deployments.

Interactive terminal with paas exec

paas exec opens the same kind of session from your own terminal:

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

You land in /bin/sh on a running instance. Exit with exit or Ctrl+D.

Options:

  • --command <COMMAND> — start something other than /bin/sh.
  • --instance <INSTANCE> — connect to a specific instance, by the name shown in paas ps. Without it, the first running instance is used.
  • --container <CONTAINER> — only needed if an instance runs more than one named process; normally leave it out.

paas exec requires a real terminal: it refuses to start when stdin/stdout is not a TTY (a script, CI), and --json is not supported — there is nothing to render as JSON in an interactive session. For scripted work, use paas run.

One-off commands with paas run

paas run executes a single command on a running instance and prints its output. The -- before the command is required, so its flags aren’t parsed as paas run’s own:

paas run -o acme -p shop -e production -a web -- ls -la
paas run -a web -- ./bin/rails db:migrate

The command runs without an interactive terminal, so it must not expect input. paas run prints the command’s standard output; its error output is shown only when it printed nothing else (and paas run then exits 1). The command’s own exit status is not relayed, so check the output to see whether it worked. --instance and --container work the same as for paas exec, and --json returns the raw API response.

Next steps