ScopeDB CLI

Use the ScopeDB CLI to query a ScopeDB Cloud workspace from a terminal or script. The executable is scope. The CLI is in public preview, and current releases are release candidates whose commands may change before a stable release. See the ScopeDB CLI repository for the current release and complete command help.

Install

Download a release

The latest public preview release is v0.1.0-rc.3. Choose the archive for your platform:

Download the release's SHA-256 checksums and compare the digest for your archive before extracting it. On macOS, use shasum -a 256 <archive>; on Linux, use sha256sum <archive>; on Windows, use Get-FileHash <archive> -Algorithm SHA256 in PowerShell.

On macOS or Linux, extract the archive and put scope on your PATH. For example, from a directory containing only the downloaded ScopeDB CLI archive:

tar -xzf scope_*.tar.gz scope
mkdir -p "$HOME/.local/bin"
install -m 0755 scope "$HOME/.local/bin/scope"
export PATH="$HOME/.local/bin:$PATH"
scope version

Add the export PATH=... line to your shell profile to keep scope available in new terminals. On Windows, extract the ZIP, add the directory containing scope.exe to your PATH, then run scope version.

Official Homebrew, Scoop, and winget packages are not available yet. Use the release archives or Go source instead of an unverified package with a similar name.

Build from source

With Go 1.27 or later:

go install github.com/scopedb/scopedb-cli/cmd/scope@v0.1.0-rc.3

The binary is installed in Go's binary directory. Ensure that directory is on your PATH before running scope version.

Sign in and select a workspace

For interactive use, sign in with your ScopeDB Cloud account and run a test query:

scope login
scope status
scope query 'SELECT 1 AS ready'

scope login prompts for an email address and verification code, then stores the session in the operating system keyring. If your account is pending or has no workspace, scope status explains the next step. Use scope open to check approval status or create a workspace in the Console.

When more than one workspace is available, select one explicitly:

scope workspace list
scope workspace use <id-or-name>
scope status

Run queries

Pass a query inline or read it from a file. Results can be rendered as a table, JSON, JSON Lines, or CSV:

scope query 'FROM system.tables LIMIT 10'
scope query --file report.txt --format json
scope query 'FROM system.tables LIMIT 10' --format csv --output tables.csv

Run scope --help or scope query --help for all current options. For query syntax and examples, use the query reference.

Use the CLI in automation

For CI or another non-interactive environment, configure the data-plane API address and an API key instead of an interactive login. Follow Connect an application to obtain these values and store the key in your CI secret store:

export SCOPEDB_ENDPOINT="https://<endpoint>"
export SCOPEDB_API_KEY="<api-key>"

scope doctor
scope query --format json 'SELECT 1 AS ready'

Both environment variables are required and override the saved login for queries, status, and connection checks. Setting only one fails instead of falling back to your login. Workspace selection and API key management still use your login. Keep API keys out of source control and terminal logs.

To return to login-based queries:

unset SCOPEDB_ENDPOINT SCOPEDB_API_KEY

Prepare application credentials

With a CLI login and a selected workspace, show its endpoint and create an application key:

scope workspace show
scope api-key create my-app --expires-in 720h

The key is shown only once. Store it in your application's secret manager, then pass it and the workspace endpoint explicitly to your SDK. SDKs do not read the CLI's stored login. An existing API key cannot manage keys through the CLI.

Diagnose a connection

Use scope status to see the active authentication mode and scope doctor --format json for diagnostics. Incomplete account setup is a warning, so exit code 0 alone does not confirm query readiness. Use scope query 'SELECT 1 AS ready' as a readiness gate in scripts.

If a key is rejected, check that it belongs to the endpoint's workspace and has not expired or been revoked. If the workspace is provisioning, check scope status or the Console and retry when it is ready.