CLI

The ScopeDocs CLI is a stateless HTTP client over the same /api/v1/* surface used by the web UI and MCP server. Three core verbs — ask, why, impact — plus an interactive TUI when invoked with no arguments.

Note:

Pin a specific release with SCOPEDOCS_INSTALL_VERSION=0.1.4. Opt into pre-releases with SCOPEDOCS_INCLUDE_PRE=1 (PowerShell: $env:SCOPEDOCS_INCLUDE_PRE=1).

Install

The shell installer detects Python 3.11+, installs pipx if missing, and drops scopedocs on your PATH inside an isolated venv:

curl -fsSL https://api.scopedocs.ai/install.sh | sh

After install, open a new shell so ~/.local/bin is on PATH, then verify:

scopedocs --version

Requirements: Python 3.11+. Tested on macOS, Linux, WSL2, and native Windows (PowerShell 5.1+ in Windows Terminal).

Log in

Create an API key from Settings → Organization → API keys. The docs:read, graph:read, and chat:write scopes cover all three core commands.

Paste the key into:

scopedocs auth login

Credentials are saved to ~/.config/scopedocs/config.toml with 0600 perms. To switch, use scopedocs auth logout then log in again, or set SCOPEDOCS_API_KEY in your shell.

Core commands

scopedocs ask "why is the refund flow flaky right now?"

• scopedocs ask "<question>" — free-form Q&A across GitHub, Linear, Slack, Notion, and indexed code. Streams tokens by default.
• scopedocs why <target> — surfaces the governing decisions (ADRs, owners, rationale) behind a service, file, or symbol. Not "what does this code do" — that's your coding agent's job.
• scopedocs impact <target> — maps blast radius: direct consumers, data pipelines, dashboards, recent incidents, live workarounds.

Rate the most recent answer to feed the DSPy training loop:

scopedocs feedback --good "matched the right ADR"
scopedocs feedback --bad  "missed the live workaround for INC-204"

Check who you are logged in as

scopedocs auth status hits /api/v1/me and reports the active CLI version, key name and prefix, organization, granted scopes, rate-limit budget, and last-used timestamp. Use it as a quick whoami probe in CI to verify a key still works.

scopedocs auth status
scopedocs auth status --json     # machine-readable for agents and CI

Exits 0 when authenticated, 1 when the key is invalid or revoked. When the backend is unreachable, prints a warning but still exits 0 so you can distinguish "keys are bad" from "network is down."

Check for updates

scopedocs update queries PyPI for the latest release, detects how this CLI was installed (pipx / pip user / venv), and prints the right upgrade command. Pass --apply to run it automatically — only safe for pipx installs; for pip-user or venv installs it surfaces the command but won't run it.

scopedocs update                      # check + print upgrade command
scopedocs update --apply              # auto-upgrade (pipx only)
scopedocs update --json               # machine-readable
scopedocs update --channel stable     # ignore pre-releases

The default --channel auto mirrors the channel of your installed version: stable on 0.x.y, pre-release on 0.x.ybN/0.x.yaN. Set --channel pre to track betas, --channel stable to ignore them.

JSON output for agents

Every command supports --json. Schemas are stable and pipeable:

scopedocs ask "who owns billing?" --json | jq '.sources[].url'

scopedocs why payment-service --json | jq '.decisions[] | {id, title, owner}'

scopedocs impact api-gateway --json | jq '.recent_incidents[] | select(.workaround_status == "live")'

The ask shape:

{
"command": "ask",
"question": "string",
"summary": "string with [1] [2] citations",
"evidence": [
  {"source": "...", "system": "github|slack|linear|notion|...", "signal": "...", "ref": "1"}
],
"recommendation": "string",
"sources": [
  {"ref": "1", "url": "...", "type": "pr|slack_thread|notion_page|adr|incident", "title": "..."}
],
"tokens_used": 0,
"tokens_budget": 3000
}

Interactive TUI

Run scopedocs with no arguments to open a chat-style Textual app. Slash commands: /ask, /why, /impact, /copy (Ctrl+Y), /clear (Ctrl+L), /help. Bare input becomes /ask. ↑/↓ walks prompt history.

Copy uses OSC 52 — works over SSH and tmux on iTerm2, Kitty, Alacritty, WezTerm, Ghostty, and Windows Terminal.

Configuration

Precedence (high → low): CLI flag → env var → user config → repo config → built-in default.

User config — path varies by platform:

• POSIX: $XDG_CONFIG_HOME/scopedocs/config.toml, default ~/.config/scopedocs/config.toml
• Windows: %APPDATA%\scopedocs\config.toml

Same TOML on every platform:

[default]
workspace = "ws_xxx"
api_key   = "sk-sd_xxx"
budget    = 3000

[backend]
url = "https://api.scopedocs.ai"   # default — override only for self-hosted / staging

Repo override: commit .scopedocs/config.toml at the repo root for team-wide defaults (workspace, repo alias, privacy denylist).

Common env vars: SCOPEDOCS_API_KEY, SCOPEDOCS_WORKSPACE, SCOPEDOCS_BACKEND_URL, SCOPEDOCS_BUDGET, SCOPEDOCS_NO_TRACE.

Privacy: --no-context disables the local Query Enrichment Layer (which attaches branch, dirty files, and IDE selection to chat requests). --no-trace disables the local invocation log (POSIX: ~/.local/state/scopedocs/traces.jsonl; Windows: %LOCALAPPDATA%\scopedocs\traces.jsonl).

Exit codes

All error paths print a clean one-line message — no Python tracebacks reach the user. Useful for shell scripts and CI.

Uninstall

pipx uninstall scopedocs-cli
rm -rf ~/.config/scopedocs ~/.local/state/scopedocs

If installed via pip --user, replace the first line with python3 -m pip uninstall scopedocs-cli.