# Detail API authentication: Bearer tokens and API keys Source: https://docs.detail.dev/api/authentication Learn how to authenticate Detail REST API requests using Bearer tokens, generate API keys from the dashboard, and handle auth errors. Detail authenticates API requests using Bearer tokens. Include your API key in the `Authorization` header of every request — the API does not support cookie-based auth or query-string tokens. ## Header format ``` Authorization: Bearer dtl_live_YOUR_KEY ``` Every request must carry this header, regardless of the endpoint. ## Example request ```bash theme={null} curl https://api.detail.dev/public/v1/user \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ## Obtaining an API key 1. Sign in at [app.detail.dev](https://app.detail.dev). 2. Navigate to **Settings → API Keys**. 3. Click **Create key**, give it a name, and copy the key value immediately — it will not be shown again. ## Key format API keys come in two types, distinguished by their prefix: | Prefix | Use | | ----------- | ------------------------------------------------ | | `dtl_live_` | Production keys — authenticate against live data | | `dtl_test_` | Test keys — for development and CI environments | ``` dtl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx dtl_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` Never embed API keys in client-side code, commit them to version control, or share them in public channels. Use environment variables or a secrets manager to inject keys at runtime. ## Error responses If authentication fails, the API returns a JSON error body alongside the HTTP error status. | Status | Error type | Cause | | ------ | ----------------------------- | -------------------------------------------------------------------------------- | | `401` | `DETAIL_AUTHENTICATION_ERROR` | The `Authorization` header is missing or the token is invalid | | `403` | `AUTHORIZATION_ERROR` | The token is valid but does not have permission to access the requested resource | A `401` response looks like this: ```json theme={null} { "type": "DETAIL_AUTHENTICATION_ERROR", "message": "Invalid or missing API key", "statusCode": 401 } ``` If you receive a `403`, check that the API key belongs to an account that has access to the organization or repository you are querying. # Bugs API: list, retrieve, and triage Detail bug findings Source: https://docs.detail.dev/api/bugs List, retrieve, and triage Detail bug findings programmatically. Filter by status, paginate results, and resolve or dismiss bugs via the API. The bugs endpoints give you full programmatic access to Detail's findings. You can list all pending bugs for a repository, fetch a single bug's details, and update a bug's review state — all without leaving your own tooling. *** ## GET /public/v1/bugs Returns a paginated list of bugs for a repository, filtered by review status. ```bash theme={null} curl "https://api.detail.dev/public/v1/bugs?repo_id=repo_abc123&status=pending" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Query parameters The repository ID to fetch bugs for. Repository IDs are prefixed with `repo_` and can be retrieved from [GET /public/v1/repos](/api/repos). Example: `repo_abc123`. Filter bugs by review state. One of: * `pending` — bugs that have not yet been reviewed * `resolved` — bugs marked as fixed * `dismissed` — bugs marked as not actionable Number of results to return. Between `1` and `100`. Defaults to `50`. Number of results to skip for pagination. Defaults to `0`. Filter bugs to those surfaced by a specific scan. Workflow request IDs are prefixed with `wr_` and are returned by [GET /public/v1/scans](/api/scans). ### Response Array of bug objects matching the query. Unique bug identifier, prefixed with `bug_`. Short title describing the finding. Detailed description of the bug and its potential impact. Path to the file where the bug was found, relative to the repository root. The commit SHA at which this bug was identified. Whether Detail has classified this finding as a security vulnerability. ID of the repository this bug belongs to. Unix timestamp (milliseconds) when the bug was first found. Attribution data for the commit that introduced the bug. Full commit SHA. Date the commit was made, in `YYYY-MM-DD` format. GitHub username or name of the commit author. Pull request number that introduced the bug, if applicable. The current review record for this bug. Present when the bug has been reviewed. One of `pending`, `resolved`, or `dismissed`. Unix timestamp (milliseconds) when the review was created. Reason for dismissal. One of `not_a_bug`, `wont_fix`, `duplicate`, or `other`. Only present when `state` is `dismissed`. Free-text note left during review. How the review was created. One of `review`, `linear`, `jira`, `asana`, `github_issue`, or `bug_fix_check`. Issues in external trackers linked to this bug. One of `linear`, `jira`, `github`, `slack`, or `asana`. The issue identifier in the external tracker. Direct URL to the issue in the external tracker. Total number of bugs matching the query, regardless of `limit` and `offset`. ### Example response ```json theme={null} { "bugs": [ { "id": "bug_abc123", "title": "SQL injection in user search", "summary": "User-controlled input is passed directly to a raw SQL query without sanitization, enabling SQL injection attacks.", "filePath": "src/db/users.ts", "commitSha": "abc1234567890abcdef", "isSecurityVulnerability": true, "repoId": "repo_xyz789", "createdAt": 1736899200000, "introducedIn": { "sha": "abc1234def5678", "date": "2024-12-10", "author": "alice", "prNumber": 42 }, "review": null, "linkedIssues": [] } ], "total": 12 } ``` *** ## GET /public/v1/bugs/\{bug\_id} Returns a single bug by its ID. The response shape is identical to an individual item in the `bugs` array above. ```bash theme={null} curl https://api.detail.dev/public/v1/bugs/bug_abc123 \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Path parameters The bug ID to retrieve. Must match the pattern `bug_*`. ### Example response ```json theme={null} { "id": "bug_abc123", "title": "SQL injection in user search", "summary": "User-controlled input is passed directly to a raw SQL query without sanitization, enabling SQL injection attacks.", "filePath": "src/db/users.ts", "commitSha": "abc1234567890abcdef", "isSecurityVulnerability": true, "repoId": "repo_xyz789", "createdAt": 1736899200000, "introducedIn": { "sha": "abc1234def5678", "date": "2024-12-10", "author": "alice", "prNumber": 42 }, "review": null, "linkedIssues": [ { "tracker": "linear", "issueId": "ENG-101", "url": "https://linear.app/team/issue/ENG-101" } ] } ``` *** ## POST /public/v1/bugs/\{bug\_id}/review Creates or updates a review on a bug. Use this to resolve, dismiss, or reopen a finding programmatically. ```bash theme={null} curl -X POST https://api.detail.dev/public/v1/bugs/bug_abc123/review \ -H "Authorization: Bearer dtl_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "state": "dismissed", "dismissalReason": "not_a_bug", "notes": "Reviewed — this is expected behavior in the context of our auth middleware." }' ``` ### Path parameters The bug ID to review. Must match the pattern `bug_*`. ### Request body The new review state for the bug. One of: * `resolved` — the bug has been fixed * `dismissed` — the bug is not actionable * `pending` — reopen a previously reviewed bug Required when `state` is `dismissed`. One of: * `not_a_bug` — the finding is a false positive * `wont_fix` — the team has decided not to address this * `duplicate` — already tracked elsewhere * `other` — any other reason Optional free-text note to record with the review. Useful for explaining triage decisions. ### Response Returns the created or updated `BugReview` object. The review state: `pending`, `resolved`, or `dismissed`. Unix timestamp (milliseconds) when this review was recorded. The dismissal reason, if `state` is `dismissed`. The note recorded with the review, if provided. How the review was created. For API-created reviews this is `review`. ### Example response ```json theme={null} { "state": "dismissed", "createdAt": 1736985600000, "dismissalReason": "not_a_bug", "notes": "Reviewed — this is expected behavior in the context of our auth middleware.", "source": "review" } ``` Calling this endpoint on a bug that already has a review will overwrite the existing review with the new state. # Detail REST API: programmatic access to bug findings Source: https://docs.detail.dev/api/overview Explore the Detail REST API to automate triage, sync bug findings to internal tools, and build dashboards with scan and repository data. The Detail REST API gives you programmatic access to bug findings, scan history, repository info, and custom rules. Use it to automate triage workflows, sync findings to internal tools, or build custom dashboards on top of Detail's analysis engine. ## Base URL All API requests go to: ``` https://api.detail.dev ``` Every endpoint is prefixed with `/public/v1/`. A full request URL looks like: ``` https://api.detail.dev/public/v1/bugs ``` ## Authentication The API uses Bearer token authentication. Pass your API key in the `Authorization` header on every request. See [Authentication](/api/authentication) for details on obtaining and using keys. ``` Authorization: Bearer dtl_live_YOUR_KEY ``` ## Request and response format All request bodies and responses use JSON. Set `Content-Type: application/json` when sending a request body. ## Pagination Endpoints that return lists accept `limit` and `offset` query parameters and include a `total` field in the response. | Parameter | Type | Default | Maximum | Description | | --------- | ------- | ------- | ------- | --------------------------- | | `limit` | integer | `50` | `100` | Number of results to return | | `offset` | integer | `0` | — | Number of results to skip | The response `total` field tells you how many records exist in total, so you can calculate subsequent offsets. ```bash theme={null} # Fetch the second page of 25 results curl "https://api.detail.dev/public/v1/bugs?repo_id=repo_abc123&status=pending&limit=25&offset=25" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ## Available endpoints | Method | Path | Description | | ------ | ------------------------------------ | ------------------------------------ | | `GET` | `/public/v1/user` | Authenticated user info | | `GET` | `/public/v1/bugs` | List bugs for a repository | | `GET` | `/public/v1/bugs/{bug_id}` | Get a single bug | | `POST` | `/public/v1/bugs/{bug_id}/review` | Resolve or dismiss a bug | | `GET` | `/public/v1/scans` | List scans for a repository | | `GET` | `/public/v1/repos` | List connected repositories | | `POST` | `/public/v1/rules` | Start an async rule creation job | | `GET` | `/public/v1/rules` | List completed rules | | `GET` | `/public/v1/rules/{rule_id}` | Get a single rule with file contents | | `GET` | `/public/v1/rules/requests` | List rule creation requests | | `GET` | `/public/v1/rules/requests/{rcr_id}` | Get a rule creation request status | ## Error codes All errors return an `ApiError` JSON object with `type`, `message`, and `statusCode` fields. ```json theme={null} { "type": "NOT_FOUND", "message": "Bug not found", "statusCode": 404 } ``` | Status | Type | Meaning | | ------ | ----------------------------------------------- | ------------------------------------------------- | | `400` | `INVALID_REQUEST_BODY` / `INVALID_QUERY_PARAMS` | Malformed request body or query parameters | | `401` | `DETAIL_AUTHENTICATION_ERROR` | Missing or invalid API key | | `403` | `AUTHORIZATION_ERROR` | Valid key but insufficient permissions | | `404` | `NOT_FOUND` | The requested resource does not exist | | `400` | `UNKNOWN_WORKFLOW_REQUEST` | The referenced workflow request ID does not exist | | `500` | `INTERNAL_ERROR` | Unexpected server error | # Repos API: list Detail repositories and user account info Source: https://docs.detail.dev/api/repos List repositories connected to Detail and retrieve the authenticated user's account information, including organization memberships. The repos and user endpoints give you the reference data you need to work with the rest of the API. Use the repos endpoint to discover `repo_id` values, which are required parameters for the bugs, scans, and rules endpoints. Use the user endpoint to verify your API key and inspect your organization memberships. *** ## GET /public/v1/repos Returns a paginated list of repositories connected to Detail that the authenticated user can access. ```bash theme={null} curl "https://api.detail.dev/public/v1/repos" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Query parameters Number of results to return. Between `1` and `100`. Defaults to `50`. Number of results to skip for pagination. Defaults to `0`. ### Response Array of repository objects accessible to the authenticated user. Unique repository identifier, prefixed with `repo_`. Use this as the `repo_id` parameter in other endpoints. Short repository name (without the owner prefix). Example: `my-repo`. GitHub user or organization that owns the repository. Example: `myorg`. Fully qualified repository name in `owner/repo` format. Example: `myorg/my-repo`. Whether the repository is `public` or `private` on GitHub. The default branch Detail scans. Example: `main`. ID of the Detail organization that owns this repository connection, prefixed with `org_`. Name of the Detail organization that owns this repository connection. Total number of repositories accessible to the user, regardless of `limit` and `offset`. ### Example response ```json theme={null} { "repos": [ { "id": "repo_abc123", "name": "my-repo", "ownerName": "myorg", "fullName": "myorg/my-repo", "visibility": "private", "primaryBranch": "main", "orgId": "org_xyz789", "orgName": "My Organization" }, { "id": "repo_def456", "name": "api-service", "ownerName": "myorg", "fullName": "myorg/api-service", "visibility": "private", "primaryBranch": "main", "orgId": "org_xyz789", "orgName": "My Organization" } ], "total": 2 } ``` If you already know the `owner/repo` slug for a repository, fetch the full list and filter by `fullName` client-side to find its `repo_id`. Alternatively, look up the repo ID in **Settings → Repositories** in the Detail dashboard. *** ## GET /public/v1/user Returns the authenticated user's email address and their Detail organization memberships. This is a useful endpoint to verify that your API key is valid and to inspect which organizations you have access to. ```bash theme={null} curl https://api.detail.dev/public/v1/user \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Response The email address associated with the authenticated account. The Detail organizations this user belongs to. Unique organization identifier, prefixed with `org_`. Display name of the organization. ### Example response ```json theme={null} { "email": "user@example.com", "orgs": [ { "id": "org_xyz789", "name": "My Organization" } ] } ``` # Rules API: create and manage Detail custom analysis rules Source: https://docs.detail.dev/api/rules Create and manage custom Detail analysis rules via the API. Rule creation is asynchronous — poll the request status endpoint to track progress. Detail rules are custom analysis patterns that teach Detail to find specific problems in your codebase. You can create rules by describing what you want to catch, by referencing existing bug IDs, or by pointing Detail at specific commit SHAs. Rule creation is asynchronous: you submit a request and receive a request ID, then poll for completion to retrieve the generated rule. *** ## POST /public/v1/rules Starts an asynchronous rule creation job. Detail analyses the input you provide — a description, existing bugs, or commits — and generates the rule files. Returns a `ruleCreationRequestId` you can use to poll for job status. ```bash theme={null} curl -X POST https://api.detail.dev/public/v1/rules \ -H "Authorization: Bearer dtl_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "repo_id": "repo_abc123", "input": { "description": "Flag raw SQL queries that interpolate user input without parameterization", "bugIds": ["bug_abc123", "bug_def456"], "commitShas": [] } }' ``` ### Request body The repository ID the rule should be associated with. Must match the pattern `repo_*`. The inputs Detail uses to generate the rule. All sub-fields are optional — if you omit all of them, Detail automatically proposes rules based on the repository's existing bug history. A plain-language description of the pattern you want the rule to detect. Be specific: mention the language, library, or anti-pattern you have in mind. Array of existing bug IDs (prefixed with `bug_`) to use as examples. Detail uses the code patterns in these bugs to infer a generalized rule. Array of commit SHAs to use as examples. Detail analyses the diffs in these commits to identify patterns worth codifying as rules. ### Response The ID of the new rule creation request, prefixed with `rcr_`. Use this to poll [GET /public/v1/rules/requests/\{rcr\_id}](#get-publicv1rulesrequestsrcr_id) for job status. ### Example response ```json theme={null} { "ruleCreationRequestId": "rcr_abc123" } ``` *** ## GET /public/v1/rules Returns all completed rules for a repository, ordered newest first. This endpoint only returns rules that have been successfully generated — use [GET /public/v1/rules/requests](#get-publicv1rulesrequests) to see rules that are still in progress. ```bash theme={null} curl "https://api.detail.dev/public/v1/rules?repo_id=repo_abc123" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Query parameters The repository ID to list rules for. Must match the pattern `repo_*`. ### Response Array of rule summary objects. Unique rule identifier, prefixed with `rule_`. Human-readable name Detail assigned to the rule. Unix timestamp (milliseconds) when the rule was created. ### Example response ```json theme={null} { "rules": [ { "id": "rule_abc123", "ruleName": "no-raw-sql-interpolation", "createdAt": 1736899200000 }, { "id": "rule_def456", "ruleName": "require-error-boundary", "createdAt": 1736812800000 } ] } ``` *** ## GET /public/v1/rules/\{rule\_id} Returns full details for a completed rule, including the generated rule files. Use this after polling the request status endpoint and confirming that the job has a `complete` status. ```bash theme={null} curl "https://api.detail.dev/public/v1/rules/rule_abc123" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Path parameters The rule ID to retrieve. Must match the pattern `rule_*`. ### Response Unique rule identifier, prefixed with `rule_`. Human-readable name Detail assigned to the rule. A map of filename to file content strings. Each key is a file path and each value is the text content of that rule file. Unix timestamp (milliseconds) when the rule was created. ### Example response ```json theme={null} { "id": "rule_abc123", "ruleName": "no-raw-sql-interpolation", "ruleFiles": { "no-raw-sql-interpolation.yaml": "id: no-raw-sql-interpolation\nlanguage: typescript\n...", "no-raw-sql-interpolation.test.ts": "// Rule test cases\n..." }, "createdAt": 1736899200000 } ``` *** ## GET /public/v1/rules/requests Returns all rule creation requests for a repository, ordered newest first. Each entry includes the original input, current status, and — once complete — a summary of the rules that were generated. ```bash theme={null} curl "https://api.detail.dev/public/v1/rules/requests?repo_id=repo_abc123" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Query parameters The repository ID to list rule creation requests for. Must match the pattern `repo_*`. ### Response Array of rule creation request objects. See [GET /public/v1/rules/requests/\{rcr\_id}](#get-publicv1rulesrequestsrcr_id) for the full field reference. *** ## GET /public/v1/rules/requests/\{rcr\_id} Returns the current status and provenance of a rule creation job. Poll this endpoint after calling [POST /public/v1/rules](#post-publicv1rules) until `status` is `complete` or `failed`. ```bash theme={null} curl "https://api.detail.dev/public/v1/rules/requests/rcr_abc123" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Path parameters The rule creation request ID to look up. Must match the pattern `rcr_*`. ### Response The rule creation request ID, prefixed with `rcr_`. Current status of the job. One of: * `pending` — the job is queued and has not started * `complete` — the job finished and rules are available * `failed` — the job encountered an error The `CreateRuleInput` submitted when the job was created — the `description`, `bugIds`, and `commitShas` you originally passed. Rules generated by this job. Empty until `status` is `complete`. The generated rule ID, prefixed with `rule_`. Use this with [GET /public/v1/rules/\{rule\_id}](#get-publicv1rulesrule_id) to fetch the full rule content. Human-readable name Detail assigned to the rule. Unix timestamp (milliseconds) when the request was created. Unix timestamp (milliseconds) when the job completed. Only present once the job has finished. ### Example response ```json theme={null} { "id": "rcr_abc123", "status": "complete", "input": { "description": "Flag raw SQL queries that interpolate user input without parameterization", "bugIds": ["bug_abc123"], "commitShas": [] }, "results": [ { "id": "rule_abc123", "ruleName": "no-raw-sql-interpolation" } ], "createdAt": 1736899200000, "completedAt": 1736899560000 } ``` ### Full polling example ```bash theme={null} # Step 1: Create the rule and capture the request ID RCR_ID=$(curl -s -X POST https://api.detail.dev/public/v1/rules \ -H "Authorization: Bearer dtl_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "repo_id": "repo_abc123", "input": { "description": "Flag SQL injection patterns in database query helpers" } }' | jq -r '.ruleCreationRequestId') echo "Request ID: $RCR_ID" # Step 2: Poll until complete while true; do STATUS=$(curl -s "https://api.detail.dev/public/v1/rules/requests/$RCR_ID" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" | jq -r '.status') echo "Status: $STATUS" if [ "$STATUS" = "complete" ] || [ "$STATUS" = "failed" ]; then break fi sleep 5 done # Step 3: Fetch the generated rule files RULE_ID=$(curl -s "https://api.detail.dev/public/v1/rules/requests/$RCR_ID" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" | jq -r '.results[0].id') curl "https://api.detail.dev/public/v1/rules/$RULE_ID" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` Rule generation typically completes within 30–60 seconds. We recommend polling every 5–10 seconds with a maximum of 20 attempts before surfacing an error to your users. # Detail scan history API: list and inspect analysis runs Source: https://docs.detail.dev/api/scans Retrieve Detail scan history for a repository. List past scans, check their status, and link bug findings to the scan that surfaced them. The scans endpoint lets you browse the history of Detail analysis runs for a repository. Each scan record tells you when the analysis ran, what commit it covered, how it was triggered, and how many bugs it found. You can also use a scan's `workflowRequestId` to filter bug results to only those surfaced during that specific scan. *** ## GET /public/v1/scans Returns a paginated list of scans for a repository, ordered newest first. ```bash theme={null} curl "https://api.detail.dev/public/v1/scans?repo_id=repo_abc123" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` ### Query parameters The repository ID to fetch scans for. Repository IDs are prefixed with `repo_` and are returned by [GET /public/v1/repos](/api/repos). Example: `repo_abc123`. Number of results to return. Between `1` and `100`. Defaults to `50`. Number of results to skip for pagination. Defaults to `0`. ### Response Array of scan objects for the repository. Unique identifier for the scan, prefixed with `wr_`. Pass this as `workflow_request_id` when querying [GET /public/v1/bugs](/api/bugs) to scope results to this scan. ID of the repository that was scanned. Short name of the repository (without owner prefix). GitHub owner (user or organization) of the repository. Current status of the scan. One of: * `in_progress` — the scan is still running * `complete` — the scan finished successfully * `failed` — the scan encountered an error * `dlq` — the scan was moved to the dead-letter queue after repeated failures The analysis mode used. One of: * `default` — full repository scan * `recentChanges` — analysis focused on recently changed code What triggered the scan. One of: * `scheduler` — triggered automatically on a schedule * `scanNow` — triggered manually via the dashboard or CLI The full commit SHA that the scan analysed. Unix timestamp (milliseconds) when the scan was created. Unix timestamp (milliseconds) when the scan completed. `null` if the scan is still in progress. Breakdown of bug counts for this scan. `null` while the scan is in progress. Total number of bugs found. Bugs with `pending` review state. Bugs marked as `resolved`. Bugs marked as `dismissed`. Total number of scans for the repository, regardless of `limit` and `offset`. ### Example response ```json theme={null} { "scans": [ { "workflowRequestId": "wr_abc123", "repoId": "repo_xyz789", "repoName": "my-repo", "ownerName": "myorg", "workflowStatus": "complete", "scanType": "default", "initiator": "scheduler", "commitSha": "abc1234567890abcdef", "createdAt": 1736899200000, "completedAt": 1736899800000, "bugCounts": { "total": 5, "open": 3, "resolved": 1, "dismissed": 1 } }, { "workflowRequestId": "wr_def456", "repoId": "repo_xyz789", "repoName": "my-repo", "ownerName": "myorg", "workflowStatus": "in_progress", "scanType": "recentChanges", "initiator": "scanNow", "commitSha": "def4567890abcdef12", "createdAt": 1737072000000, "completedAt": null, "bugCounts": null } ], "total": 8 } ``` To list the bugs surfaced by a specific scan, pass its `workflowRequestId` as the `workflow_request_id` parameter when calling [GET /public/v1/bugs](/api/bugs). ```bash theme={null} curl "https://api.detail.dev/public/v1/bugs?repo_id=repo_xyz789&status=pending&workflow_request_id=wr_abc123" \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` # Authenticate the Detail CLI with your Detail account Source: https://docs.detail.dev/cli/authentication Log in to the Detail CLI using a browser-based OAuth flow or pass a direct API token for CI/CD pipelines and headless environments. Before using the Detail CLI, authenticate with your Detail account. The CLI supports a browser-based OAuth flow for local development and direct token entry via `--token` for CI/CD pipelines or headless environments. ## Browser-based login (recommended) For local development, run `detail auth login` to open a browser window and complete the OAuth flow: ```bash theme={null} detail auth login ``` The CLI opens `https://app.detail.dev/cli-auth` in your default browser. After you approve access, the CLI receives a token and saves it to `~/.config/detail-cli/config.toml`. You'll see a confirmation message like this one: ```text theme={null} ✓ Successfully authenticated! Logged in as: user@example.com Example commands: detail bugs list / detail bugs show ``` If your browser doesn't open automatically, the CLI prints the full URL so you can paste it yourself. The browser flow uses PKCE (RFC 7636) for security. No client secret is transmitted — the CLI binds a local callback listener to receive the authorization code. ## Token-based login For automated pipelines or environments without a browser, pass an API token directly using `--token`: ```bash theme={null} detail auth login --token dtl_live_YOUR_API_KEY ``` Tokens start with `dtl_`. Generate one in the Detail dashboard under **Settings → API Keys**. In automated pipelines, e.g. in CI or in your software factory of choice, store the token in a secret and pass it via an environment variable to avoid hard-coding credentials: ```bash theme={null} detail auth login --token $DETAIL_API_KEY ``` ## Check authentication status Verify that the CLI is authenticated and confirm which account is active: ```bash theme={null} detail auth status # ✓ Authenticated # Email: user@example.com ``` If the stored token is invalid or has been revoked, `detail auth status` tells you to re-run `detail auth login`. ## Log out Remove the stored token from your machine: ```bash theme={null} detail auth logout # ✓ Logged out successfully ``` This clears the `api_token` field from `~/.config/detail-cli/config.toml`. It does not revoke the token in the Detail dashboard; do that in **Settings → API Keys** if needed. ## Token storage The CLI stores your token in `~/.config/detail-cli/config.toml` (Linux and macOS) or `%LOCALAPPDATA%\detail-cli\config.toml` (Windows). The file is created with permissions that restrict access to your user account. Do not commit `config.toml` to version control. Add `~/.config/detail-cli/` to your global `.gitignore` if you manage dotfiles in a public repository. ## Authentication subcommands summary | Command | Description | | -------------------- | -------------------------------------------- | | `detail auth login` | Log in via browser (PKCE OAuth) or `--token` | | `detail auth status` | Show the currently authenticated account | | `detail auth logout` | Remove stored credentials | # detail bugs: list, show, close, and reopen findings Source: https://docs.detail.dev/cli/commands/bugs CLI reference for the detail bugs command: list, inspect, close, and reopen AI-detected bug findings directly from your terminal. The `detail bugs` command group lets you list, inspect, resolve, and dismiss AI-detected bugs from the terminal. You can filter findings by status, author, time range, or scan, and triage them individually without leaving your workflow. ## `detail bugs list [REPO]` List bugs for a repository. ```bash theme={null} detail bugs list [OPTIONS] [REPO] ``` **Arguments** | Argument | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `REPO` | Repository as `owner/repo` (e.g. `usedetail/cli`), bare repo name (e.g. `cli`), or omitted to infer from the `origin` git remote. | **Flags** | Flag | Description | Default | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `--status ` | Status filter: `pending`, `resolved`, or `dismissed`. Repeat the flag or comma-separate values to combine (e.g. `--status pending,resolved`). | `pending` | | `--vulns` | Show only security vulnerabilities. | — | | `--introduced-by ` | Show only bugs introduced by these GitHub usernames. Comma-separated or repeat the flag. | — | | `--scan-id ` | Filter bugs to a specific scan by workflow request ID (`wr_...`). | — | | `--since ` | Show bugs created at or after this point. Accepts a duration (`1d`, `24h`, `30m`), an ISO date (`2024-01-01`), or an RFC 3339 timestamp. | — | | `--until ` | Show bugs created at or before this point. Same formats as `--since`. | — | | `--all` | Auto-paginate and return every matching bug instead of a single page. Cannot be combined with `--page` or `--limit`. | — | | `--limit <1-100>` | Maximum number of results per page. | `50` | | `--page ` | Page number, starting at 1. | `1` | | `--format ` | Output format: `table` or `json`. | `table` | Filters like `--vulns`, `--introduced-by`, `--since`, and `--until` are applied client-side after fetching all matching bugs. For large repositories, adding `--scan-id` first narrows the server-side result set and can speed things up considerably. **Examples** ```bash theme={null} # List pending bugs in a specific repo detail bugs list owner/my-repo # Show only security vulnerabilities (inferred from git remote) detail bugs list --vulns # Filter by author and time range detail bugs list --introduced-by alice,bob --since 7d # Show all pending and resolved bugs detail bugs list --status pending,resolved # Filter to a specific scan detail bugs list --scan-id wr_abc123 # Fetch every matching bug without paging detail bugs list --all # Output as JSON for scripting detail bugs list --format json ``` *** ## `detail bugs show ` Show the full AI-generated report for a single bug, including its title, affected file, security classification, introduction commit, and review history. ```bash theme={null} detail bugs show [OPTIONS] ``` **Arguments** | Argument | Description | | -------- | --------------------------- | | `BUG_ID` | Bug ID in `bug_...` format. | **Flags** | Flag | Description | Default | | ------------------- | --------------------------------- | ------- | | `--format ` | Output format: `table` or `json`. | `table` | **Examples** ```bash theme={null} # View the full report for a bug detail bugs show bug_abc123 # Output as JSON detail bugs show bug_abc123 --format json ``` *** ## `detail bugs close ` Resolve or dismiss a bug. When you run this command in a terminal without `--state`, Detail prompts you interactively to choose a close state, dismissal reason, and optional notes. ```bash theme={null} detail bugs close [OPTIONS] ``` **Arguments** | Argument | Description | | -------- | --------------------------- | | `BUG_ID` | Bug ID in `bug_...` format. | **Flags** | Flag | Description | Default | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------- | | `--state ` | Close state: `resolved` or `dismissed`. Prompted interactively if omitted in a TTY. Required in non-interactive mode. | — | | `--dismissal-reason ` | Reason for dismissal: `not-a-bug`, `wont-fix`, `duplicate`, or `other`. Required when `--state dismissed` in non-interactive mode. | — | | `--notes ` | Optional free-text note to attach to the review. | — | | `--format ` | Output format: `table` or `json`. | `table` | `--state pending` is not valid for `close`. Use `detail bugs reopen` to move a bug back to pending. **Examples** ```bash theme={null} # Resolve a bug detail bugs close bug_abc123 --state resolved # Dismiss a bug as not a bug detail bugs close bug_abc123 --state dismissed --dismissal-reason not-a-bug # Dismiss with a reason and a note detail bugs close bug_abc123 --state dismissed --dismissal-reason wont-fix --notes "Intentional behavior, see ADR-42" # Dismiss a duplicate (non-interactive, e.g. in CI) detail bugs close bug_abc123 --state dismissed --dismissal-reason duplicate ``` When running in a terminal, you can omit all flags and Detail will walk you through the prompts step by step. *** ## `detail bugs reopen ` Reopen a previously resolved or dismissed bug, flipping it back to `pending`. Use this when a fix is reverted or a "won't fix" decision is overturned. ```bash theme={null} detail bugs reopen ``` **Arguments** | Argument | Description | | -------- | --------------------------- | | `BUG_ID` | Bug ID in `bug_...` format. | **Examples** ```bash theme={null} detail bugs reopen bug_abc123 ``` # detail repos: list all your connected repositories Source: https://docs.detail.dev/cli/commands/repos CLI reference for detail repos list: view all repositories connected to your Detail account, grouped by GitHub organization name. The `detail repos` command lists all repositories your Detail account has access to, grouped by organization. Use it to confirm which repos Detail is monitoring and to look up the exact `owner/repo` slug you need for other commands. ## `detail repos list` List all repositories connected to your Detail account. ```bash theme={null} detail repos list [OPTIONS] ``` **Flags** | Flag | Description | Default | | ------------------- | ----------------------------------- | ------- | | `--limit <1-100>` | Maximum number of results per page. | `50` | | `--page ` | Page number, starting at 1. | `1` | | `--format ` | Output format: `table` or `json`. | `table` | In `table` mode, repositories are grouped under their organization name and sorted alphabetically. In `json` mode, the raw list is returned as a JSON array. **Examples** ```bash theme={null} # List all connected repositories detail repos list # Page through a large list detail repos list --page 2 # Output as JSON for scripting detail repos list --format json ``` To add or remove repositories, use the GitHub App settings in GitHub (Settings → Applications → Detail) or the Detail dashboard under **Settings → Repositories**. Changes appear in the CLI immediately after the GitHub App installation is updated. # detail rules: create, propose, and manage analysis rules Source: https://docs.detail.dev/cli/commands/rules CLI reference for detail rules: create, propose, list, show, and pull custom analysis rules that teach Detail what patterns to catch. The `detail rules` command group lets you create, list, inspect, and download custom analysis rules for your repositories. Rules can be used to enforce codebase guardrails. You can generate a rule from a plain language description, from an existing bug, or from commit SHAs that contain an example bug. An example use case would be: Detail has found a location where your application logs raw secrets, and you want to find any other bugs of this type, fix them all, and prevent them going forward. ## `detail rules create [REPO]` Submit a rule creation request for a repository. Rule creation takes time; Detail builds your rule in the background and iterates on it based on what it finds in your codebase until the new rule is working well. ```bash theme={null} detail rules create [OPTIONS] [REPO] ``` **Arguments** | Argument | Description | | -------- | --------------------------------------------------------------------------------------------- | | `REPO` | Repository as `owner/repo`, bare repo name, or omitted to infer from the `origin` git remote. | **Flags** | Flag | Description | | ---------------------- | ------------------------------------------------------------------------ | | `--description ` | Plain language description of the pattern to detect. | | `--bug-ids ` | Bug IDs to learn from. Comma-separated or repeat the flag. | | `--commit-shas ` | Commit SHAs to examine for patterns. Comma-separated or repeat the flag. | At least one of `--description`, `--bug-ids`, or `--commit-shas` is required. You can combine them — for example, provide both a description and bug IDs to give Detail richer context. On success, the command prints a rule creation request ID (`rcr_...`). Use `detail rules requests show ` to poll for completion. **Examples** ```bash theme={null} # Create a rule from a plain language description detail rules create --description "Flag any console.log in production code" # Create a rule from existing bug findings detail rules create --bug-ids bug_abc123,bug_def456 # Combine a description with commit SHAs detail rules create --commit-shas abc1234,def5678 --description "SQL injection pattern" # Target a specific repository explicitly detail rules create owner/my-repo --description "Detect unvalidated redirects" ``` *** ## `detail rules propose [REPO]` Ask Detail to automatically propose rules based on the repository's existing bug history. Detail reviews your findings and suggests rules that would catch similar patterns in future scans. ```bash theme={null} detail rules propose [REPO] ``` **Arguments** | Argument | Description | | -------- | --------------------------------------------------------------------------------------------- | | `REPO` | Repository as `owner/repo`, bare repo name, or omitted to infer from the `origin` git remote. | On success, the command prints a rule creation request ID. Poll progress with `detail rules requests show`. **Examples** ```bash theme={null} # Propose rules for the repo inferred from git remote detail rules propose # Propose rules for an explicit repo detail rules propose owner/my-repo ``` *** ## `detail rules requests list [REPO]` List all rule creation requests for a repository and their current status. ```bash theme={null} detail rules requests list [OPTIONS] [REPO] ``` **Arguments** | Argument | Description | | -------- | --------------------------------------------------------------------------------------------- | | `REPO` | Repository as `owner/repo`, bare repo name, or omitted to infer from the `origin` git remote. | **Flags** | Flag | Description | Default | | ------------------- | --------------------------------- | ------- | | `--format ` | Output format: `table` or `json`. | `table` | **Examples** ```bash theme={null} detail rules requests list detail rules requests list owner/my-repo --format json ``` *** ## `detail rules requests show ` Show the status and details of a specific rule creation request. Poll this command until the status is `complete` or `failed`. ```bash theme={null} detail rules requests show ``` **Arguments** | Argument | Description | | ------------ | --------------------------------------------- | | `REQUEST_ID` | Rule creation request ID in `rcr_...` format. | The output includes the request status, creation time, completion time (when available), the inputs you provided, and the IDs of any rules that were created. **Examples** ```bash theme={null} detail rules requests show rcr_abc123 ``` If the status is still `pending`, wait a moment and run the command again. Rule creation typically completes within a few minutes. *** ## `detail rules list [REPO]` List all completed rules for a repository. ```bash theme={null} detail rules list [OPTIONS] [REPO] ``` **Arguments** | Argument | Description | | -------- | --------------------------------------------------------------------------------------------- | | `REPO` | Repository as `owner/repo`, bare repo name, or omitted to infer from the `origin` git remote. | **Flags** | Flag | Description | Default | | ------------------- | --------------------------------- | ------- | | `--format ` | Output format: `table` or `json`. | `table` | **Examples** ```bash theme={null} detail rules list detail rules list owner/my-repo --format json ``` *** ## `detail rules show ` Show a rule's name, metadata, and full generated content. ```bash theme={null} detail rules show ``` **Arguments** | Argument | Description | | --------- | ----------------------------- | | `RULE_ID` | Rule ID in `rule_...` format. | **Examples** ```bash theme={null} detail rules show rule_abc123 ``` *** ## `detail rules pull ` Download a rule's generated files to your local filesystem so you can use them as Claude Code skills. ```bash theme={null} detail rules pull [OPTIONS] ``` **Arguments** | Argument | Description | | --------- | ----------------------------- | | `RULE_ID` | Rule ID in `rule_...` format. | **Flags** | Flag | Description | Default | | ---------------- | ---------------------------------------------------------------------------------------- | ----------------- | | `--output ` | Directory to write the `detail-rules/` folder into. Accepts a relative or absolute path. | `.claude/skills/` | The command writes all rule files into a `detail-rules/` subdirectory inside the output directory, creating any missing parent directories automatically. **Examples** ```bash theme={null} # Pull a rule into the default Claude skills location detail rules pull rule_abc123 # Pull a rule into a custom directory detail rules pull rule_abc123 --output ./my-rules/ ``` Pulled rules are stored under `.claude/skills/detail-rules/` by default and work as Claude Code skills. Commit this directory to your repository so the whole team benefits from the same rules. # detail scans: list and filter your repository scan history Source: https://docs.detail.dev/cli/commands/scans CLI reference for detail scans list: view full scan history and filter by status, scan type, and date range for any connected repository. The `detail scans` command lets you inspect the scan history for any repository, check the status of individual runs, and look up the scan ID you need to filter bugs with `detail bugs list --scan-id`. ## `detail scans list [REPO]` List recent scans for a repository. ```bash theme={null} detail scans list [OPTIONS] [REPO] ``` **Arguments** | Argument | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `REPO` | Repository as `owner/repo` (e.g. `usedetail/cli`), bare repo name (e.g. `cli`), or omitted to infer from the `origin` git remote. | **Flags** | Flag | Description | Default | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `--status ` | Filter by scan status: `in-progress`, `complete`, `failed`, or `dlq`. | — | | `--scan-type ` | Filter by scan type: `default` or `recent-changes`. | — | | `--since ` | Show scans created at or after this point. Accepts a duration (`1d`, `24h`, `30m`), an ISO date (`2024-01-01`), or an RFC 3339 timestamp. | — | | `--until ` | Show scans created at or before this point. Same formats as `--since`. | — | | `--limit <1-100>` | Maximum number of results per page. | `50` | | `--page ` | Page number, starting at 1. | `1` | | `--format ` | Output format: `table` or `json`. | `table` | Each row in the output includes the scan ID, status, scan type, commit SHA, bug counts, and timestamp. Filters are applied client-side. When you use `--status`, `--scan-type`, `--since`, or `--until`, Detail fetches all scans for the repository first and then filters the results locally. For repositories with many scans, combining `--since` with a narrow window keeps the result set manageable. **Examples** ```bash theme={null} # List recent scans for the repo inferred from git remote detail scans list # List scans for an explicit repository detail scans list owner/my-repo # Show only completed scans from the last week detail scans list --status complete --since 7d # Show failed scans of the recent-changes type detail scans list --status failed --scan-type recent-changes # Filter to a specific date range detail scans list --since 2024-06-01 --until 2024-06-30 # Output as JSON for scripting detail scans list --format json ``` Copy the scan ID from the output and pass it to `detail bugs list --scan-id ` to see only the bugs that were discovered in that particular run. # Install the Detail CLI on macOS, Linux, or Windows Source: https://docs.detail.dev/cli/installation Install the Detail CLI using the one-line installer script or build from source. The Detail CLI is a single static binary available for macOS, Linux, and Windows. It has no runtime dependencies; just download and run. Install it with the one-line installer script or build it yourself from source. ## Install with the installer script (recommended) The fastest way to get started is the official installer script, which downloads the correct pre-built binary for your platform and places it on your `PATH`: ```bash theme={null} curl --proto '=https' --tlsv1.2 -LsSf https://cli.detail.dev | sh ``` Restart your terminal (or run `source ~/.bashrc` / `source ~/.zshrc`) after the script completes. ## Build from source The Detail CLI is open source and can be cloned from GitHub: [https://github.com/usedetail/cli](https://github.com/usedetail/cli) If you prefer to build the CLI yourself, clone it and use `cargo install`: ```bash theme={null} cargo install detail-cli ``` This requires a working [Rust toolchain](https://rustup.rs). The binary is placed in `~/.cargo/bin/detail`. ## Verify the installation Confirm that the CLI is installed and on your `PATH`: ```bash theme={null} detail --version # detail-cli v0.2.5 ``` ## Update the CLI Run `detail update` to immediately pull the latest release: ```bash theme={null} detail update ``` The CLI also checks for updates automatically in the background and prints a notice when a new version is available. Structured JSON output (`--format json`) suppresses the notice to keep machine-readable output clean. ## Shell completions The CLI can generate completion scripts for Bash, Zsh, Fish, Elvish, and PowerShell. Add the appropriate line to your shell's startup file so completions load in every new session: ```bash theme={null} # Bash — add to ~/.bashrc source <(detail completions bash) # Zsh — add to ~/.zshrc source <(detail completions zsh) # Fish — add to ~/.config/fish/config.fish detail completions fish | source # PowerShell — add to $PROFILE detail completions powershell | Out-String | Invoke-Expression ``` ## Config file location The CLI stores its configuration and authentication token in a single TOML file: | Platform | Path | | ------------- | --------------------------------------- | | Linux / macOS | `~/.config/detail-cli/config.toml` | | Windows | `%LOCALAPPDATA%\detail-cli\config.toml` | If the `XDG_CONFIG_HOME` environment variable is set, it takes precedence over the default location on all platforms. You can hand-edit `config.toml` to override advanced settings such as the API URL. The CLI preserves any comments and custom keys you add. ## Next steps Once the CLI is installed, authenticate with your Detail account: ```bash theme={null} detail auth login ``` See [Authentication](/cli/authentication) for the full login guide. # Detail CLI: Consume bugs and manage rules from the terminal Source: https://docs.detail.dev/cli/overview The Detail CLI gives you full access to your Detail workspace from the terminal. Triage bugs, manage rules, inspect scans, and more. The Detail CLI (`detail`) gives you full access to your Detail workspace from the terminal. Use it to triage bugs, manage custom rules, and inspect scan history. ## What you can do Each top-level command maps to a core concept in Detail. Run any of them with `--help` to see the available subcommands and options. | Command | What it does | | -------------- | ------------------------------------------------------------------ | | `detail bugs` | List, view, close, and reopen bug findings | | `detail rules` | Create, propose, and inspect custom analysis rules | | `detail scans` | List recent scans and filter by status, date, or type | | `detail repos` | List repositories connected to your Detail account | | `detail auth` | Authenticate with your Detail account | | `detail skill` | Install Detail skills into your repo's `.claude/skills/` directory | ## Installation The CLI is a single static binary with no runtime dependencies. Install it on macOS, Linux, or Windows. See the [Installation guide](/cli/installation) for the full steps. ## Authentication Before running any command, authenticate with your Detail account using `detail auth login`. The CLI supports a browser-based OAuth flow for local development and a `--token` flag for CI/CD pipelines. See the [Authentication guide](/cli/authentication) for details. ## Next steps Install the Detail CLI on macOS, Linux, or Windows. Log in with your Detail account or an API key. List, view, close, and reopen bug findings. Create and manage custom analysis rules. ## Getting help Run `detail --help` for a top-level overview of every command. Append `--help` to any subcommand for focused usage information: ```bash theme={null} detail --help detail bugs --help detail rules create --help ``` To enable tab completion in your shell, use `detail completions`: ```bash theme={null} # Bash source <(detail completions bash) # Zsh source <(detail completions zsh) # Fish detail completions fish | source # PowerShell detail completions powershell | Out-String | Invoke-Expression ``` See the [Installation guide](/cli/installation) for how to persist completions across shell sessions. # Create and manage Detail API keys Source: https://docs.detail.dev/configuration/api-keys Generate API keys to authenticate CLI and REST API access, understand the key format, and learn how to rotate or revoke keys safely. Detail API keys let you authenticate programmatic access to the Detail REST API and CLI. You can create multiple keys for different environments or team members, and revoke any key instantly if it's no longer needed or has been compromised. ## Creating an API key Go to [app.detail.dev](https://app.detail.dev) and sign in. Go to **Settings → API Keys**. Click **New API Key**. Give the key a descriptive name so you can identify it later — for example, `CI pipeline`, `Local dev`, or `Staging`. Copy the key immediately and store it somewhere safe (for example, your password manager or secrets vault). **The full key value is only shown once** — if you lose it, you'll need to create a new one. ## Key format Production API keys follow this format: ```text theme={null} dtl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` All Detail API keys are prefixed with `dtl_live_` for production environments. This prefix makes it easy to detect keys in code reviews and automated secret scanners. ## Using API keys **REST API** — Pass the key as a Bearer token in the `Authorization` header: ```bash theme={null} curl https://api.detail.dev/public/v1/repos \ -H "Authorization: Bearer dtl_live_YOUR_KEY" ``` **CLI** — Authenticate the Detail CLI with your key using the `auth login` command: ```bash theme={null} detail auth login --token dtl_live_YOUR_KEY ``` Once authenticated, the CLI stores the token locally and uses it for all subsequent commands. ## Revoking a key Go to **Settings → API Keys** in the Detail dashboard. Locate the key by its name in the list. Click the trash icon next to the key and confirm the revocation. Revocation is immediate. Any request using the revoked key will return a `401 DETAIL_AUTHENTICATION_ERROR` response. There is no grace period. Never commit API keys to version control — not even in private repositories. Use environment variables or a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or GitHub Actions secrets) to inject keys at runtime. ## Best practices * **One key per environment** — create separate keys for CI, staging, and production so you can rotate or revoke them independently without disrupting other workflows. * **Use descriptive names** — name keys after their purpose and owner (e.g., `GitHub Actions – prod deploy`) so you always know where a key is used before revoking it. * **Rotate keys periodically** — even if a key hasn't been compromised, rotating it regularly limits the blast radius of an undetected leak. * **Revoke immediately on compromise** — if you suspect a key has been exposed, revoke it right away. Create a replacement key and update the relevant environment variables or secrets before resuming work. # Configure repository settings in Detail Source: https://docs.detail.dev/configuration/repos Control which Detail features are active per repository, set scan frequency, configure path filters, and add or remove repos from the dashboard. Each repository connected to Detail has its own settings controlling which features are enabled, how often scans run, and which parts of the codebase to focus on. This lets you tailor Detail's behavior per project — for example, running Doc Fixes daily on your primary service while scanning only the `src/` directory of a monorepo. ## Accessing repository settings Go to **Settings → Repositories** in the Detail dashboard, then click the name of the repository you want to configure. ## Per-repository settings Enable or disable the Bug Finder agent for this repository. Set path filters to focus scanning on specific directories and skip test or vendor code. Enable or disable automated dead code detection. When enabled, Detail opens pull requests to remove unreachable code it finds during scans. Enable or disable documentation drift detection. Set the run frequency to **weekly** (once per week) or **weekdays** (Monday through Friday). ## Adding repositories Go to **Settings → Repositories** in the Detail dashboard. Click the **Add Repository** button. Detail shows you a list of repositories accessible via the installed Detail GitHub App. Select the repository you want to add and click **Add**. Detail schedules an initial scan automatically. If the repository you want isn't listed, you may need to update the Detail GitHub App's repository access first. Go to **GitHub → Settings → Applications → Detail** and add the repository under *Repository access*. ## Removing a repository To remove a repository from Detail and purge all history, open its settings page and click **Remove from Detail** at the bottom of the page. Confirm the removal in the dialog that appears. # Configure and trigger scans in Detail Source: https://docs.detail.dev/configuration/scans Understand Detail's scan types and schedule, trigger on-demand scans from the dashboard, and inspect past scan runs with the CLI or dashboard. Detail runs scans on a nightly schedule by default, so your bug findings stay fresh without any manual effort. You can also trigger on-demand scans at any time from the dashboard and configure exactly what each scan covers — whether that's a full repository scan or a focused look at recent changes. ## Scan types A full repository scan against the latest commit on your primary branch. This is the standard scan type used for nightly runs. Scans only code introduced since a specific date or by specific authors. Faster than a full scan and useful for reviewing work in progress before merging. ## Scan schedule Recurring scans run automatically — no configuration required. Detail picks up the latest commit on your primary branch each week and runs a Recent Changes scan. Detail also runs a Full Repo scan every month. Results appear in the dashboard as soon as the scan completes. ## Triggering an on-demand scan You can kick off a scan at any time without waiting for the recurring schedule. **From the dashboard:** 1. Go to **Scans** and find the repository you want to scan. 2. Click **Schedule New Scan** and follow the flow to select a repo. 3. The scan starts immediately. You'll see it appear under the **Scans** tab with an `in-progress` status. ## Inspecting scan history **From the dashboard:** Click on a repository, then open the **Scans** tab. You'll see a list of past scan runs with their status, scan type, commit SHA, and bug counts. **From the CLI:** Use `detail scans list` to view scan history for a repository. ```bash theme={null} # List all scans for a repository detail scans list owner/my-repo # Filter by status and time range detail scans list --status complete --since 7d ``` ## Scan statuses | Status | Meaning | | ------------- | ------------------------------------------------------------------------------------ | | `in_progress` | The scan is currently running. Results are not yet available. | | `complete` | The scan finished successfully. Bug findings are available in the dashboard and API. | | `failed` | The scan encountered an error and did not produce results. | If a scan consistently shows a `failed` status, contact [support@detail.dev](mailto:support@detail.dev) with the repository name. # Set up SSO authentication for Detail Source: https://docs.detail.dev/configuration/sso Configure single sign-on for your Detail organization using OIDC or SAML, with step-by-step setup instructions for Okta OIDC and Okta SAML. Detail supports single sign-on (SSO) so your team can sign in with your existing identity provider. Both **OIDC** and **SAML** are supported, and you can configure SSO with any provider that implements either protocol, including Okta, Azure AD, Google Workspace, and OneLogin. To start setup, sign in to Detail and go to **Settings → Organization → Setup SSO**. ## Okta OIDC setup Follow these steps to configure Detail to use Okta OIDC authentication. In the Detail UI, click **Setup SSO** under **Settings → Organization**. Then, visit the Okta admin console and click **Create App Integration**. Choose **OIDC** as the sign-in method and **Web Application** as the application type. Name the app `Detail`. Under **Grant type**, choose **Authorization Code**. Enter the **sign-in redirect URI** value provided from the Detail app. Remove the default **sign-out redirect URI** if one is set. Under **Controlled access**, select **Allow everyone in your organization to access** and **Enable immediate access with Federation Broker Mode**, then save. Once complete, locate three values in the newly created application: * The **client ID** and **client secret** are found under the **General** tab of the application. * The **issuer** (Okta instance URL) is located in the top right hand corner dropdown, under your email address. Enter these values into the Detail UI to complete setup. ## Okta SAML setup Follow these steps to configure SAML authentication with Detail. Visit the Okta admin console and click **Create App Integration**. Choose **SAML 2.0**. Name the app `Detail` and optionally add a logo. On the **Configure SAML** screen, add the **single sign-on URL** and **audience URI**. (These will be the same value, provided by Detail.) Update the **Name ID format** to `EmailAddress` and the **Application username** to `Email`. Click **Submit** on the Feedback screen and go straight to the **Sign On** tab for the new application. On the **Sign On** tab, set up attribute statements. Click **Show legacy configuration** and add three statements (all **basic** format): | Name | Value | | ----------- | ---------------- | | `firstName` | `user.firstName` | | `lastName` | `user.lastName` | | `id` | `user.id` | Copy the **Metadata URL** from Okta and paste it into the Detail UI to complete setup. You are all set to add desired users to the application in Okta. The **Setup SSO** screen in Detail accepts standard OIDC and SAML configuration values from any compliant identity provider. # Bug Finder: code scanning that finds your most severe bugs Source: https://docs.detail.dev/features/bug-finder Detail's scans your GitHub repositories and produces a ranked list of reproducible bugs. Detail scans your codebase and produces a ranked list of reproducible bugs. Unlike shallow bug scanners, Detail sets up your dev environment in the cloud, runs code to confirm bugs are real, and uses historical data on what bugs get fixed to select the bugs you're most likely to care about. Each scan generates a new set of findings. ## How it works When a scan runs, Detail dispatches sets up your dev environment in a container and runs whatever you run locally, e.g. a local Redis instance or a Next.js application. Detail finds thousands of candidate bugs and determines which ones are real. Detail maintains a model of which bugs get fixed and which bugs get ignored, which we use to select a small subset of the bugs we can find that you are most likely to fix. Before results are surfaced, Detail also deduplicates findings across scans, so the same underlying issue never appears twice unless the code substantially changes. Each bug is packaged as a structured bug report with all the context you need to fix it. Optionally, we will deliver your bugs to Linear, Jira, Asana, GitHub Issues, or Slack. ## Scan modes Detail scans your whole repository for the bugs we think you are most likely to care about. Detail focuses on changes introduced in the last week. Useful for reviewing a sprint's worth of changes or improving quality before a release. Trigger a one-off scan at any time from the Detail dashboard. If you're interested in a custom scan, e.g. one that focuses on a particular portion of your repository or only on a certain kind of bug, contact Detail Support and we can help. ## Bug report fields Every bug Detail finds includes the following information: | Field | Description | | ----------------- | ------------------------------------------------------------------------------------------- | | **Title** | A short, human-readable description of the bug | | **Summary** | A full explanation of the problem and why it is a bug | | **File path** | The file where the bug was found | | **Introduced By** | The commit SHA, date, author, and (if available) pull request that first introduced the bug | | **Security Flag** | Whether the bug is classified as a security vulnerability | ## Managing bugs From the dashboard or CLI you can change the status of any bug: * **Open** — unresolved and awaiting action (the default state) * **Resolved** — fixed and closed * **Dismissed** — closed without a fix, with a reason: *Not a Bug*, *Won't Fix*, *Duplicate*, or *Other* You can always reopen later. This is useful when a fix is reverted or a "won't fix" decision is overturned. # Dead Code Detection and Removal Source: https://docs.detail.dev/features/dead-code Detail's finds unused symbols, functions, and files across your repositories and automatically opens pull requests to remove them. Detail detects unused symbols, functions, and files in your codebase and automatically opens pull requests to remove them. You get a steady stream of focused PRs that keep your codebase lean. If your CI pipeline catches an issue with a removal, Detail will update the PR automatically. ## How it works Detail scans your repository looking for dead code. It only flags code it can verify is truly unreferenced and has been dead for a minimum amount of time. For each batch of dead code found, the agent opens a pull request containing the removal patch. The PR description explains what was removed, when it was introduced, when it became unused, and why Detail is sure it's safe to remove. Detail will automatically assign the PR to an engineer who has context on the dead code. Treat the PR like any other: review the diff, leave comments, request changes, or merge. You stay in full control of what lands in your main branch. ## Enabling dead code scanning In the Detail dashboard, go to **Dead Code** and select the repository you want to configure. Toggle **Dead Code** to on. You can schedule scans nightly, weekly, or on weekdays only. Optionally, you can specify a single reviewer to whom Detail will assign all Dead Code PRs. # Doc Drift Detection and Auto-Fix Source: https://docs.detail.dev/features/doc-fixes Detail detects when code changes make your documentation stale and automatically opens GitHub pull requests to bring it back in sync. Detail detects when code changes make documentation stale and automatically opens GitHub pull requests to update it. Documentation drift – where the code moves forward but the docs still describe the old behavior – is one of the most common invisible forms of technical debt; it doesn't affect your product directly, but it degrades the agents that build your product. Detail finds it and fixes it for you. ## What documentation drift looks like Documentation drift happens gradually: * A module is refactored and its README still shows the old API * A configuration option is renamed but the docs still use the original name * New behavior is added to a function without a corresponding update to its documentation * A CLI changes but an agent skill still specifies the old flags Each of these cases causes mistakes in the agents that subsequently modify your code, e.g. reimplementing functionality that already exists or wasting tokens going down obsolete paths. ## How it works Detail compares recent commits against your repository's documentation and identifies places where the documentation no longer accurately describes the code. For each stale documentation item, Detail opens a GitHub pull request with the updated documentation. The PR description explains what changed in the code and why the docs needed to be updated. Review the PR diff, make any additional edits you want, and merge when you're satisfied. The updated docs land in your repository just like any other PR. ## Enabling Doc Fixes In the Detail dashboard, go to **Doc Drift** and select the repository you want to configure. Toggle **Doc Fixes** to on for the repository. You can select how often the agent should look for documentation drift – weekly or on every weekday – and optionally specify a single engineer who should be tagged on all Doc Drift PRs. # Rules: Enforce codebase guardrails Source: https://docs.detail.dev/features/rules Detail's Rules engine lets you encode project-specific standards into reusable rules and enforce them across your codebase. Detail's Rules engine lets you create repo-specific rules. Describe a pattern in plain language, via an example bug, via an example commit SHA, and Detail generates a rule. You can use these rules ## How rules work Detail rules are enforced via an agent skill that's stored in your repository, so you can use it flexibly: as a CI check, or to find existing violations and fix them in bulk. Rules work alongside Detail's built-in bug scanning, so you can turn an individual bug into a guardrail that prevents the whole category of bug from happening. Rule creation is asynchronous and can take about an hour. Detail tests out the rule against your codebase and iterates on it until the results look correct. ## Creating rules from the CLI You can create a rule from three kinds of input, or combine them in a single request: ```bash theme={null} # From a plain-language description detail rules create --description "Flag any use of console.log in production code" # From existing bug IDs — Detail uses these as examples of the pattern to detect detail rules create --bug-ids bug_abc123,bug_def456 # From commit SHAs — Detail examines the commits to extract the underlying pattern detail rules create --commit-shas abc1234,def5678 # Combine all three for richer context detail rules create \ --description "Avoid raw SQL string concatenation" \ --bug-ids bug_abc123 \ --commit-shas abc1234 ``` After submitting, Detail prints the request ID: ```text theme={null} ✓ Rule creation started. Request ID: rcr_01j9x... Use 'detail rules requests show ' to check progress. ``` ## Proposing rules automatically If you're not sure where to start, let Detail analyze your bug history and propose rules for you: ```bash theme={null} detail rules propose ``` Detail examines patterns in your existing bugs and generates rule proposals automatically. You receive a request ID and can review the proposed rules once they're ready. ## Checking rule creation status Rule creation runs asynchronously. Use the `requests` subcommands to track progress: ```bash theme={null} # List all rule creation requests for the current repo detail rules requests list # Check the status of a specific request detail rules requests show rcr_01j9x... ``` The status field will show the current state of the request, and when it completes you'll see the IDs of the rules that were created. ## Viewing and using rules Once rules are created, you can inspect and manage them with the following commands: ```bash theme={null} # List all rules for the current repository detail rules list # Read the full content of a specific rule detail rules show rule_01j9x... # Download rule files to your local machine detail rules pull rule_01j9x... ``` `detail rules pull` writes the rule files into `.claude/skills/detail-rules/` in your current directory by default. You can specify a different output directory with `--output`: ```bash theme={null} detail rules pull rule_01j9x... --output ./my-skills/ ``` ## Claude Code Skills integration Rules pulled with `detail rules pull` are written as Claude Code skill files. This means the same patterns Detail uses in your cloud scans can guide your AI coding assistant when writing new code locally — closing the loop between detection and prevention. Rule creation is asynchronous. After running `detail rules create` or `detail rules propose`, you receive a request ID (`rcr_...`). Poll progress with `detail rules requests show ` and retrieve the finished rule with `detail rules show ` once the request completes. ## Reference | Command | Description | | ------------------------------------- | --------------------------------------------------------------------------- | | `detail rules create` | Submit a rule creation request using a description, bug IDs, or commit SHAs | | `detail rules propose` | Ask Detail to propose rules based on your bug history | | `detail rules list` | List all completed rules for the current repository | | `detail rules show ` | Display the content of a specific rule | | `detail rules pull ` | Download rule files locally into `.claude/skills/detail-rules/` | | `detail rules requests list` | List all rule creation requests for the current repository | | `detail rules requests show ` | Check the status of a specific rule creation request | # Security Vulnerability Scanning with Detail AI Source: https://docs.detail.dev/features/security-scanning Detail flags security vulnerabilities as a distinct category within every scan. Detail flags security vulnerabilities as a distinct category within its bug-finding scans. Contact Support to run a vulnerability-only scan, with a particular focus on vulnerabilities. ## What counts as a security vulnerability Detail's AI agents look for a broad range of security issues, including but not limited to: * **Injection flaws** — SQL injection, command injection, template injection, and similar input-handling bugs * **Insecure data handling** — sensitive data written to logs, stored unencrypted, or transmitted over unprotected channels * **Authentication and authorization flaws** — broken access controls, missing authentication checks, and privilege escalation paths * **Cryptographic weaknesses** — use of deprecated algorithms, weak key sizes, and insecure random-number generation * **Dependency and configuration issues** — patterns that indicate insecure defaults or known-vulnerable usage Each flagged issue carries the same full report as a standard bug: title, summary, file path, and introduced-by information. ## Security Findings If you only want to see security findings, you can filter for them in any consumption surface. Open the Bugs view and select the **Security** filter to show only security vulnerabilities. Pass the `--vulns` flag to the bugs list command: ```bash theme={null} detail bugs list --vulns ``` Fetch bugs and filter on the `isSecurityVulnerability` field: ```json theme={null} { "isSecurityVulnerability": true } ``` ## Filtering security findings ### Dashboard 1. Navigate to the **Bugs** section of your repository. 2. Click the **Security** filter chip. ### CLI ```bash theme={null} # Show only open security vulnerabilities detail bugs list --vulns # Combine with other filters — e.g. bugs introduced in the last 7 days detail bugs list --vulns --since 7d # Show a specific vulnerability's full report detail bugs show bug_abc123 ``` ### API Fetch bugs from the API and filter on the `isSecurityVulnerability` field in the response. Each bug object includes: ```json theme={null} { "id": "bug_abc123", "title": "SQL injection in user search endpoint", "isSecurityVulnerability": true, "filePath": "src/api/users.ts", "summary": "...", "introducedIn": { "sha": "a1b2c3d", "author": "dev@example.com", "date": "2024-11-01" } } ``` Filter your results to objects where `isSecurityVulnerability === true`. ## What each security finding includes Security findings include all the standard bug report fields. The key fields are: | Field | API field | Description | | ----------------- | ------------------------- | -------------------------------------------------------------- | | **Title** | `title` | Short description of the vulnerability | | **Summary** | `summary` | Full explanation of the security risk and its potential impact | | **File path** | `filePath` | File where the vulnerability exists | | **Introduced by** | `introducedIn` | Commit SHA, date, author, and PR that introduced the code | | **Security flag** | `isSecurityVulnerability` | Always `true` for security findings | # Connect GitHub repositories to Detail Source: https://docs.detail.dev/integrations/github Install the Detail GitHub App to give Detail read access to scan your repositories and write access to open automated fix pull requests. Detail integrates with GitHub through a GitHub App that you install on your personal account or organization. The app grants Detail read access to scan your repositories and write access to open pull requests for doc fixes or dead code. ## Installing the GitHub App Go to [app.detail.dev](https://app.detail.dev) and sign in using GitHub OAuth. After signing in, you'll be prompted to install the Detail GitHub App on your account or organization. Click **Install**. Choose which repositories you want Detail to access. You can start with a single repository and expand later — you don't need to grant access to everything upfront. Complete the GitHub authorization flow. You'll be redirected back to the Detail dashboard once the app is installed successfully. ## Permissions Detail requests Detail requests the minimum permissions needed to scan your code and open fix PRs. | Permission | Access | Purpose | | ----------------- | ------ | -------------------------------------------------------------------------------------- | | **Code** | Read | Scan repository contents for bugs, security issues, dead code, and documentation drift | | **Commits** | Read | Associate findings with the commit that introduced them | | **Pull requests** | Read | Read CI check results on existing PRs | | **Pull requests** | Write | Open automated fix PRs from Dead Code, Doc Fixes, and Pass-CI agents | | **Webhooks** | — | Listen for push events, PR events, and check suite completions | ## Adding or removing repositories You can adjust which repositories Detail can access at any time through two paths: * **Via GitHub**: Go to **GitHub → Settings → Applications → Detail** and modify the repository list under *Repository access*. * **Via Detail**: Go to **Settings → Repositories** in the Detail dashboard, then click **Add Repository** or **Remove from Detail**. ## GitHub Enterprise Server Detail supports GitHub Enterprise Server (GHE) for teams on self-hosted GitHub installations. Because GHE requires a custom GitHub App registration against your own hostname, this is handled on a per-organization basis. Contact the Detail team at [support@detail.dev](mailto:support@detail.dev) to configure a custom GitHub App for your GHE instance. ## How automated pull requests work When Detail's Dead Code or Doc Drift scans find problems, they open a pull request in your GitHub repository. The PR includes a description of what was changed and why. If CI checks fail on a Detail-created PR, Detail will update the branch automatically. Detail never pushes directly to your main or default branch. Every change goes through a pull request that you can review, request changes on, or close. # Sync Detail bugs with Linear, Jira, and Asana Source: https://docs.detail.dev/integrations/linear-jira-asana Publish Detail bug findings as issues or tasks in Linear, Jira, or Asana, with status sync so resolving an issue marks the bug as Resolved or Dismissed. Connect Detail to Linear, Jira, or Asana to publish bugs as issues or tasks in your project management tool. Status changes sync back to Detail: when you close an issue in your tracker, Detail automatically marks the corresponding bug as Resolved or Dismissed. ## Connecting Linear Go to **Settings → Integrations → Linear** in the Detail dashboard. Click **Connect** and complete the OAuth flow. You'll be redirected to Linear to grant Detail access to your workspace. Select the default Linear workspace and project where Detail should publish bugs. You can override this on a per-bug basis when publishing. ## Connecting Jira Go to **Settings → Integrations → Jira** in the Detail dashboard. Click **Connect** and authorize Detail via Atlassian OAuth. You'll be prompted to log in to your Atlassian account if you aren't already. Select the default Jira project where Detail should create issues. You can override this per bug at publish time. ## Connecting Asana Go to **Settings → Integrations → Asana** in the Detail dashboard. Click **Connect** and complete the Asana OAuth flow. Select the default Asana workspace and project where Detail should create tasks. ## Publishing a bug to your tracker To publish an individual bug, open its detail page and click **Publish**. Choose your destination tracker from the dropdown. The issue or task is created immediately and a link back to the Detail bug report is included in the description. You can publish multiple bugs at once from the main dashboard. Select the bugs you want using the checkboxes, then choose **Publish** from the bulk actions menu. ## Status sync Once a bug is published, Detail keeps its status in sync with the linked issue or task automatically. When you mark a Linear issue as Done (or any state mapped to resolved), the bug is automatically marked resolved in Detail. When you resolve or close a Jira issue, Detail updates the linked bug state accordingly. Marking an Asana task complete automatically resolves the linked bug in Detail. # Post Detail bug reports to Slack Source: https://docs.detail.dev/integrations/slack Connect Detail to Slack to receive bug reports in Slack. The Detail Slack integration posts bugs directly to Slack, so your team stays informed without needing to check a dashboard. You can also publish individual bug findings to any channel manually, from the bug view. ## Connecting Slack Go to **Settings → Integrations → Slack** in the Detail dashboard. Click **Connect** and authorize Detail for your Slack workspace. You'll be redirected to Slack to complete the OAuth flow and grant the necessary permissions. Select the default channel where Detail should post bug notifications and scan summaries. You can change this at any time from the integration settings. ## What gets posted automatically If you configure automatic publishing to Slack, Detail will post the following to your channel of choice: * **New bugs** — includes the bug title, affected file, severity, and a direct link to the full report in the Detail dashboard * **Scan completion summaries** — a brief message after each scan run showing how many new bugs were found across your repositories ## Publishing a bug to Slack manually To share a specific bug with your team, open the bug detail view and click **Send To → Slack**. Select the channel from the dropdown and click **Post**. The message includes the bug title, summary, severity, file location, and a deeplink back to Detail. This is useful for escalating high-severity findings, flagging security vulnerabilities to a dedicated security channel, or sharing context with a specific team. # Overview Source: https://docs.detail.dev/introduction Detail scans your codebase for bugs, security vulnerabilities, dead code, and docs that no longer match the code they describe. ## What Detail finds * **Bugs:** logic errors and other garden variety software defects. * **Security vulnerabilities:** anything a hacker could exploit to gain unauthorized access, e.g. IDORs, SQL injections, incorrect key validation, gaps in your OAuth implementation. * **Dead code:** functions, classes, endpoints, and UI components that are no longer used and can be safely deleted. * **Documentation drift:** READMEs, agent skills, and other internal documentation that have fallen out of sync with the code they describe, silently misleading the agents that rely on them to write your code. * **Rule violations:** a rules engine lets Detail learn patterns specific to your codebase, so recurring categories of bugs can be prevented automatically. ## How it works Connecting your codebase to Detail takes about five minutes. Scans run automatically from that point forward: 1. **Connect GitHub.** Sign in at [app.detail.dev](https://app.detail.dev) with GitHub OAuth and install the Detail GitHub App on the repositories you want to monitor. 2. **Detail scans your code.** Under the hood Detail is setting up your development environment, running code to confirm that bugs are reproducible, and selecting the most severe bugs. This process takes a few hours. 3. **Triage your findings.** Bugs appear in your dashboard and can also be sent to Slack, Linear, Jira, GitHub, or Asana. You can also consume bugs via the Detail CLI, which is particularly handy for fixing bugs in bulk via your agent or factory of choice. Dead code deletion and documentation fixes are sent directly as pull requests and automatically assigned. 4. **Repeat**. As your team ships code, Detail re-scans and surfaces new findings. Detail tracks which bugs you fix and uses this to improve targeting going forward, so you receive a high signal-to-noise stream of bugs. ## Where to go next Connect your first repository start scanning in under five minutes. Learn how Detail's AI scanner identifies bugs and security vulnerabilities in your code. Install the Detail CLI to consume findings and manage rules from the command line. Integrate Detail findings into your own tools using the public REST API. # Quickstart: Set up Detail and find your first bugs Source: https://docs.detail.dev/quickstart Connect your first GitHub repository to Detail and start your first scan in under five minutes. This guide walks you through signing up for Detail, installing the GitHub App, and reviewing the findings from your first scan. By the end, you'll have an initial batch of bugs and security vulnerabilities in your codebase. ## Prerequisites * A GitHub account with access to at least one repository you want to scan. * Access to [app.detail.dev](https://app.detail.dev). Sign up for free if you don't have an account yet. ## Steps Navigate to [app.detail.dev](https://app.detail.dev) and click **Sign in with GitHub**. Detail uses GitHub OAuth; no separate password is required. Once authenticated, Detail creates your account and takes you to the onboarding flow. During onboarding, Detail prompts you to install the Detail GitHub App. Click **Install GitHub App** to open the GitHub App installation page. On that page, choose whether to grant access to **all repositories** or select specific repositories you want Detail to monitor, then click **Install**. GitHub redirects you back to [app.detail.dev](https://app.detail.dev) when installation is complete. You can add or remove repository access at any time in your GitHub organization settings. Back in the Detail UI, select the repositories you want Detail to scan. Your first scan starts shortly after installation and will take a few hours. When it finishes, Detail will email you with findings. You can monitor progress on the **Scans** page in the dashboard. You'll see the scan status update to **Complete** when findings are ready. Navigate to the **Bugs** page in the dashboard. Detail displays a list of findings ordered by when they were introduced, with the newest first. Each finding includes: * **Title:** a concise description of the problem. * **Summary:** a detailed explanation of what the bug is, why it's a problem, and where it lives in your code. * **File path:** the exact location of the bug. * \*\*Commit and Author: \*\*the commit that introduced the issue, and an original author who is likely to have context. You can use the author for routing. * **Security flag:** a badge if the finding is classified as a security vulnerability. Use the **Status** filter to toggle between open, resolved, and dismissed findings. Click any finding from the table to see the full bug contents. From here you can manually share it, copy a fix prompt for your agent of choice, or mark its final status: * **Resolve:** Click \*\*Resolve \*\*once you've fixed the underlying code. Detail records the resolution and removes the finding from your open list. * \*\*Dismiss: \*\*Click **Dismiss** and choose a reason. Add an optional note to leave context for your teammates and for the Detail agent. Dismissed findings are hidden from the default view but remain searchable. If you've sent bugs to Linear, Jira, GitHub, or Asana, resolving the associated ticket will automatically update the status in Detail. ## Next steps You've connected your repository and triaged your first finding. Here's where to go from here: Understand how Detail's AI scanner works and how to tune signal quality for your codebase. Learn how to filter, sort, and bulk-triage findings to keep your bug backlog under control. Install the Detail CLI to trigger scans and review findings without leaving your terminal. Pull findings into your own tooling or automate triage using the Detail public REST API. # How We Protect Your Code Source: https://docs.detail.dev/trust/protect-your-code Detail processes sensitive code, e.g. for banks, healthcare systems, and defense applications, so it's critical that we can do so in a way that merits customer trust. Protecting your source code is a core design constraint of our platform. This page explains how your code is accessed, processed, stored, and safeguarded. ## Access is scoped and controlled by you Detail connects to your repositories through a GitHub App, so access is governed by GitHub's permission model. You select exactly which repositories Detail can see, and you can revoke access at any time from your GitHub settings. For details on the exact read and write permissions Detail requests, see [Connect GitHub repositories to Detail](/integrations/github). ## Your code is processed in isolated, ephemeral environments When Detail investigates a potential bug, it checks out your code into an isolated, sandboxed development environment. Your code is never commingled with other customers' code, and different sandboxes are isolated from each other at the network layer. These environments are ephemeral and are destroyed after analysis. Environment snapshots, which include customer code, are retained for up to 30 days, then deleted. Customer data is encrypted in transit and at rest. ## Your code is never used to train models that could reproduce it Every third-party inference provider that processes your code on our behalf is subject to a zero data retention agreement: providers do not retain snippets of your code after completing a request and are not permitted to use it to train their own models. Detail does not train models that could reproduce or regurgitate your code or IP. We do use usage data – such as which bug reports customers fix or dismiss – to improve how the service prioritizes and presents findings, as described in our [Terms](https://detail.dev/legal/terms). ## Internal access follows least privilege Access to production systems is role-based and restricted to authorized employees with a business need. Production access requires multi-factor authentication over encrypted connections, access rights are reviewed quarterly, and access is revoked promptly when employees depart. All employees undergo background checks and sign confidentiality agreements, as do any third-party contractors who will have any access to customer data. Employees also complete security awareness training during onboarding and annually thereafter. For your own users, Detail supports single sign-on via OIDC and SAML, so you can manage access through your identity provider. See [Set up SSO authentication for Detail](/configuration/sso) for setup instructions. ## Our infrastructure is hardened and monitored Our network is segmented to prevent unauthorized access to customer data and protected by firewalls and intrusion detection. We run vulnerability scans on an ongoing basis with SLA-enforced remediation. We engage an external firm to perform penetration testing at least annually. ## Retention and deletion We retain customer data only as long as necessary to provide the service. Codebase snapshots are deleted within 30 days, and when you leave the service, your data – including source code and anything derived from it – is purged from our environment. ## Independently verified These controls are independently audited: Detail maintains a SOC 2 Type II report covering the security trust services criteria. The full report and our latest penetration test results are available through our [Trust Center](https://trust.detail.dev/). We also maintain a documented incident response plan with defined procedures for notifying affected customers. # Detail dashboard: review, triage, and resolve bugs Source: https://docs.detail.dev/workflow/dashboard Review AI-detected findings, triage bugs by status, track code health metrics, and trigger on-demand scans — all from one central workspace. The Detail dashboard at [app.detail.dev](https://app.detail.dev) is your central workspace for reviewing AI-detected findings, tracking bug status, and managing your repositories. Every scan result lands here first, giving you a single place to decide what gets fixed, dismissed, or escalated. ## Reviewing findings When Detail finishes scanning a repository, all detected bugs appear in a ranked list. Each row shows: * **Title** — a concise AI-generated description of the issue * **File** — the path and line range where the bug lives * **Severity** — how critical the issue is, from low to critical * **Introduced by** — the commit author who added the offending code, derived from `git blame` Click any bug in the list to open the full AI-generated report. The report includes a plain-language explanation of the root cause, the relevant code excerpt, and a suggested fix you can apply directly. Scope the list to a single repo when you're doing focused triage on one project. Show only `pending`, `resolved`, or `dismissed` bugs — or combine statuses. Toggle the **Vulnerabilities only** filter to surface findings flagged as security risks. ## Triaging a bug Once you've read the report for a bug, take one of two actions: Click **Resolve** after you've addressed the issue in your code. Detail marks the bug as `resolved` and removes it from your pending queue. You can reopen a resolved bug at any time if a fix gets reverted. Click **Dismiss** if the finding isn't actionable. You must choose one of the following reasons before the dismissal is saved: | Reason | When to use | | ------------- | ---------------------------------------------------------------- | | **Not a bug** | The AI flagged something that is intentional or correct behavior | | **Won't fix** | The issue is real but your team has decided not to address it | | **Duplicate** | Another finding or ticket already tracks the same issue | | **Other** | Any other reason — add optional notes to explain | Dismissed bugs are suppressed in all future scans for that repository. They won't resurface unless you explicitly reopen them. Dismissals are permanent until manually reopened. If you're unsure whether a finding is valid, consider leaving it as `pending` until you've reviewed the relevant code. ## Stats & reporting The overview section of the dashboard gives you a snapshot of your repository's code health: | Metric | What it means | | ----------------- | ------------------------------------------------------ | | **Total found** | All bugs Detail has ever detected across your repos | | **Outstanding** | Bugs currently in `pending` state that need attention | | **Fixed** | Bugs marked `resolved` | | **Dismissed** | Bugs your team has explicitly closed without fixing | | **Repos covered** | The number of repositories Detail is actively scanning | Track these numbers over time to measure whether your codebase is getting healthier. A growing "outstanding" count alongside a stable "fixed" count is an early signal to increase triage cadence. ## Triggering scans Detail automatically scans your repositories on every push to your primary branch. You can also kick off an on-demand scan at any time: Navigate to the **Repositories** tab and find the repo you want to scan. Click the **Scan Now** button on the repository row. Detail queues the scan immediately. Scan results appear in your findings list within minutes. You'll see new bugs added to the `pending` queue as soon as the scan completes. For bulk triage and automation, use the CLI or the REST API instead of the dashboard. Run `detail bugs list` to pull your pending findings into a terminal workflow, or pipe results into your own scripts. ```bash theme={null} # List all pending bugs for a repository detail bugs list usedetail/my-repo --status pending # Close a specific bug as dismissed detail bugs close bug_abc123 --state dismissed --dismissal-reason not_a_bug ``` # Send Detail bug findings to Linear, Jira, and more Source: https://docs.detail.dev/workflow/publishing Send Detail bug findings to Linear, Jira, Asana, GitHub Issues, Slack, or Email so your team tracks them alongside the rest of your work. Detail can publish bug findings directly to your issue tracker — Linear, Jira, Asana, GitHub Issues, Slack, or Email — so your team sees them alongside other work. Publishing a bug creates a linked issue in the destination tool and keeps status in sync automatically, so you never need to manually update two places. ## Supported destinations Creates a Linear issue in the project you configure. When you mark the Linear issue as done, Detail automatically updates the corresponding bug to `resolved`. Creates a Jira issue in your chosen project. When you close a Jira issue, Detail automatically marks the corresponding bug resolved. Creates an Asana task in your chosen project. When you mark the task complete in Asana, Detail marks the bug resolved. Creates a GitHub issue in the scanned repository or in a separate target repository you configure. Useful for keeping bug tracking inside GitHub. Posts the bug report as a Slack message to a channel you choose. Ideal for alerting your team to new critical findings without leaving their existing workflow. Sends the bug report as an email. Useful for sending security findings to a security team distribution list or for stakeholders who don't use the dashboard. ## Connecting an integration Before you can publish bugs, connect at least one destination in your account settings. In the Detail dashboard, click your organization name in the top navigation, then go to **Settings → Integrations**. Click **Connect** next to the integration you want to enable. You'll be redirected to complete an OAuth flow that authorizes Detail to create issues on your behalf. After authorization, select the default project, workspace, or channel where Detail should publish bugs. You can override this per-bug when publishing. You can connect multiple destinations simultaneously. For example, you might send security vulnerabilities to a private Slack channel and all other bugs to a Linear project. ## Publishing a bug Once an integration is connected, publish any bug directly from the dashboard. Click on any bug in the findings list to open its full report. Click the **Publish** button in the bug detail panel. Choose where to send the bug from the list of connected integrations. If you have a default configured, it's pre-selected — change it here if needed. Click **Publish** to create the issue. Detail links the new issue back to the bug report so you can navigate between them in both tools. After publishing, the linked issue appears in the **Linked Issues** section of the bug detail view, with a direct URL to the created issue. ## Status sync When you update an issue in Linear, Jira, or Asana, Detail reflects that change automatically — no manual updates in the Detail dashboard required. | Action in issue tracker | Effect in Detail | | -------------------------------------------- | --------------------------- | | Mark a Linear issue as done | Bug moves to `resolved` | | Close a Jira issue as resolved | Bug moves to `resolved` | | Complete an Asana task | Bug moves to `resolved` | | Reopen a closed Linear, Jira, or Asana issue | Bug moves back to `pending` | If sync stops working, go to **Settings → Integrations** and click **Reconnect** next to the affected integration to restore it. Status sync is one-directional for Slack and Email — those destinations don't send status updates back to Detail. Resolve or dismiss Slack/Email-published bugs manually in the Detail dashboard. ## Bulk publishing You can publish multiple bugs at once using the bulk actions menu. In the findings list, check the boxes next to the bugs you want to publish, then click **Bulk actions → Publish** at the top of the list. Select your destination and Detail queues all selected bugs for publication in one step.