Installing the CLI

The paas command-line tool lets you manage Organizations, Projects, Environments, and Resources from your terminal — everything from creating an app to streaming its logs. This page gets it installed and logged in.

Most of what the CLI does is also available in the dashboard, so the CLI is optional — though a few things, such as printing a bucket’s S3 credentials, are currently CLI-only. It’s also the fastest way to work once you deploy regularly.

Prerequisites

• A platform account. The platform is invitation-only, so you should already have accepted an invitation and be able to sign in to the dashboard. If not, see Inviting People.
• Nothing else. The CLI is a single prebuilt binary with no runtime dependencies — you do not need a Rust toolchain unless you choose to build it yourself.

Install

On macOS and Linux, the install script picks the right build for your operating system and CPU, verifies its SHA-256 checksum, and installs the paas binary into ~/.local/bin. If minisign is installed, the script also verifies the release signature and refuses to install on a mismatch; without it, the script says it skipped that check and installs on the checksum alone.

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

If ~/.local/bin is not on your PATH, the script says so and prints the line to add to your shell profile. Three environment variables change what it does:

For example, to pin a version and install into ~/bin:

curl -fsSL https://dl.d2o.io/install.sh | PAAS_VERSION=0.12.0 PAAS_INSTALL_DIR="$HOME/bin" sh

Verify it:

paas --version

The language tutorials and paas apps attach, paas apps attachments, and paas apps detach require 0.9.0 or later. paas deploy-tokens, paas connections and paas links need version 0.8.0 or later; paas deploys and paas manifest check need 0.7.0; paas attach and paas detach need 0.4.0. Run paas --version to check; to upgrade, run the install script again.

Install manually

Releases are published under https://dl.d2o.io/paas/v<VERSION>/. Check the current version:

curl -fsS https://dl.d2o.io/paas/latest.json

The examples below read that version, so they install the latest release. To pin a release, set VERSION (or $v on Windows) yourself.

macOS: select the archive for your CPU (arm64 below; use amd64 for Intel).

