Start with your agent

Let your coding agent connect to ScopeDB, discover your tables, and help you choose what to query next. Reuse an existing connection, or let your agent guide the setup.

Paste this prompt into Codex, Claude Code, or another coding agent with terminal and web access.

Help me connect to ScopeDB and explore my data. Read this guide first:
https://www.scopedb.io/start-with-agent/guide.md

Reuse my existing connection if available, or guide me through setup. Verify the connection, discover available tables and their schemas, and help me choose what to query next.

Keep access read-only. Show actual results, and never ask for secrets in chat.

Get started

1. Connect your workspace. Your agent reuses your configured connection. New to ScopeDB? Create an account, then let your agent guide sign-in and workspace selection one step at a time.
2. Discover your data. Your agent runs a small query to check the connection, then discovers your tables and their fields.
3. Choose what to explore. Bring a question, or ask where to start. If your workspace is empty, your agent helps you choose the next step to bring in data.

Sign-in and workspace help

The CLI provides macOS, Linux, and Windows binaries. To reuse a personal CLI login, run your agent on the same computer and OS account. You sign in in your own terminal, and the CLI keeps the session in your OS keyring. This path does not need an API key. A remote sandbox needs its own configured endpoint and API key; it cannot reuse your local keyring session.

Configure secrets locally and keep them out of the conversation. New accounts may need approval before a workspace is available. Your agent pauses at the step that needs you, then resumes when you are ready.

The prompt asks your agent to query without changing data. It still uses your account access, so review the commands it proposes. If you prefer to work in the browser yourself, use the Console quickstart.

Agent workflow

Follow the steps below to connect and explore without changing data. These instructions are also available as plain Markdown, with more official references in llms.txt.

Work one step at a time

Prepare what you can, then hand back only the next action that requires the user. Do not present the entire setup checklist or future queries at the first pause. Resume from the reported state after the user completes that step; do not restart installation or login unnecessarily. Never claim that you created an account, signed in, or ran a query unless that action actually completed.

Check the CLI

Check scope version and scope --help. If the CLI is missing, download the official release archive for the user's OS and architecture and verify it against the published checksums before extraction. Install it in a user-writable directory and use its explicit path if it is not on PATH. Do not change shell profiles or install an unrelated package named scope. The installation guide has manual instructions.

The commands below target the published preview release v0.1.0-rc.3. Use that release for a reproducible first run. Do not silently replace an existing installation. For another version, inspect its help and release notes before proceeding; repository main can describe commands that have not been released.

For this pinned release, use direct asset downloads; release discovery through the GitHub API is unnecessary and can fail due to anonymous rate limits. The base URL is https://github.com/scopedb/scopedb-cli/releases/download/v0.1.0-rc.3/. Choose scope_0.1.0-rc.3_<os>_<arch>.tar.gz for darwin or linux, or scope_0.1.0-rc.3_windows_<arch>.zip for Windows; <arch> is arm64 or amd64. Download checksums.txt from the same base URL. Match the exact filename and SHA-256 digest, extract the executable, and verify scope version. Preserve the full executable path for the user's later sign-in command.

The published release uses scope login, scope status, and scope workspace show. It signs in with an email verification code. Do not substitute unreleased OAuth commands, a device-login flow, or an MCP endpoint.

Reuse an existing connection

First check whether SCOPEDB_ENDPOINT and SCOPEDB_API_KEY are set, without printing their values. If both are present, use them for this session and proceed to Verify the connection. Do not clear them or start a separate login. These variables take precedence over the saved CLI session.

If only one variable is present, pause and ask the user to complete the pair locally. Do not silently fall back to a different account. The published CLI accepts an API endpoint and API key as separate environment variables, not a single database connection URI. If the user has connection details, point them to Connect an application to configure those values in the agent's execution environment. Do not request secrets in chat or print an environment or credential file.

If neither variable is set, check the existing CLI session:

scope status --format json

