Running & updating

Start, stop, update, and health-check the Openship server itself from the terminal — up, stop, update, install, open, status, and doctor.

These commands run and maintain Openship itself — the server that everything else talks to — rather than your deployed apps. Start the server, keep it up to date, and check that it's healthy.

Two different things called “install”

There are two ways to run Openship, and they don't overlap:

openship up runs the self-hosted server (API + dashboard) from the globally-installed CLI. This is what most self-hosters want. openship update keeps it current.
openship install downloads the desktop app (a .dmg / .AppImage / .zip) — a packaged, double-click version for a single machine. It's a separate artifact from the CLI.

The reporting commands — status, doctor, update, install, and install cache — also accept the global --json flag for machine-readable output:

openship status --json

Command summary

Command	Purpose
`openship` (no args)	Guided first-run setup: deploy Openship, create your admin, print the login URL.
`openship up`	Start the server as a persistent, auto-restarting service.
`openship stop`	Stop that service.
`openship update`	Update the CLI + bundled server to the latest release.
`openship install`	Download and install the Openship desktop app.
`openship install cache`	Inspect and clean the desktop-app download cache.
`openship open`	Open the dashboard in your browser.
`openship status`	Show the active context's API health and deployment info.
`openship doctor`	Diagnose the CLI setup (config, context, runtime).

Run openship with no arguments for the interactive first-run setup. It asks whether the instance should be private (this machine only) or public (reachable from other machines), your domain and whether an HTTPS reverse proxy is in front (for public), and your admin name, email, and password. It then deploys via the same pipeline as openship up, creates your admin account, and prints the URL to sign in. This is the recommended way to stand up a new instance.

openship

`openship up`

Starts Openship as a persistent service that starts on boot and auto-restarts if it crashes, then keeps running until you openship stop. The API is served at /api (default port 4000) and the dashboard on port 3001.

CLI instances always require login

Unlike the desktop app (which uses loopback zero-auth), an instance started from the CLI always requires an email + password login. Create the first admin with the openship guided setup above (or openship system upgrade-to-auth). Zero-auth is desktop-only.

# Start the service (API on :4000, dashboard on :3001)
openship up

# Run attached in this terminal instead (Ctrl-C to stop)
openship up --foreground

# Preview the service definition without installing it
openship up --dry-run

Flag	Purpose	Default
`--port <port>`	API port to listen on.	`4000`
`--data-dir <dir>`	Directory for the embedded database.	`~/.openship/data`
`--dashboard-port <port>`	Dashboard port.	`3001`
`--no-ui`	Run the API only — don't download or serve the dashboard.	—
`--ui-version <tag>`	Dashboard release tag to run.	this CLI's version
`-f`, `--foreground`	Run attached in this terminal instead of as a background service.	—
`--dry-run`	Print the service definition that would be installed, then exit.	—
`--public-url <url>`	Serve to the internet at this URL: binds the dashboard to all interfaces, proxies the API same-origin, and requires login.	—
`--trust-proxy`	Trust the `X-Real-IP` set by a reverse proxy in front (the proxy MUST overwrite it with the real client IP, e.g. `proxy_set_header X-Real-IP $remote_addr`) — enables per-client rate limiting.	—
`--managed-edge`	Install OpenResty + a free Let's Encrypt cert on this box and route `--public-url`'s domain to the dashboard — no separate reverse proxy needed.	—
`--acme-email <email>`	Contact email for the Let's Encrypt certificates (managed edge).	—

The dashboard is downloaded on first run

Unless you pass --no-ui, the dashboard bundle is lazy-downloaded from GitHub releases the first time you run openship up and pinned to match the CLI version. If it can't be fetched, the API keeps serving on its own — retry openship up, pass --no-ui, or use openship install for the desktop app.

Serving to the internet

--public-url https://ops.example.com makes the dashboard reachable from other machines while keeping the API bound to loopback (only the dashboard's same-origin proxy reaches it — nothing but the dashboard is exposed). Put an HTTPS reverse proxy (Caddy, nginx, Cloudflare) in front of the dashboard port and add --trust-proxy. The guided openship setup walks you through all of this.

