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

CLI Overview & Authentication

The paas command-line tool covers the same ground as the dashboard — Organizations, Projects, Environments, and Resources — from your terminal. This page explains how it authenticates, where it keeps its state, and how it decides which Organization, Project, Environment, and app a command applies to. For a command-by-command listing, see the Command Reference.

Install

On macOS and Linux, one line installs the paas binary — no Rust toolchain needed:

curl -fsSL https://dl.d2o.io/install.sh | sh
paas --version

The full walkthrough — manual downloads, checksum and signature verification, and Windows — is in Installing the CLI.

Log in, check who you are, log out

Login happens in your browser, so your password never touches the terminal:

paas login --host <your-platform-url>

<your-platform-url> is the full dashboard origin, including https:// (hosted d2o: https://dashboard.d2o.io). The CLI opens the platform’s sign-in page, then a consent page, Approve d2o CLI sign-in, showing the account you’re signed in as and the token name; click Approve sign-in. That sends a short-lived, single-use code back to the CLI, which exchanges it for an API token and stores it. The tab then reads “Signed in to d2o PaaS” and you can close it. If no browser opens, visit the URL the CLI prints on the same machine. For remote hosts, see Remote terminals and CI. Each login mints a named token (default cli <hostname>); pick your own name with --name "work-laptop". Logging in again to the same host asks the server to revoke the previously stored token before replacing it (best-effort — if the revoke fails, the old token remains listed under paas auth tokens list and can be revoked there).

paas whoami    # show the logged-in user
paas logout    # revoke this host's token and forget it locally

You can list and revoke your tokens at any time with paas auth tokens list and paas auth tokens revoke <id>, and print the current token for scripting with paas auth token. See Account, SSH Keys & API Tokens.

Where the token is stored

The CLI keeps its state in a single file, config.toml, in your platform’s standard config directory: ~/.config/paas/config.toml on Linux, ~/Library/Application Support/paas/config.toml on macOS, %APPDATA%\paas\config.toml on Windows. (Set PAAS_CONFIG_DIR to override the directory.)

The file holds one entry per host — the API token, and your default Organization and Project for that host — plus the current_host your last login pointed at. You can be logged in to several installations at once and switch between them with --host or by logging in again.

The token is stored in plain text, so on Linux and macOS the CLI protects the file at the filesystem level: the directory is created with mode 0700 and the file is written atomically with mode 0600 — it is never world-readable, even for a moment. Windows has no such permission bits, so the file inherits whatever your user profile directory allows. Either way, treat it like a password: do not commit it or copy it between machines.

Environment variables

Three variables override the config file, which is what you want in scripts and CI:

  • PAAS_API_URL — the API host to talk to.
  • PAAS_API_TOKEN — the API token to use. An environment-supplied token is never written to disk, and paas logout refuses to clear it — unset the variable instead.
  • PAAS_CONFIG_DIR — an alternate config directory; the CLI then reads and writes $PAAS_CONFIG_DIR/config.toml.

Precedence, per value:

  • API host: --host flag > PAAS_API_URL > the configured current_host.
  • Token: PAAS_API_TOKEN > the stored token for the resolved host. If neither exists, commands fail with “not logged in” and point you at paas login.

How the CLI finds your context

Most commands need some combination of Organization, Project, Environment, and app. Each value is resolved independently; the first source that supplies it wins:

  1. Flags: -o/--org, -p/--project, -e/--env, -a/--app — available on every command.

  2. The git remote of the current repository — d2o, else paas. An Environment’s shared remote (…/sources/acme/shop/production.git) encodes Organization, Project and Environment, and the app is the one whose source directory contains your working directory (or the only app building from the repository root); an app’s own remote (…/sources/acme/shop/production/web.git) encodes all four values. When your working directory matches none of the shared remote’s apps — a checkout that still has an older per-app paas remote left over from before d2o existed — the CLI falls back to that paas remote’s app rather than erroring. The remote is ignored, with a printed hint, when it belongs to a different installation than the API host you are talking to. It is also ignored when -o names a different Organization than the remote’s. When -p names a different Project, only the remote’s Organization carries over; -e alone still takes the rest from the remote.

  3. Stored defaults for Organization and Project, saved per host:

    paas orgs set-default acme
paas projects set-default shop

    Environments and apps have no stored default — supply those via a flag or the git remote.

  4. Otherwise the command errors, naming the missing value and each way to supply it.

JSON output

Every read command accepts --json, which prints the raw API response instead of a formatted table:

paas projects list -o acme --json

This is the stable contract for scripting. The streaming commands are the exception: paas logs --tail, paas watch and paas exec reject --json, since a live stream and an interactive session have no JSON to render.

Shell completions

Generate completions for your shell and install them in its completion directory:

paas completions zsh

Supported shells: bash, elvish, fish, powershell, zsh.

Next steps