Runsite CLI

runsite is the command-line version of the dashboard. It talks to the same Public API, signs in with an API key, and behaves the same on your laptop as it does in a CI job.

runsite deploy my-api
runsite logs my-api --tail 200
runsite env set my-api LOG_LEVEL=debug

Install

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/runsite-platform/runsite-cli/main/install/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/runsite-platform/runsite-cli/main/install/install.ps1 | iex

The installer picks the build for your operating system and CPU, checks it against SHA256SUMS.txt from the release, and puts the binary in ~/.local/bin/runsite (%LOCALAPPDATA%\runsite\bin on Windows). Builds exist for Linux (x86_64 and arm64), macOS (Intel and Apple silicon) and Windows.

Two variables change what it does: RUNSITE_VERSION=v0.1.0 pins a version, and RUNSITE_INSTALL_DIR chooses where the binary lands.

Check it worked:

runsite --version

Log in

runsite login                       # email and password
runsite login --token ak_live_...   # an API key from the dashboard
runsite whoami                      # who am I signed in as?

runsite login creates an API key for this machine and saves it in ~/.config/runsite/config.toml.

If you signed up with Google or GitHub you have no password to type. Create a key in the dashboard under Settings → API keys and pass it with --token.

runsite logout deletes the local copy of the key. The key itself keeps working until you revoke it in the dashboard, so revoke it there if a laptop is lost.

Note

The scope you give the key decides what the CLI can do. read can look but not touch; write can deploy, start, stop and change environment variables; admin can also delete. See API keys.

Services

runsite service list                # services in the current project
runsite service list --all          # services in every project
runsite service status my-api
runsite service start my-api
runsite service stop my-api
runsite service restart my-api

The service name is optional. If you have only one service, or one service in the project you picked with runsite project use, the CLI works out which one you mean. A UUID works anywhere a name does.

Start, restart and deploy do different things:

Command	What happens
runsite service start	Runs the image that was already built
runsite service restart	Restarts the running container, no rebuild
runsite deploy	Builds the current commit and releases it

Deploy and read logs

runsite deploy my-api               # build and release the current commit
runsite logs my-api                 # last 100 lines
runsite logs my-api --tail 200

runsite deploy queues the build and returns. Watch the build itself in the dashboard, or check on it later with runsite service status.

Environment variables

runsite env list my-api
runsite env set my-api DATABASE_URL=postgres://... LOG_LEVEL=debug
runsite env delete my-api LOG_LEVEL

Names must be uppercase and start with a letter (^[A-Z][A-Z0-9_]*$). Setting a name that already exists overwrites it. A change reaches the container on the next deploy or restart, not immediately.

Projects and profiles

runsite project list
runsite project use my-project      # look up names inside this project only

runsite context show                # active profile, API URL, project, user
runsite context set-url https://api.runsite.app

Profiles keep separate accounts or environments apart. Each one has its own key, project and API URL:

runsite --profile staging login
runsite --profile staging service list

Set RUNSITE_PROFILE=staging instead of typing --profile every time.

In CI

Put an API key in RUNSITE_API_TOKEN and skip runsite login entirely:

- name: Deploy
  env:
    RUNSITE_API_TOKEN: ${{ secrets.RUNSITE_API_TOKEN }}
  run: |
    curl -fsSL https://raw.githubusercontent.com/runsite-platform/runsite-cli/main/install/install.sh | sh
    ~/.local/bin/runsite deploy my-api

Give the CI key the write scope. It never needs admin.

JSON output

Every command that prints something takes --output json, so you can pipe it:

runsite service list --output json | jq '.[] | select(.status != "running") | .name'

Shell completions

runsite completions bash > /etc/bash_completion.d/runsite
runsite completions zsh  > ~/.zfunc/_runsite
runsite completions fish > ~/.config/fish/completions/runsite.fish

Not available yet

runsite shell, runsite run and runsite deploy --watch need a live WebSocket connection, which the Public API does not yet open to API keys. Until it does, use the dashboard for an interactive shell and for streaming build logs.

Common problems

What you see	What to do
401 Invalid access token	The key was revoked, rotated or expired. Run runsite login again, or pass a fresh --token
403 on deploy or env set	The key is read-only. Create one with the write scope
”service not found”	The name belongs to another project. Run runsite project use, or add --all to service list
runsite: command not found	~/.local/bin is not on your PATH. Add it to your shell profile
Your change did not take effect	Environment variables apply on the next deploy or restart

Questions people ask

Do I need a password to use the CLI? No. If you signed in with Google or GitHub, create an API key in the dashboard and use runsite login --token ak_live_....

Where is the API key stored? In ~/.config/runsite/config.toml on Linux and macOS. runsite logout removes it locally; revoke it in the dashboard to kill it everywhere.

Can one machine hold two accounts? Yes, that is what profiles are for. runsite --profile staging login keeps a second key, project and API URL side by side with your default.

Does runsite deploy wait for the build? No. It queues the deployment and returns. Follow the build in the dashboard, or let an AI assistant watch it through the MCP server.

See also

• MCP server — the same actions, driven by an AI assistant
• API keys — create, scope, rotate and revoke keys
• Public API — what the CLI calls underneath
• runsite-cli on GitHub — source and releases