`openship stop`

Stops the service started by openship up. Once stopped it will not auto-restart or come back on reboot. Takes no flags.

openship stop

`openship update`

Updates the globally-installed CLI — which bundles the self-hosted server — to the latest published release, then restarts the running service so you're immediately on the new version. It checks GitHub releases (not your Openship API) and re-installs the global package with your package manager.

# Update to the latest release
openship update

# Just report current vs. latest — install nothing
openship update --check

# Force a package manager
openship update --via npm

Flag	Purpose
`--check`	Only report the current + latest version; don't install.
`--via <manager>`	Package manager to update with: `bun` or `npm` (default: `bun` if present, else `npm`).

Automatic restart

openship update restarts the installed service for you after updating, so you land on the new version immediately. If you're running attached with openship up --foreground (no service installed), it can't restart you — relaunch it yourself.

`openship install`

Downloads the Openship desktop app for your OS and architecture (macOS .dmg, Linux .AppImage, or Windows .zip), verifies it against its published .sha256 checksum, installs it, and launches it. This is separate from the CLI/server — see the callout at the top of this page.

# Install the latest desktop release and launch it
openship install

# Pin a specific release, and don't open it after installing
openship install --version v1.2.3 --no-launch

Flag	Purpose
`--version <tag>`	Release tag to install (e.g. `v1.2.3`).
`--latest`	Install the latest release (this is the default).
`--force`	Re-download even if a verified copy is already cached.
`--no-verify`	Skip SHA-256 verification (only allowed when no checksum sidecar exists).
`--no-launch`	Install without launching the app.

Checksums are enforced by default

Downloads are verified against a published .sha256 sidecar and the install is fail-closed: if the sidecar is missing, Openship refuses to install unless you pass --no-verify. A checksum mismatch always aborts — the download may be corrupt or tampered with.

`openship install cache`

Manages ~/.openship/cache, where openship install stores downloaded release assets and their checksum sidecars. Runs entirely offline — no API calls. Call it with a subcommand:

Subcommand	Purpose
`path`	Print the cache directory path.
`list` (alias `ls`)	List cached release assets.
`verify [tag]`	Re-hash cached assets and compare to their `.sha256` sidecar (optionally one tag).
`clean [tag]`	Delete cached assets (one tag, or all if omitted).

openship install cache list
openship install cache verify v1.2.3
openship install cache clean          # remove everything

`openship open`

Opens the Openship dashboard in your default browser. For a local dashboard it first checks that the API is responding, and warns (without blocking) if it isn't yet.

# Open the active context's dashboard
openship open

# Open a specific page on the hosted cloud dashboard
openship open --cloud --path /settings

Flag	Purpose
`--cloud`	Open the hosted cloud dashboard (`app.openship.io`).
`--dashboard-url <url>`	Dashboard base URL to open.
`--context <name>`	Context whose dashboard URL to open.
`--path <path>`	Path to open on the dashboard (e.g. `/settings`).

`openship status`

Prints a snapshot of the active context's API: whether it's reachable, its health, and how it's configured (self-hosted vs. cloud, deploy mode, auth mode, team mode, and host/machine details when present). Exits non-zero if the API can't be reached.

openship status
openship status --json

Contexts and which one is active are managed with openship context; sign-in lives under the auth commands.

`openship doctor`

Runs preflight checks so you can confirm the CLI is set up before relying on it — handy in scripts, which can gate on its exit code (non-zero if any check fails). Takes no flags.

It checks:

Check	What it confirms
`config`	The CLI config file exists.
`context`	The active context has a token.
`api`	That context's API is reachable (`GET /api/health`).
`node`	The Node.js runtime version.
`bun`	The Bun runtime version (optional).

openship doctor
openship doctor --json

Fixing failed checks

If context or api don't pass, you usually just need to sign in or point at a running server — see the auth commands and openship up above.