Connect the CLI

After installing the CLI, sign in with your ScopeDB Cloud account for terminal work. For CI, use the automation setup 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:

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. Neither login flow requires an interactive terminal.

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

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.

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:

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.

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. 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:

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.

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