# Connect the CLI

[Read this page in HTML](https://www.scopedb.io/docs/guides/scopedb-cli/connect)

After [installing the CLI](https://www.scopedb.io/docs/guides/scopedb-cli.md), sign in with your ScopeDB Cloud account for terminal work. For CI, use the [automation setup](https://www.scopedb.io/docs/guides/scopedb-cli/automation.md) with a workspace endpoint and API key.

## Sign in and select a workspace

Sign in with your ScopeDB Cloud account and run a test query:

```bash
scope auth login
scope auth status
scope doctor
scope query 'SELECT 1 AS ready'
```

`scope auth login` opens your browser to approve a CLI login in ScopeDB Console and waits for a callback on the same device. If the browser does not open, open the printed URL on that device. `--no-browser` skips automatic browser opening while keeping the same callback flow.

For SSH, containers, or approval from another device, use device authorization:

```bash
scope auth login --use-device-code --no-browser
```

Keep the command running, open the printed verification link in a browser, and approve the request using the displayed code when asked. `--use-device-code` selects this flow; `--no-browser` independently skips launching a browser on the host. Neither login flow requires an interactive terminal.

Login keeps a valid existing workspace selection or selects the first available workspace by ID, excluding workspaces scheduled for deletion. It prints the selected name and ID. Pass `--workspace <id-or-name>` at login to choose explicitly, or switch later:

```bash
scope workspace list
scope workspace use '<id-or-name>'
scope workspace get
scope auth status
```

Replace `<id-or-name>` with a workspace returned by `list`. You can select workspaces you own or that have been shared with you. The selection is local to this CLI login; it does not change your Console workspace or another machine's selection. If your account is pending or has no workspace, follow the next step shown by `scope auth status`. Use `scope console --open` to open the Console for account or workspace setup; `scope console` alone prints its URL.

To open a particular Console page, use `scope console query --open`. The available shortcuts are `home`, `query`, `data`, `keys`, and `connect`.

### Credential storage and logout

Login prefers the OS keyring. If saving there fails, the CLI warns on stderr and saves the credentials unencrypted in a file with `0600` permissions on Unix. `scope auth status` reports the actual storage source and the plaintext file path when applicable.

`--insecure-storage` chooses plaintext for that login only. It does not change a persistent storage preference. Later commands find the existing credentials, and automatic renewal keeps the same storage location. For CI and servers, you can instead use an [endpoint and API key](https://www.scopedb.io/docs/guides/scopedb-cli/automation.md).

Run `scope auth logout` to revoke the login and clear its local credentials. To return to keyring storage after using plaintext, restore keyring access, log out, and log in again without `--insecure-storage`. If logout reports a keyring cleanup failure, restore access to the OS keyring and rerun `scope auth logout` to finish cleanup. Unset any environment credentials before logging out; logout does not revoke application API keys.

### Linux servers and containers

Linux keyring storage needs a working D-Bus session and a Secret Service provider, such as GNOME Keyring, with an accessible login collection. SSH sessions and containers may lack them. For unattended use, configure an [endpoint and API key](https://www.scopedb.io/docs/guides/scopedb-cli/automation.md). For a personal login approved from another device, run `scope auth login --use-device-code --no-browser`; authorization and credential storage are independent.

If saving a new login to the keyring fails, the warning identifies the plaintext fallback. Add `--insecure-storage` to choose plaintext directly for that login. On Linux, `credentials.json` and `config.toml` use `$XDG_CONFIG_HOME/scopedb`, or `~/.config/scopedb` when it is unset; `SCOPEDB_CONFIG_DIR` overrides their directory. Check `scope auth status` for the actual credential location.

## Diagnose a connection

Use `scope auth status` to see the credential source, account, and connection target. Its JSON output uses `credential_source`; with environment credentials it shows the configured endpoint without validating the API key. Use `scope workspace get --format json` for the login workspace's `connection.endpoint` and `provisioning.status`.

`scope doctor --format json` runs a read-only query when a workspace is ready. A passing `data plane` check confirms query access; incomplete account setup is a warning, so exit code 0 alone does not. Use `scope query 'SELECT 1 AS ready'` as a readiness gate in scripts. Doctor limits each remote check to five seconds by default; use `scope doctor --timeout 15s` for a slower connection or `--timeout 0` to disable that limit.

For machine-readable diagnostics:

```bash
scope doctor --format json --timeout 15s
```

The report contains `ok` and `checks`. Failed checks exit with code 1; inspect the check results to distinguish a failed connection from incomplete account setup.

| Symptom                             | Next step                                                                                                      |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Only one connection variable is set | Set both `SCOPEDB_ENDPOINT` and `SCOPEDB_API_KEY`, or unset both to use your login.                            |
| No workspace is selected            | Run `scope workspace list`, then `scope workspace use <id-or-name>`.                                           |
| The workspace is provisioning       | Check `scope workspace get` or the Console and retry when it is ready.                                         |
| The API key is rejected             | Check that the endpoint and key belong to the same workspace and that the key has not expired or been revoked. |
| The OS keyring is unavailable       | Follow the [Linux server setup](#linux-servers-and-containers) for credential storage or use an API key.       |
| A remote check times out            | Check connectivity, then increase `doctor --timeout` if the per-check limit is too short.                      |

Include a reported request ID when asking for support. Keep API keys and session credentials out of diagnostic reports.

## Related contents

* [Install the CLI](https://www.scopedb.io/docs/guides/scopedb-cli.md)

* [Query data with the CLI](https://www.scopedb.io/docs/guides/scopedb-cli/query.md)

* [API keys with the CLI](https://www.scopedb.io/docs/guides/scopedb-cli/api-keys.md)

* [Automation](https://www.scopedb.io/docs/guides/scopedb-cli/automation.md)