# Start with your agent Follow the steps below to connect and explore without changing data. These instructions are also available as [plain Markdown](/start-with-agent/guide.md), with more official references in [llms.txt](/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](/docs/developer/scopedb-cli) has manual instructions. The commands below target the published preview release [v0.1.0-rc.3](https://github.com/scopedb/scopedb-cli/releases/tag/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__.tar.gz` for `darwin` or `linux`, or `scope_0.1.0-rc.3_windows_.zip` for Windows; `` 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](#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](/docs/guides/connect-to-scopedb) 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: ```bash 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](https://console.scopedb.cloud/?signup) 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: ```bash 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: ```bash 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: ```bash scope workspace use scope workspace show --format json ``` Replace `` 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](https://console.scopedb.cloud/). 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: ```bash 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: ```bash 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](/docs/reference/commands/statements/describe-table). Use the actual qualified names from the catalog: ```bash scope query --format json 'DESCRIBE TABLE ' ``` 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](/docs/reference/commands/stmt-query) and [query patterns](/docs/guides/query-events), 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](/docs/guides/ingest-events) or the [Console quickstart](/docs/guides/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](/docs/guides/connect-to-scopedb) 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.