CLI

launchroom is a command line tool for your laptop and your CI. It talks to your dashboard's API with a token that is bound to one team and expires. It never talks to your servers directly.

InstallCopy Anchor Link

curl -fsSL https://github.com/vantezzen/launchroom/releases/latest/download/cli.sh | sh

The script picks the right build for Linux or macOS (amd64 or arm64), verifies its checksum and, if cosign is installed, its signature, then installs launchroom into ~/.local/bin. Options:

Pass them after sh -s --, for example … | sh -s -- --dir /usr/local/bin. On Windows, download the .zip from the GitHub release.

Sign inCopy Anchor Link

launchroom login --url https://launchroom.example.com

Sign-in uses a pairing code:

1. The CLI shows a short code (like WBXH-NDSZ) and opens your dashboard in the browser.
2. The dashboard asks Sign in to the launchroom CLI? with the same code, the machine's name and where the request came from. Check that the codes match.
3. Choose the team, the permissions and how long the session lasts (90 days by default), then Approve. Your password is confirmed first if you haven't entered it recently.
4. The CLI receives its token and stores it in your system keychain.

The request expires after 10 minutes. Deny ends it.

The token lives in the macOS Keychain, the Secret Service on Linux or the Windows Credential Manager. Without a keychain (headless Linux, containers) it falls back to ~/.config/launchroom/credentials.json with mode 0600. Set LAUNCHROOM_CREDENTIALS_STORE=file to use the file directly.

launchroom whoami shows the user, team, abilities and expiry. launchroom logout forgets the token on this machine. Revoke it under Settings → API tokens to end it everywhere.

Link a directoryCopy Anchor Link

launchroom link

Pick a project, environment and (optionally) service. The CLI writes .launchroom/project.json. It contains IDs only and is safe to commit. Without a terminal, pass --project, --environment and --service. It defaults to production.

Every command also accepts --project, --environment and --service to override the link for one call, so you can work with several services from one directory.

CommandsCopy Anchor Link

Global optionsCopy Anchor Link

DeployCopy Anchor Link

launchroom deploy                       # latest commit of the tracked branch
launchroom deploy --ref main            # the head of a branch
launchroom deploy --sha 3b7d5e1…        # one commit (full 40-character SHA)
launchroom deploy --redeploy            # the current commit again
launchroom deploy --staged --message "Raise memory"   # apply staged changes

deploy follows the build until the deployment is live or failed and exits with code 10 if it failed. Add --detach to return at once. --ref and --sha can be combined. The other modes can't. --message only applies with --staged.

deploy builds from your repository, not from local files. Push first, then deploy.

LogsCopy Anchor Link

launchroom logs                         # the last hour of the linked environment
launchroom logs --service api -f        # follow one service live
launchroom logs --since 24h --source build
launchroom logs --deployment dpl_…      # one deployment's log

With --json, every line is one JSON object (JSON Lines).

VariablesCopy Anchor Link

launchroom env ls
launchroom env set LOG_LEVEL=debug FEATURE_X=on
launchroom env set STRIPE_KEY=sk_live_… --secret
launchroom env rm FEATURE_X
launchroom deploy --staged

env set and env rm stage changes in the linked environment. deploy --staged applies them, the same as Review & deploy in the dashboard.

Pull into .envCopy Anchor Link

launchroom env pull            # writes .env
launchroom env pull .env.local

The file contains the resolved variables of the last deployed revision, with references already filled in, written with mode 0600. The CLI asks before overwriting (--yes skips the question) and warns if the file isn't git-ignored. --no-secrets leaves secret values out. Secrets need a token with secrets:read and a role that may reveal them.

References to other services resolve to their private names (for example postgres:5432), which only work inside the environment.

Run with variablesCopy Anchor Link

launchroom run -- npm run dev
launchroom run --no-secrets -- php artisan migrate --pretend

run starts the command with the variables added on top of your local environment (launchroom's values win), passes signals through and exits with the command's exit code. Nothing is written to disk.

Config as codeCopy Anchor Link

launchroom config pull             # write the environment as launchroom.json
launchroom config pull --revision 12
launchroom config validate         # check the file against the dashboard's rules
launchroom config diff             # list the changes it would stage

validate prints every problem as file:line:column with the line and a caret, and exits with code 6 if the file is invalid. See Config as code.

Import and exportCopy Anchor Link

launchroom db import postgres umami.dump               # into an empty database
launchroom db import postgres umami.dump --replace     # replace what's there (asks for the name)
launchroom db export postgres -o shop.dump             # a fresh dump
launchroom db export postgres --backup 4a1f0c2e        # a decrypted backup
launchroom volume export web /app/uploads              # a volume as .tar.gz (or vol_…)

These need a token with the data:transfer ability and the Owner or Admin role. See Import and export.

db import uploads in parts with a progress line on stderr. If it stops, run the same command again: the upload continues where it stopped (the CLI remembers it per file in ~/.config/launchroom/uploads.json). It then follows the import and prints what was imported, with any adjustments as warnings.

db export and volume export wait until the file is ready, then download it to NAME.part and rename it once the size matches. Without -o the file gets the name the dashboard suggests in the current directory. -o - writes to stdout. An existing file is only overwritten with --force.

In CICopy Anchor Link

Create a token in Settings → API tokens with only the abilities the job needs (usually deploy), and set two environment variables. They replace login and the dashboard address of the link:

- name: Deploy
  env:
    LAUNCHROOM_URL: https://launchroom.example.com
    LAUNCHROOM_TOKEN: ${{ secrets.LAUNCHROOM_TOKEN }}
  run: |
    curl -fsSL https://github.com/vantezzen/launchroom/releases/latest/download/cli.sh | sh
    ~/.local/bin/launchroom config validate
    ~/.local/bin/launchroom deploy --project shop --environment production --service web --sha "$GITHUB_SHA"

Without a terminal, prompts never appear. Anything ambiguous exits with code 2 instead. The CLI never follows redirects, so the token can't leak to another host. It retries safe requests once after a network error.

Exit codesCopy Anchor Link