# Connections and access
URL: https://openship.io/docs/cli/access.md

Authenticate, select an installation, manage tokens, and call HTTP endpoints.

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:

| Destination | Authentication | Start here |
| --- | --- | --- |
| Openship installed on this server | Automatic for the installation owner, using its protected local credential | `openship --local project list` |
| A remote self-hosted installation | Sign in once with a personal access token | `openship login --api-url https://ship.example.com --context production` |
| Openship Cloud | Sign in once with a Cloud personal access token | `openship login --cloud` |

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:

```bash
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

```bash
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

```bash
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.

```bash
openship logout --context production
```

See the [context](/docs/cli/reference/context), [login](/docs/cli/reference/login), and
[logout](/docs/cli/reference/logout) references for all options.

## Select an organization

```bash
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](/docs/cli/automation).

`access` also manages team workspaces, members, invitations and resource grants. See the
[access reference](/docs/cli/reference/access). Changes use the platform's existing permission checks.

## Store provider credentials

```bash
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:

```bash
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:

```bash
openship token revoke pat_123
```

See [token options](/docs/cli/reference/token) and [permission scopes](/docs/security/permissions).

## Call an HTTP endpoint

```bash
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](/docs/cli/reference/api) and the [HTTP reference](/docs/api).

## Native mode

Contexts describe remote HTTP connections. [Native mode](/docs/cli/native) uses an explicitly trusted
configuration file to select an owned installation and identity.