CLI

Inspect Screendesk evidence from the terminal, scripts, CI, and coding agents.

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.

Fastest path: install sdesk, run sdesk auth login, then inspect a report URL.

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.

1

Install the CLI

Run the install command in Install.

2

Authenticate

Use browser OAuth for interactive work, or a personal access token for CI.

3

Load a report

Run sdesk get report <url-or-uuid> --json.

Prefer an interactive investigation inside an AI client? Use Screendesk MCP.

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

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:

sdesk version

If your shell cannot find sdesk, add ~/.local/bin to your PATH and open a new terminal.

Authenticate

OAuth

Browser OAuth is recommended for interactive use:

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:

sdesk auth login --write

Personal Access Token

Create a token from Personal Settings → MCP Access and enable Screendesk CLI.

Then run:

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.

Environment Variable

For one process, provide a CLI-enabled token through SCREENDESK_TOKEN:

SCREENDESK_TOKEN="$MY_SECURE_TOKEN" sdesk auth status --json

This overrides stored credentials for that process.

Check the active workspace:

sdesk auth status --json

Run diagnostics:

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.

sdesk skills install

Inspect the installed skill:

sdesk skills path
sdesk skills source

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.

A practical debugging workflow

1. Resolve the report

Start with the Screendesk URL from a support ticket, issue, or team message:

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

sdesk get console <url-or-uuid> --level error,warn --all --json
sdesk get network <url-or-uuid> --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

sdesk get metadata <url-or-uuid> --json
sdesk get events <url-or-uuid> --all --json
sdesk get transcript <url-or-uuid> --all --json
sdesk get analysis <url-or-uuid> --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

sdesk get screenshots <url-or-uuid> --out ./screendesk-media --json
sdesk get frames <url-or-uuid> --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:

sdesk find related <url-or-uuid> --window-days 30 --limit 10 --json
sdesk analyze recurring-errors --created-after 2026-07-01 --json
sdesk compare reports <failing-report> <successful-report> --json

This helps determine whether the issue is isolated, environment-specific, or a recurring regression.

Cross-report analysis

Find related reports

sdesk find related <url-or-uuid> --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

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

sdesk compare reports <first-report> <second-report> --json

Compare between two and five reports:

sdesk compare reports <report-1> <report-2> <report-3> --json

Search the workspace

Search recordings and bug reports:

sdesk list reports --query "checkout" --all --json

Useful filters include:

sdesk list reports \
  --type capture \
  --browser Safari \
  --os iOS \
  --error-only \
  --created-after 2026-07-01 \
  --all \
  --json

List folders and members:

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:

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:

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

sdesk create comment <url-or-uuid> \
  "Reproduced from the captured network failure." \
  --yes \
  --idempotency-key investigation-123

Add a timestamped video comment:

sdesk create comment <url-or-uuid> \
  "The failure begins here." \
  --at 18400 \
  --yes \
  --idempotency-key investigation-123-comment

Update report fields

sdesk update report <url-or-uuid> \
  --title "Checkout fails after payment confirmation" \
  --label Bug \
  --assignee [e-mail] \
  --yes \
  --idempotency-key investigation-123-triage

Approved fields are:

• title;
• description;
• folder;
• labels;
• assignees.

Reuse the same idempotency key when retrying the same uncertain write. Do not reuse a key for a different intended change.

Multiple workspace profiles

Authenticate a named profile:

sdesk --profile production auth login
sdesk --profile staging auth login

List profiles:

sdesk profile list --json

Select the default:

sdesk profile use production

Run one command against another profile:

sdesk --profile staging list reports --limit 10 --json

Delete a profile and its stored credential:

sdesk profile delete staging

JSON and pagination

Interactive terminal output is human-readable. Use --json for scripts and agents:

sdesk get report <url-or-uuid> --json

Collection responses use:

{
  "items": [],
  "next_cursor": null,
  "truncated": false,
  "hint": null
}

Follow every pagination cursor with --all:

sdesk get console <url-or-uuid> --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:

sdesk upgrade

Uninstall:

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

sdesk doctor --json
sdesk auth status --json

If the grant was revoked, authenticate again.

The wrong workspace is active

sdesk profile list --json
sdesk profile use <name>

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:

sdesk auth login --write

PAT users must create a token with Screendesk CLI → Read and write access.