Automate CLI commands | ScopeDB Docs

Run the installed scope executable in CI or other unattended environments. Use a workspace API key for data access; browser login is not required.

Configure access

For CI or other unattended commands, configure the workspace API address and an API key. Follow the application connection guide or create a key with the CLI 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, Catalog commands, scope auth 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

Capture results

Use --format json for machine-readable command results. Query output can also use jsonl or csv. Results go to stdout; prompts, warnings, progress, and errors go to stderr.

scope auth status --format json
scope query --format json 'SELECT 1 AS ready'

auth status reports the configured endpoint and credential_source without validating the API key. Use the query as a readiness check. scope doctor --format json supplies detailed diagnostics, but incomplete account setup is a warning rather than a failed check.

Shell redirection with > can truncate an existing file before a command runs. To preserve the last successful result, save to a temporary file in the same directory and replace the destination only after success. In a POSIX shell, with report.scopeql containing your query:

result_tmp=$(mktemp ./report.json.XXXXXX) || exit 1
if scope query -f report.scopeql --format json > "$result_tmp"; then
  mv -- "$result_tmp" report.json
else
  result_status=$?
  rm -f -- "$result_tmp"
  exit "$result_status"
fi

The replacement inherits the temporary file's restrictive permissions. Set any required access permissions explicitly in your job.

Handle exit codes

Code	Meaning
0	The command completed successfully. For `doctor`, inspect warnings and the individual checks too.
1	A general failure, including a failed diagnostic check or an output error.
2	Invalid arguments, flags, or input.
3	Authentication failed or the required login is missing.
4	A requested resource was not found.
5	A temporary failure or a request timeout.
130	The command was interrupted.

A nonzero exit code does not prove a write was rejected. Query timeouts attempt cancellation; Catalog writes never retry automatically. Check the reported statement ID or read the current resource before deciding whether to repeat a mutation.

Apply catalog changes

For reviewed changes, save and apply a Catalog plan. A saved plan does not prompt again and is tied to the connection and catalog version used to create it. Direct apply needs --yes; data-loss changes also require --allow-destructive.

Keep definition and plan files protected because they can contain storage credentials. When the connection or catalog changes, regenerate and review the plan before applying it.