ScopeDB LogoDOCUMENTATION

ScopeQL CLI

Use the ScopeQL CLI to work with a ScopeDB workspace from a terminal, script, or CI job. This page documents the CLI; use the ScopeQL quickstart for a guided introduction and the Reference for exact language syntax.

Before you start

Copy the ScopeDB API address and create an API key from Connect in ScopeDB Console. If you have not done that yet, start with Connect an application.

1. Install the CLI

Download a prebuilt v0.6.0 binary from the ScopeQL v0.6.0 release.

To install v0.6.0 from crates.io, use its pinned Rust nightly toolchain:

rustup toolchain install nightly-2026-05-01
cargo +nightly-2026-05-01 install scopeql --version 0.6.0

2. Add a connection

Create a named connection with the interactive flow:

scopeql config set-connection development

Paste the ScopeDB API address when prompted, choose api_key, then paste the API key. The API key prompt does not echo the secret.

The first connection becomes the default. Manage named connections with the commands available in ScopeQL v0.6.0:

scopeql config get-connections
scopeql config get-connections development
scopeql config use-connection development
scopeql config delete-connection old-development

get-connections marks the default stored in the discovered local configuration file. use-connection updates that value. Environment configuration can still override the default at runtime for the shell, run, and load.

3. Run ScopeQL

Run a single statement and choose an output format:

scopeql run --format json "SELECT 1 AS ok"

Available output formats are table, json, csv, and jsonl. The json and csv formats require a single statement. Run a script containing one or more statements with jsonl, which can represent a sequence of results:

scopeql run --file workflow.scopeql --format jsonl

Start the interactive shell by running the CLI without a subcommand:

scopeql

Configuration file shape

The connection commands create or update a supported local configuration file. A configuration with two API-key connections has this shape:

default_connection = "development"

[connections.development]
endpoint = "https://<endpoint>"
auth = "api_key"
api_key = "<development-api-key>"

[connections.production]
endpoint = "https://<endpoint>"
auth = "api_key"
api_key = "<production-api-key>"

Protect this file because it contains API keys. To use an explicit configuration path:

  • shell: scopeql --config-file <file>;
  • statements: scopeql run --config-file <file> ...;
  • loads: scopeql load --config-file <file> ....

Environment configuration

Environment variables can provide or override the default connection. This is useful in CI, where the key should come from secret storage:

export SCOPEQL_CONFIG_DEFAULT_CONNECTION="default"
export SCOPEQL_CONFIG_CONNECTIONS_DEFAULT_ENDPOINT="$SCOPEDB_ENDPOINT"
export SCOPEQL_CONFIG_CONNECTIONS_DEFAULT_AUTH="api_key"
export SCOPEQL_CONFIG_CONNECTIONS_DEFAULT_API_KEY="$SCOPEDB_API_KEY"

The DEFAULT segment identifies a connection named default; it is not an API address or workspace identifier.

Load JSON data

Use load to send a local file through a ScopeQL transformation:

scopeql load \
  --file events.jsonl \
  --format json \
  --transform "SELECT NOW() AS time, \$0['service']::string AS service, \$0['name']::string AS name, \$0::object AS var INSERT INTO events"

For the flags and release notes that match these commands, see the ScopeQL v0.6.0 source and release.