Access & the raw API

These commands are how the CLI knows which Openship it's talking to and who you are — plus an escape hatch (openship api) for reaching any route that doesn't have its own command yet.

openship login

Authenticate against an instance and save the token into a context. Run with no --token and it opens the dashboard's Settings page — where Personal Access Tokens live — and waits for you to paste one; pass --token to log in non-interactively (CI, scripts). The token is validated against the API before it's stored, and it must start with opsh_pat_.

# Interactive — opens the dashboard, prompts for a pasted token
openship login

# Non-interactive — against a remote self-hosted instance, stored as a named context
openship login \
  --token opsh_pat_xxxxxxxx \
  --api-url https://openship.example.com \
  --dashboard-url https://openship.example.com \
  --context prod

openship logout

Remove the stored token from a context. The endpoints stay saved, so a later login just re-adds the token.

openship logout                 # active context
openship logout --context prod  # a specific one

openship context

Manage the named connections in ~/.openship/config.json. This is pure local config editing — no API calls. Use it to keep several instances side by side (local, staging, production) and switch between them. Alias: openship ctx. Running it bare prints the active context and the full list (the active row is starred).

openship context           # show active + list all
openship context use prod  # switch the active context

The list shows one row per context: current (* marks the active one), name, apiUrl, dashboardUrl, and auth (token when a token is stored, - when not).

context add

Register an instance without logging in interactively. add only writes config — use login when you want the token checked against the API first.

openship context add staging \
  --api-url https://staging.example.com \
  --dashboard-url https://staging.example.com \
  --token opsh_pat_xxxxxxxx \
  --use

openship token

Create and manage the personal access tokens that authenticate the CLI and the API. Tokens are self-scoped — every call operates on your own tokens. In the dashboard these live under Settings → Personal Access Tokens.

token create

# A full-access, non-expiring token
openship token create "laptop"

# A read-only token that expires in 30 days
openship token create "ci-reader" --read-only --expires 30

# Scope a token to one project with specific permissions (repeatable)
openship token create "deploy-bot" --grant project:abc123:read,write

The list table shows: id, name, prefix, readOnly, scoped, expires, lastUsed, and revoked. Pass a token's id (they look like pat_…) to revoke:

openship token list
openship token revoke pat_abc123

openship api

The escape hatch. Make an authenticated request to any API route using the active context's token — much like gh api. This is what keeps the CLI small: anything without a dedicated command (audit log, one-off reads, routes added after your CLI version) is still reachable here.

The <path> argument is relative to /api, so openship api /projects calls <your-api-url>/api/projects. The method defaults to GET, or POST when you pass --data.

# GET a collection
openship api /projects

# GET a single resource
openship api /deployments/dep_abc123

# POST with a JSON body (method defaults to POST when --data is given)
openship api /domains -d '{"projectId":"proj_123","hostname":"app.example.com"}'

# DELETE with an explicit method
openship api /tokens/pat_abc123 -X DELETE

# Add query parameters (repeatable)
openship api /domains -q projectId=proj_123

The response body is printed to stdout — pretty-printed when it's JSON, raw otherwise. On a non-2xx response the body is still printed and the command exits non-zero, so you can pipe it into jq and still detect failures in scripts.