Connections and access

The CLI stores named contexts in ~/.openship/config.json. Each context contains an API URL, dashboard URL, personal access token, and optional fixed organization. One context is the saved default; openship --context production <command> selects another for one invocation.

Each command pins its connection settings for the entire invocation. Switching or updating a context in another terminal affects the next command, including while this command paginates, uploads or watches logs.

Choose where to connect

The same CLI works on your laptop and on an Openship server:

On a fresh machine, openship offers Cloud, an existing self-hosted installation, or installing Openship on this machine. Choosing a connection does not start a local server. openship login also offers a guided Cloud/self-hosted choice when no endpoint is saved.

On the installation server

Run the CLI as the OS account that installed Openship. Ordinary resource commands discover the installed service when there is no remote connection configured. Use --local to choose it explicitly, including after signing into Cloud or another server:

openship --local project list
openship --local server list
openship --local service list --project proj_123

The CLI reads the existing private installation credential, discovers the actual API port, and obtains a temporary administrator session over loopback. It uses the normal API permissions and signs out when the command finishes. It does not save that session in your contexts or enable anonymous API access. An interrupted process's session expires within 24 hours; the next local authentication cleans expired sessions.

Both CLI-managed bare and Docker Compose installations are supported. If you installed under another OS account or a custom OPENSHIP_HOME, run as that account or use the correct installation home with appropriate permissions. Merely installing the CLI or being another user on the same server does not grant access. Automatic local authentication requires a server release containing this feature. Older servers can still use the existing PAT login until upgraded.

--local ignores saved and ambient remote credentials. An explicit remote endpoint/context or token never falls back to local administrator privileges. Local setup, start, stop, and password recovery continue to manage this machine independently of the active remote context.

Log in to Cloud or a remote server

openship login \
  --api-url https://ship.example.com \
  --context production

The CLI opens the dashboard token page and prompts for a token without echoing it. For scripts, use --token-file /path/to/token or --token-file - to read stdin. Login validates the token before storing it and selects the context. Saved credentials are written atomically with owner-only permissions. For most self-hosted installations, the public dashboard URL is also the API URL. Pass --dashboard-url when they use different origins. Login reuses a saved connection's endpoints; retargeting its API also updates the default dashboard address. The installed service's remembered ports take precedence over the local defaults of API port 4000 and dashboard port 3001.

Switch contexts

openship context list
openship context use production
openship status
openship --context cloud project list
openship --local project list

context add stores endpoints and a token without validating them. Use login when you want validation. context rm removes an inactive context. logout clears a token while keeping its endpoints. Changing a context's API clears its previous token, organization and capability cache. Authenticate again for the new endpoint. If OPENSHIP_TOKEN is set, logout reports that environment authentication is still active; unset the variable to stop using it.

openship logout --context production

See the context, login, and logout references for all options.

Select an organization

openship access workspaces
openship login --cloud --organization org_123 --token-file /path/to/cloud-token
openship --organization org_123 --json project list
openship --organization org_123 init --project proj_123

--organization uses the SDK's fixed scope and requires a server that supports it. It never grants access the credential does not already have. Use the same organization option when deploying a link created with it. The native configuration selects its own organization.

OPENSHIP_API_URL, OPENSHIP_TOKEN, OPENSHIP_ORGANIZATION_ID, and OPENSHIP_CONTEXT can select an ephemeral connection for CI. They are not saved. An explicit --context selects that context's complete connection and ignores ambient connection variables. See automation.

access also manages team workspaces, members, invitations and resource grants. See the access reference. Changes use the platform's existing permission checks.

Store provider credentials

openship credential providers
openship credential create registry.json
openship credential list
openship credential verify credential_123

The JSON file contains provider, name, optional selector, and provider values. Provider discovery describes the required fields. Reads return masked secrets; verification failures exit nonzero.

Create a token

Choose explicit access for each token:

openship token create deploy-bot --grant project:proj_123:read,write
openship token create report-reader --read-only --expires 30 --full-access
openship token list

Pass either --grant or --full-access; omitting both is refused. A full-access token acts with your own permissions. Scoped credentials cannot mint unrestricted credentials.

Copy a new token's secret when it is created; later reads show only metadata. Revoke by token ID:

openship token revoke pat_123

See token options and permission scopes.

Call an HTTP endpoint

openship api /projects
openship api /domains --query projectId=proj_123

Paths are relative to /api. Use --method to select a method and --data for a JSON body; supplying data defaults the method to POST. Responses are printed, and non-success HTTP results exit nonzero. See raw API options and the HTTP reference.

Native mode

Contexts describe remote HTTP connections. Native mode uses an explicitly trusted configuration file to select an owned installation and identity.