> For the complete documentation index, see [llms.txt](https://docs.screendesk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.screendesk.io/debug-with-ai/cli.md). # CLI The Screendesk CLI, `sdesk`, brings customer-reported debugging evidence into your terminal, scripts, CI jobs, and coding-agent workflows. Give it a Screendesk recording or bug report URL to retrieve structured report details, console logs, network requests, user events, metadata, transcripts, screenshots, and video frames. Use the same commands manually while debugging or return compact JSON for a script or coding agent. Use the CLI when you want explicit, repeatable commands that can be inspected, composed, rerun, and automated. {% hint style="success" %} **Fastest path:** install `sdesk`, run `sdesk auth login`, then inspect a report URL. {% endhint %} {% hint style="info" %} The CLI calls the Screendesk Developer API directly. It does not wrap MCP, but it uses the same workspace permissions, redaction rules, and report services. {% endhint %} {% stepper %} {% step %} #### Install the CLI Run the install command in [Install](#install). {% endstep %} {% step %} #### Authenticate Use browser OAuth for interactive work, or a personal access token for CI. {% endstep %} {% step %} #### Load a report Run `sdesk get report --json`. {% endstep %} {% endstepper %} {% hint style="info" %} Prefer an interactive investigation inside an AI client? Use [Screendesk MCP](/debug-with-ai/mcp.md). {% endhint %} ### Why use the CLI The CLI closes the gap between a customer report and the repository where you will fix it. It is useful for: * **Terminal-first debugging** — inspect a report without switching between dashboards and developer tools; * **Coding agents** — give agents stable commands and machine-readable JSON instead of copied prose or screenshots; * **Focused evidence retrieval** — request only errors, `5xx` responses, a time range, a host, or another relevant slice of a large report; * **Cross-report investigation** — search reports, find related failures, compare environments, and summarize recurring errors; * **Repeatable triage** — rerun the same query during an incident or across a release window; * **Safe report updates** — add comments or update bounded metadata with explicit confirmation and retry-safe idempotency keys. ### CLI or MCP? | Choose | Best for | | ---------------------------- | ------------------------------------------------------------------------------------------ | | **Screendesk CLI (`sdesk`)** | Shell workflows, scripts, CI, reproducible queries, and command-oriented coding agents | | **Screendesk MCP** | Conversational investigation in Claude Code, Codex, Cursor, VS Code, and other MCP clients | Both use workspace-scoped credentials, preserve Screendesk permissions, and apply the same redaction rules. Many teams use MCP for exploration and the CLI for repeatable or automated follow-up. ### Install ```bash curl -fsSL https://app.screendesk.io/cli/install | sh ``` The installer: * detects macOS or Linux; * supports `amd64` and `arm64`; * downloads the latest public release from the official `screendesk/cli-releases` repository; * verifies its SHA-256 checksum; * installs `sdesk` to `~/.local/bin` by default. Verify the installation: ```bash sdesk version ``` {% hint style="warning" %} If your shell cannot find `sdesk`, add `~/.local/bin` to your `PATH` and open a new terminal. {% endhint %} ### Authenticate {% tabs %} {% tab title="OAuth" %} Browser OAuth is recommended for interactive use: ```bash sdesk auth login ``` Your browser opens so you can select a workspace and authorize read access. Request read-write access only when comments or report updates are needed: ```bash sdesk auth login --write ``` {% endtab %} {% tab title="Personal Access Token" %} Create a token from **Personal Settings → MCP Access** and enable **Screendesk CLI**. Then run: ```bash sdesk auth login --token ``` Paste the token when prompted. The token is read from standard input instead of a process argument. Use a PAT for headless environments, CI, WSL, or systems where browser OAuth is unavailable. {% endtab %} {% tab title="Environment Variable" %} For one process, provide a CLI-enabled token through `SCREENDESK_TOKEN`: ```bash SCREENDESK_TOKEN="$MY_SECURE_TOKEN" sdesk auth status --json ``` This overrides stored credentials for that process. {% endtab %} {% endtabs %} Check the active workspace: ```bash sdesk auth status --json ``` Run diagnostics: ```bash sdesk doctor --json ``` ### Install the coding-agent skill The CLI includes a Screendesk skill that teaches Codex how to inspect reports, load evidence selectively, use structured JSON, and confirm writes. ```bash sdesk skills install ``` Inspect the installed skill: ```bash sdesk skills path sdesk skills source ``` {% hint style="success" %} After installing the skill, give Codex a Screendesk URL and ask it to investigate. The skill guides the agent through report resolution, evidence retrieval, analysis, and safe writes. {% endhint %} ### A practical debugging workflow #### 1. Resolve the report Start with the Screendesk URL from a support ticket, issue, or team message: ```bash sdesk get report https://app.screendesk.io/recordings/REPORT_UUID --json ``` You can use either a full Screendesk URL or a report UUID. The response includes the report details, comments, linked issues, labels, assignees, and a summary of available evidence. #### 2. Inspect the failure ```bash sdesk get console --level error,warn --all --json sdesk get network --status-family 5xx --all --json ``` These focused queries are often the fastest route to a concrete failure. You can narrow evidence by text, timestamp, HTTP method, host, content type, event type, or status. #### 3. Reconstruct the user's path ```bash sdesk get metadata --json sdesk get events --all --json sdesk get transcript --all --json sdesk get analysis --json ``` Use events to recover clicks and navigation, metadata to reproduce the environment, the transcript to understand the user's intent, and existing analysis as another source of context. #### 4. Inspect what the user saw ```bash sdesk get screenshots --out ./screendesk-media --json sdesk get frames --count 6 --out ./screendesk-media --json ``` Screenshots and sampled frames are downloaded as authenticated media so you or a multimodal coding agent can inspect the visible state at important moments. #### 5. Correlate the evidence with the codebase Pass the JSON and downloaded media to your coding agent, or let an agent run the commands directly. Useful evidence-to-code connections include: * an exception message to the class or component that raises it; * a failed request URL to its route, controller, handler, or client; * a network response field to the parser or validation that consumes it; * the last user event to the UI action that initiated the failure; * a browser or device difference to compatibility-specific code. Example request for a coding agent: ``` Investigate this Screendesk report with the sdesk CLI: https://app.screendesk.io/recordings/REPORT_UUID Start with the report details, then load only the evidence needed to explain the failure. Correlate errors and requests with this repository, identify the most likely root cause, and propose a fix. Separate confirmed evidence from hypotheses. ``` #### 6. Check the scope of the issue Once you have a likely signature, look beyond the original report: ```bash sdesk find related --window-days 30 --limit 10 --json sdesk analyze recurring-errors --created-after 2026-07-01 --json sdesk compare reports --json ``` This helps determine whether the issue is isolated, environment-specific, or a recurring regression. ### Cross-report analysis #### Find related reports ```bash sdesk find related --window-days 30 --limit 10 --json ``` Results include explainable match reasons such as: * shared normalized error signatures; * matching source URL; * matching browser or operating system; * matching recording source; * shared labels. #### Summarize recurring errors ```bash sdesk analyze recurring-errors \ --created-after 2026-07-01 \ --report-limit 100 \ --limit 20 \ --json ``` The result contains normalized error signatures, occurrence counts, affected-report counts, and representative report links. #### Compare reports ```bash sdesk compare reports --json ``` Compare between two and five reports: ```bash sdesk compare reports --json ``` ### Search the workspace Search recordings and bug reports: ```bash sdesk list reports --query "checkout" --all --json ``` Useful filters include: ```bash sdesk list reports \ --type capture \ --browser Safari \ --os iOS \ --error-only \ --created-after 2026-07-01 \ --all \ --json ``` List folders and members: ```bash sdesk list folders --json sdesk list members --json ``` ### Use the CLI in scripts and CI Use `--json` whenever another program will consume the result. JSON output is stable to parse and avoids scraping terminal formatting. For complete collections, add `--all` so the CLI follows every pagination cursor: ```bash sdesk list reports \ --error-only \ --created-after 2026-07-01 \ --all \ --json ``` For headless environments, provide a CLI-enabled personal access token through the `SCREENDESK_TOKEN` environment variable. Keep the token in your CI provider's secret store and grant read-only access unless the job must perform a confirmed write. Common automation ideas include: * list new error-bearing reports after a deployment; * summarize recurring console and network failures for incident review; * compare reports from before and after a release; * download evidence into an isolated debugging workspace; * feed structured report context into an internal coding-agent workflow. Print the CLI's versioned, machine-readable command contract when an agent or integration needs to discover the available commands: ```bash sdesk agent-context ``` ### Update a report safely CLI writes require: 1. a read-write CLI credential; 2. explicit `--yes` confirmation; 3. an idempotency key. #### Create a comment ```bash sdesk create comment \ "Reproduced from the captured network failure." \ --yes \ --idempotency-key investigation-123 ``` Add a timestamped video comment: ```bash sdesk create comment \ "The failure begins here." \ --at 18400 \ --yes \ --idempotency-key investigation-123-comment ``` #### Update report fields ```bash sdesk update report \ --title "Checkout fails after payment confirmation" \ --label Bug \ --assignee engineer@example.com \ --yes \ --idempotency-key investigation-123-triage ``` Approved fields are: * title; * description; * folder; * labels; * assignees. {% hint style="warning" %} Reuse the same idempotency key when retrying the same uncertain write. Do not reuse a key for a different intended change. {% endhint %} ### Multiple workspace profiles Authenticate a named profile: ```bash sdesk --profile production auth login sdesk --profile staging auth login ``` List profiles: ```bash sdesk profile list --json ``` Select the default: ```bash sdesk profile use production ``` Run one command against another profile: ```bash sdesk --profile staging list reports --limit 10 --json ``` Delete a profile and its stored credential: ```bash sdesk profile delete staging ``` ### JSON and pagination Interactive terminal output is human-readable. Use `--json` for scripts and agents: ```bash sdesk get report --json ``` Collection responses use: ```json { "items": [], "next_cursor": null, "truncated": false, "hint": null } ``` Follow every pagination cursor with `--all`: ```bash sdesk get console --all --json sdesk list reports --all --json ``` ### Command reference | Command | Purpose | | -------------------------------- | ---------------------------------------------------- | | `sdesk auth login` | Authenticate with browser OAuth | | `sdesk auth login --token` | Read a PAT from standard input | | `sdesk auth status` | Show the active workspace and grant | | `sdesk auth logout` | Remove stored credentials | | `sdesk get report` | Get report details and evidence availability | | `sdesk get metadata` | Get browser, device, network, and technical metadata | | `sdesk get console` | Get filtered console logs | | `sdesk get network` | Get redacted network requests | | `sdesk get events` | Get captured user events | | `sdesk get transcript` | Get timestamped transcript segments | | `sdesk get analysis` | Get existing analysis | | `sdesk get screenshots` | Download screenshots and thumbnails | | `sdesk get frames` | Generate or download sampled video frames | | `sdesk list reports` | Search accessible reports | | `sdesk list folders` | List accessible folders | | `sdesk list members` | List active workspace members | | `sdesk find related` | Find related reports with match reasons | | `sdesk analyze recurring-errors` | Aggregate recurring error signatures | | `sdesk compare reports` | Compare two to five reports | | `sdesk create comment` | Create a confirmed comment | | `sdesk update report` | Update approved report fields | | `sdesk doctor` | Diagnose profile, credential, and API connectivity | | `sdesk skills install` | Install the bundled Codex skill | | `sdesk upgrade` | Install the latest checksummed release | | `sdesk uninstall --yes` | Remove the CLI executable | | `sdesk version` | Print the CLI version | ### Upgrade or remove Upgrade: ```bash sdesk upgrade ``` Uninstall: ```bash sdesk uninstall --yes ``` ### Security * OAuth and PAT credentials are bound to one workspace. * Stored credentials use the operating system credential store when available. * The fallback credential file uses restrictive permissions. * Network credentials, cookies, sensitive headers, and URL parameters are redacted. * Private folder and report permissions are preserved. * CLI access is audited without storing evidence bodies or credentials. * Report output may include workspace member, reporter, customer, comment author, and linked-issue details that the signed-in user can already access. * Exact visitor IP addresses are not returned. * Tokens should never be printed, committed, or passed as command-line arguments. ### Troubleshooting #### `sdesk` is not found Add `~/.local/bin` to your `PATH`, then restart the shell. #### Authentication fails ```bash sdesk doctor --json sdesk auth status --json ``` If the grant was revoked, authenticate again. #### The wrong workspace is active ```bash sdesk profile list --json sdesk profile use ``` #### A report returns not found The active profile may point to another workspace, or your user may not have access to the report's folder. #### A write command is forbidden Authenticate with read-write access: ```bash sdesk auth login --write ``` PAT users must create a token with **Screendesk CLI → Read and write** access. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.screendesk.io/debug-with-ai/cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.