CLI overview
Install the openship CLI, log in with a token, understand connection contexts, and find every command at a glance.
The openship CLI does everything the dashboard does, from your terminal — run the platform, deploy a
project, tail logs, manage domains, and script it all in CI. It's the same binary you use to install and
run Openship itself.
Install it first
This page assumes the openship command is already on your PATH. If not, see
Installation — the short version is npm i -g openship (or
curl -fsSL https://get.openship.io | sh).
Every command supports --help, so when in doubt:
openship --help # top-level commands
openship deploy --help # flags for one command
openship domain add --help # flags for a subcommandLog in with a token
The CLI authenticates with a Personal Access Token (PAT) — a string that starts with opsh_pat_.
You create one in the dashboard, then hand it to openship login.
Get a token
In the dashboard, open Settings → Personal Access Tokens and create one. Copy it — the secret is shown
only once. (You can also mint tokens from the CLI with openship token create.)
Log in
Running openship login with no arguments opens that settings page and waits for you to paste the token.
For scripts and CI, pass it directly:
# Interactive — opens Settings and prompts for a paste
openship login
# Non-interactive — pass the token (great for CI)
openship login --token opsh_pat_xxxxxxxxxxxx
# Point at a remote instance instead of localhost
openship login --token opsh_pat_xxxxxxxxxxxx \
--api-url https://your-host --dashboard-url https://your-hostThe token is validated against the API and saved to ~/.openship/config.json.
openship login flag | Purpose | Default |
|---|---|---|
--token <token> | PAT (opsh_pat_…) for non-interactive login. | prompt |
--api-url <url> | API base URL to authenticate against. | http://localhost:4000 |
--dashboard-url <url> | Dashboard base URL (opened for the paste flow). | http://localhost:3001 |
--context <name> | Name of the context to store this login under. | default |
Signing out
openship logout removes the stored token from the active context.
Global flags
These work on every command.
| Flag | Purpose |
|---|---|
--json | Machine-readable JSON output on stdout (data only — no spinners or prose). Ideal for piping into jq or consuming from scripts. |
--version | Print the CLI version. |
--help | Show help for the CLI or any command / subcommand. |
# Human-readable
openship project list
# Same data as JSON for scripting
openship project list --json | jq '.[].name'Connection contexts
A context is a named connection: an API endpoint, a dashboard endpoint, and the token to use with them. They let one machine talk to more than one Openship instance — say a local install and a production server — and switch between them without re-authenticating each time.
Contexts live in ~/.openship/config.json. The one marked current is what every authenticated command
uses. openship login writes to the default context unless you pass --context <name>.
openship context # list contexts; the active one is starred
openship context use prod # switch the active context to "prod"Managing contexts
| Command | Purpose |
|---|---|
openship context (alias ctx) | Show all contexts; the active row is starred. |
openship context list (alias ls) | List configured contexts. |
openship context use <name> | Switch the active context. |
openship context add <name> | Create or update a context's endpoints/token. |
openship context rm <name> (alias remove) | Remove a context (you can't remove the active one). |
Flags for openship context add:
| Flag | Purpose |
|---|---|
--api-url <url> | API base URL. |
--dashboard-url <url> | Dashboard base URL. |
--token <token> | Personal access token to store. |
--use | Switch to this context immediately after adding it. |
add vs. login
openship context add only writes config — it doesn't check the token. Use openship login when you want
the token validated against the API before it's saved.
All commands
Twenty-four commands, grouped the same way the reference pages are. Each heading links to the page that
covers those commands in full; run openship <command> --help for the flag list of any one.
Running & updating — reference
Operate Openship itself: the local server, the CLI, and the desktop app.
| Command | Purpose |
|---|---|
openship up | Run Openship as a persistent service (starts on boot, auto-restarts). Add --foreground for a one-off attached run. |
openship stop | Stop the service started by openship up (won't restart or return on reboot). |
openship update | Update the CLI and bundled server to the latest release. |
openship install | Download and install the Openship desktop app for this OS. |
openship install cache | Manage the local download cache (list, verify, clean, path). |
openship open | Open the Openship dashboard in your browser. |
openship status | Show the active context's API health and deployment info. |
openship doctor | Diagnose the CLI setup (config, active context, runtime). |
Access & the raw API — reference
Who you are, which instance you're talking to, and an escape hatch to any route.
| Command | Purpose |
|---|---|
openship login | Authenticate with a Personal Access Token. |
openship logout | Remove the stored token from the active context. |
openship context (alias ctx) | Manage connection contexts — see above. |
openship token | Manage personal access tokens (list, create, revoke). |
openship api | Make an authenticated request to any Openship API route (like gh api). |
Deploying — reference
| Command | Purpose |
|---|---|
openship deploy | Trigger a deployment for the current project. |
openship deployment (alias deployments) | Manage deployments — list, inspect, redeploy, rollback. |
openship logs | View or stream a deployment's logs. |
Projects, services & domains — reference
| Command | Purpose |
|---|---|
openship init | Link the current directory to a project (writes .openship/project.json). |
openship project (alias projects) | Manage Openship projects. |
openship service (alias services) | Manage the services in a compose stack (a multi-service project). |
openship domain | Manage custom domains, DNS verification, and SSL certificates. |
Self-host infrastructure — reference
| Command | Purpose |
|---|---|
openship server | Manage self-hosted SSH servers. |
openship system | Instance settings, onboarding, migration, and data transfer. |
openship mail | Self-hosted mail server (iRedMail) setup and admin. |
openship backup | Manage backups — policies, runs, restores, and destinations. |
Where to next
Running & updating
up, stop, update, install — operate Openship itself.
Deploying
deploy, deployment, logs — the full deploy loop.
Projects, services & domains
init, project, service, and domain commands.
Access & the raw API
login, context, token, api — auth and any route.
Self-host infrastructure
server, system, mail, and backup for instances you run.