A ready session with a selected workspace can proceed directly to the connection check. Do not repeat login or change the workspace unnecessarily. If the session is missing, expired, or has no ready workspace, follow the setup below. If several connections or workspaces are candidates, ask which one the user intends to use.

Sign in when needed

If there is no valid session, ask a new user to create an account first. Let them complete email verification and any required approval. If they already have an account, skip that step. Then ask the user to run this command in their own terminal, substituting the full path to the installed executable when needed:

scope login

The user enters their email address and verification code directly in the terminal. Never ask them to paste a verification code, session token, API key, or keyring contents into the agent conversation. The CLI stores the session in the OS keyring and exchanges it for a short-lived credential when it queries. An API key is not required. If the keyring is unavailable, stop and explain the problem; do not silently enable plaintext credential storage.

The agent runs with the user's account access. A read-only prompt is an instruction to the agent, not a permission boundary enforced by the CLI. Review the proposed commands before allowing them.

Account setup and resource creation remain with the user. A Console login alone does not log in the CLI. Wait for the user to finish sign-in before checking the session again.

With a valid CLI session, inspect the workspaces:

scope workspace list --format json

If several workspaces are available, ask the user which to use. Select by its actual ID, then inspect its state:

scope workspace use <workspace-id>
scope workspace show --format json

Replace <workspace-id> with the selected ID. Do not guess a workspace or change the selection unnecessarily. If the account is pending, no workspace exists, or provisioning is incomplete, explain the reported state and direct the user to ScopeDB Console. Continue only when provisioning.status is ready. If setup fails, report the error and the next step instead of repeatedly logging in or creating resources.

Verify the connection

Run a real query before reporting that the connection works:

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

Require a successful response with one row whose ready value is 1. Report which connection was used, the selected workspace when known, and the returned result without exposing credentials. A successful login or a zero exit code from scope doctor alone is not proof that queries work.

If the query fails, retain the error and request ID when available, omit credentials, and explain the blocker. Never substitute an expected result for an executed query.

Discover the available data

After the connection check, inspect a bounded catalog result:

scope query --format json 'FROM system.tables LIMIT 10'

Distinguish user tables from system metadata. Do not infer that a limited result is the complete catalog. If the result reaches its limit, narrow the catalog query to the relevant schema or table before describing what is available.

Inspect a small number of relevant tables with DESCRIBE TABLE. Use the actual qualified names from the catalog:

scope query --format json 'DESCRIBE TABLE <qualified-table-name>'

Replace the placeholder before running the command. Summarize the available tables and fields, using their returned names and types. Do not assume that a table contains events, has a timestamp column, or represents a particular business process. If the catalog is too broad to choose relevant tables, ask the user which area to explore.

Help choose the next query

Use the user's question when they have provided one. Otherwise, suggest one or two useful queries based on the schemas you actually inspected, explain what each would show, and ask which direction to take. Show the proposed ScopeQL; do not invent results for queries that have not run.

Before reading table rows, agree on the table and question, plus a time range when the table and task call for one. Reuse choices the user has already supplied. Use ScopeQL syntax and query patterns, keep row limits small, and return only the fields needed. A row limit bounds returned data; use appropriate filters to also constrain the work. For query files, submit one statement per file without a trailing semicolon.

If no user tables are available, report that the connection works but there is no user data to explore yet. Ask what data the user wants to bring in, and point to Ingest data or the Console quickstart. Do not manufacture sample data, choose a business scenario, create tables, or upload anything as part of this connection task.

When an agreed query succeeds, show the executed query and actual results, explain their limits, and suggest a next step. If it fails, report the error. Keep this workflow read-only: no table creation, ingestion, updates, or deletion.

Continue from the result

Keep using the verified connection for interactive work with your agent. For an application, SDK, scheduled ingestion job, or CI environment, follow Connect an application to create and store a separate workspace API key. SDKs do not inherit the CLI's login. Do not export your personal session as an application credential.

When you are ready to create a table or bring in data, agree on that separate task before making changes.