VERSION=$(curl -fsS https://dl.d2o.io/paas/latest.json | sed -n 's/.*"version" *: *"\([^"]*\)".*/\1/p')
BASE="https://dl.d2o.io/paas/v$VERSION"
ARCHIVE=paas-darwin-arm64.tar.gz
curl -fsSLO "$BASE/$ARCHIVE" && \
curl -fsSLO "$BASE/SHA256SUMS" && \
shasum -a 256 --ignore-missing -c SHA256SUMS && \
tar xzf "$ARCHIVE" && \
sudo install -d /usr/local/bin && \
sudo install -m 0755 paas /usr/local/bin/paas

Linux: select amd64 or arm64 for your CPU.

VERSION=$(curl -fsS https://dl.d2o.io/paas/latest.json | sed -n 's/.*"version" *: *"\([^"]*\)".*/\1/p')
BASE="https://dl.d2o.io/paas/v$VERSION"
ARCHIVE=paas-linux-amd64.tar.gz
curl -fsSLO "$BASE/$ARCHIVE" && \
curl -fsSLO "$BASE/SHA256SUMS" && \
sha256sum --ignore-missing -c SHA256SUMS && \
tar xzf "$ARCHIVE" && \
sudo install -m 0755 paas /usr/local/bin/paas

Stop if download or verification fails; do not install an archive with a checksum mismatch. Expect an OK line for the archive you selected. --ignore-missing skips the other platform archives listed in the shared checksum file.

Each archive is flat and holds the binary, a completions/ directory, a README, and — on Linux and macOS — the paas.1 man page.

Optionally, verify the release signature too (the install script does this for you when minisign is installed). SHA256SUMS.minisig is a minisign signature over SHA256SUMS, which in turn covers the archives, so checking it covers everything. Your platform operator publishes the public key:

curl -fsSLO $BASE/SHA256SUMS.minisig
minisign -Vm SHA256SUMS -P 'RWQHV7FbUhxhZzDFI+69HMeEtGMmL1XWAPl3rLKpPs70Bt+2YyC6zgsZ'

Opening https://dl.d2o.io/ in a browser returns an AccessDenied document rather than a file listing. That is expected: the download host serves the objects above, not an index.

Windows

There is no install script for Windows. Download the .zip for your architecture, compare its hash against the matching line in SHA256SUMS, unpack it, and add the folder holding paas.exe to your PATH:

$v    = (Invoke-RestMethod https://dl.d2o.io/paas/latest.json).version
$base = "https://dl.d2o.io/paas/v$v"
$dir  = "$env:LOCALAPPDATA\Programs\paas"

Invoke-WebRequest "$base/paas-windows-amd64.zip" -OutFile paas-windows-amd64.zip
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS

$want = (Select-String 'paas-windows-amd64.zip' SHA256SUMS).Line.Split()[0]
$got  = (Get-FileHash paas-windows-amd64.zip -Algorithm SHA256).Hash
if ($want -ne $got) { throw "checksum mismatch - do not install this file" }

New-Item -ItemType Directory -Force $dir
Expand-Archive paas-windows-amd64.zip -DestinationPath $dir -Force

$old = [Environment]::GetEnvironmentVariable('Path', 'User')
$new = (@($old -split ';') + $dir | Where-Object { $_ }) -join ';'
[Environment]::SetEnvironmentVariable('Path', $new, 'User')

Get-FileHash prints the hash in uppercase and SHA256SUMS records it in lowercase — that is fine, because PowerShell compares strings case-insensitively. Run the PATH block once; it appends, so a second run adds a duplicate entry.

The PATH change only reaches new processes, so open a fresh terminal before running paas --version.

Build from source

If your platform has no published binary, or you want to run an unreleased change, build the CLI from a checkout with a Rust toolchain:

cargo install --path crates/paas

Shell completions

Every archive ships completions in completions/, and the CLI can also print them for bash, elvish, fish, powershell, or zsh. Send the output to your shell’s completion directory:

paas completions zsh

Log in

Logging in happens through your browser, so you never type your password into the terminal:

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

<your-platform-url> is the full dashboard origin, including https:// (hosted d2o: https://dashboard.d2o.io). You need --host the first time; after that the CLI remembers your current host, and a plain paas login targets it.

Step by step:

1. The CLI starts a small listener on your own machine (127.0.0.1) and opens your browser to the platform. It also prints the address, so if no browser opens you can visit it in a browser on the same machine.
2. The platform’s sign-in page appears — sign in with your account. (You are asked to sign in each time you authorize a CLI login, even if you already have an active dashboard session.)
3. A page titled Approve d2o CLI sign-in shows the account you’re signed in as, that a code will be sent to 127.0.0.1:<port> on this machine — that is, back to the CLI — and the name of the API token it will create. Click Approve sign-in. If you didn’t run paas login, close the tab. Approve within 10 minutes of running paas login; after that the page says “CLI login expired or missing — run paas login again”.
4. The browser hands 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 (“You can close this tab and return to your terminal”) — you are logged in. If it reads Sign-in didn’t complete instead, your terminal says why.

Each login creates a named API token so you can tell your devices apart later. The default name is cli <hostname>; pick your own with --name:

paas login --host <your-platform-url> --name "work-laptop"

Logging in again replaces the stored token and attempts to revoke the old one. If revocation fails, the old token remains listed under paas auth tokens list; revoke it there.

Remote terminals and CI

The browser must reach the CLI listener on the machine running paas login. Opening the printed URL on your laptop while the CLI runs on a remote server sends the callback to the laptop instead. Use SSH port forwarding for the callback port, or provision an account API token through your secret-management workflow and supply PAAS_API_URL and PAAS_API_TOKEN in the remote environment. See API Access & Automation; a Git deployment token cannot log in to the API.

Verify

paas whoami

This prints the logged-in user for your current host. If instead you see “Not logged in”, run paas login again.

Where the token is stored

The CLI keeps its state in your platform’s configuration directory:

• Linux: ~/.config/paas/config.toml
• macOS: ~/Library/Application Support/paas/config.toml
• Windows: %APPDATA%\paas\config.toml (that is, C:\Users\<you>\AppData\Roaming\paas\config.toml)

This file holds your API token for each host you have logged in to, plus your current host and any default Organization or Project you set (there is no stored default Environment — supply it with -e or run inside a repo with a paas or d2o git remote). The token is stored in plain text. On Linux and macOS the CLI restricts the file to your user; on Windows it inherits whatever your user profile directory allows. Either way, treat the file like a password and do not commit or share it.

For scripts and CI, you can bypass the config file entirely: set PAAS_API_URL to the platform address and PAAS_API_TOKEN to a token. An environment-supplied token is never written to disk.

You can review every token issued to your account with paas auth tokens list and revoke one by ID with paas auth tokens revoke <uuid> — useful if a laptop goes missing. See Account, SSH Keys & API Tokens.

Log out

paas logout

This revokes the current host’s token on the server and removes it from your local config. If your token comes from the PAAS_API_TOKEN environment variable, paas logout refuses — unset the variable instead.

Next steps

• CLI Overview & Authentication — context flags, defaults, and --json output
• Command Reference — every command and flag
• Quickstart: Deploy Your First App — from zero to a running app
• Deploying with Git Push — push your code straight to the platform