docs: add CLI reference and refresh JSON output docs#404
Open
SH4DY wants to merge 6 commits into
Open
Conversation
Document all commands, flags, and environment variables in one place, and link to it from the existing docs index. Co-authored-by: Cursor <cursoragent@cursor.com>
Refresh naming, schema fields, failure codes, and CI guidance to match the current CLI. Co-authored-by: Cursor <cursoragent@cursor.com>
SH4DY
force-pushed
the
cursor/cli-reference-docs
branch
from
July 17, 2026 11:26
011684f to
b7ead12
Compare
Link the extension repo, document auth once at section level, and spell out when Evo upload is configured. Co-authored-by: Cursor <cursoragent@cursor.com>
SH4DY
marked this pull request as ready for review
July 17, 2026 14:02
PR Summary by QodoDocs: add CLI reference and refresh JSON output documentation
AI Description
Diagram
High-Level Assessment
Files changed (5)
|
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
Comment on lines
+114
to
+123
| | `--ci` | boolean | `false` | Exit with code **1** if any analysis issues or runtime failure codes remain after the scan. Requires `--dangerously-run-mcp-servers` in non-interactive environments. | | ||
| | `--ignore-issues-codes CODES` | string | — | Comma-separated issue/failure codes to ignore for `--ci` exit status (e.g. `W001,W015,X001`). **Only valid with `--ci`.** Ignored codes are also removed from JSON output in CI mode. | | ||
|
|
||
| **Exit codes (scan / inspect with `--ci`):** | ||
|
|
||
| | Code | Meaning | | ||
| | --- | --- | | ||
| | `0` | Success; no remaining issues or failures (after ignores) | | ||
| | `1` | `--ci`: findings or unignored runtime failures present | | ||
| | `2` | Invalid flag combination (e.g. `--ignore-issues-codes` without `--ci`, or `--ci` without `--dangerously-run-mcp-servers`) | |
There was a problem hiding this comment.
Inconsistent --ci and --dangerously-run-mcp-servers requirement.
Line 114 states: "Requires --dangerously-run-mcp-servers in non-interactive environments" (conditional requirement).
But line 123 states exit code 2 occurs for: "--ci without --dangerously-run-mcp-servers" (unconditional requirement, no environment qualifier).
This contradiction will confuse users about whether the flag is:
- Always required with
--ci(exit code 2 suggests this) - Only required in non-interactive environments (line 114 suggests this)
Fix: Clarify the requirement consistently. If --dangerously-run-mcp-servers is only required in non-interactive environments, line 123 should read:
| `2` | Invalid flag combination (e.g. `--ignore-issues-codes` without `--ci`, or `--ci` in non-interactive mode without `--dangerously-run-mcp-servers`) |Or if it's always required, line 114 should remove "in non-interactive environments".
Suggested change
| | `--ci` | boolean | `false` | Exit with code **1** if any analysis issues or runtime failure codes remain after the scan. Requires `--dangerously-run-mcp-servers` in non-interactive environments. | | |
| | `--ignore-issues-codes CODES` | string | — | Comma-separated issue/failure codes to ignore for `--ci` exit status (e.g. `W001,W015,X001`). **Only valid with `--ci`.** Ignored codes are also removed from JSON output in CI mode. | | |
| **Exit codes (scan / inspect with `--ci`):** | |
| | Code | Meaning | | |
| | --- | --- | | |
| | `0` | Success; no remaining issues or failures (after ignores) | | |
| | `1` | `--ci`: findings or unignored runtime failures present | | |
| | `2` | Invalid flag combination (e.g. `--ignore-issues-codes` without `--ci`, or `--ci` without `--dangerously-run-mcp-servers`) | | |
| | `--ci` | boolean | `false` | Exit with code **1** if any analysis issues or runtime failure codes remain after the scan. Requires `--dangerously-run-mcp-servers` in non-interactive environments. | | |
| | `--ignore-issues-codes CODES` | string | — | Comma-separated issue/failure codes to ignore for `--ci` exit status (e.g. `W001,W015,X001`). **Only valid with `--ci`.** Ignored codes are also removed from JSON output in CI mode. | | |
| **Exit codes (scan / inspect with `--ci`):** | |
| | Code | Meaning | | |
| | --- | --- | | |
| | `0` | Success; no remaining issues or failures (after ignores) | | |
| | `1` | `--ci`: findings or unignored runtime failures present | | |
| | `2` | Invalid flag combination (e.g. `--ignore-issues-codes` without `--ci`, or `--ci` in non-interactive mode without `--dangerously-run-mcp-servers`) | | |
Spotted by Graphite
Is this helpful? React 👍 or 👎 to let us know.
Code Review by Qodo
Context used✅ Compliance rules (platform):
8 rules 1. Shell injection example
|
![qodo-merge-etso[bot]](https://avatars.githubusercontent.com/u/12959162?s=60&v=4){kind=small}
Comment on lines
+271
to
+275
| function checkAgentScan(targetPath) { | ||
| const scanOutput = execSync( | ||
| `uvx snyk-agent-scan@latest --json ${JSON.stringify(targetPath)}`, | ||
| { encoding: "utf8" } | ||
| ); |
There was a problem hiding this comment.
1. Shell injection example 🐞 Bug ⛨ Security
The Node.js integration snippet constructs an execSync shell command by interpolating targetPath, so shell expansions like $()/backticks in the path can execute arbitrary commands if targetPath is derived from untrusted input. This is a copy-paste RCE footgun in the documentation.
Agent Prompt
### Issue description
The Node.js example uses `execSync()` with a single interpolated command string, which passes through a shell and can allow command substitution if `targetPath` contains `$()` or backticks.
### Issue Context
This is documentation intended for copy/paste into automation; it should demonstrate a safe invocation pattern (no shell).
### Fix
Update the snippet to use `execFileSync`/`spawnSync` (or `execSync` with a pre-escaped argument) with an argument array, e.g.:
```js
const { execFileSync } = require("child_process");
const scanOutput = execFileSync(
"uvx",
["snyk-agent-scan@latest", "--json", targetPath],
{ encoding: "utf8" }
);
```
### Fix Focus Areas
- docs/json-output.md[266-275]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+128
to
+144
| ### Runtime failure codes (`X*`) | ||
|
|
||
| Operational failures map to `X*` codes (via `error.category`, or occasionally in `issues`): | ||
|
|
||
| | Code | Category | Typical `is_failure` | | ||
| | --- | --- | --- | | ||
| | `X001` | `server_startup` | true | | ||
| | `X002` | `skill_scan_error` | true | | ||
| | `X003` | `file_not_found` | false | | ||
| | `X004` | `unknown_config` | false | | ||
| | `X005` | `parse_error` | true | | ||
| | `X006` | `server_http_error` | true | | ||
| | `X007` | `analysis_error` | true | | ||
| | `X008` | (uncategorized) | true | | ||
| | `X009` | `user_declined` | true | | ||
| | `X010` | `skipped_by_runtime_config` | true | | ||
|
|
There was a problem hiding this comment.
2. Nonexistent x010 code 🐞 Bug ≡ Correctness
The JSON output docs list an X010 runtime failure code (skipped_by_runtime_config), but the runtime failure-code mapping only defines X001–X009 and has no such category. Consumers following the docs will implement handling for a code the CLI cannot emit.
Agent Prompt
### Issue description
Docs claim an `X010` runtime failure code, but the implementation's failure-category enum/mapping does not include it.
### Issue Context
Runtime failure codes are derived from `ScanError.category` via `FAILURE_CATEGORY_TO_CODE`.
### Fix
Either:
1) Remove `X010` from the documentation (recommended if not actually emitted), or
2) Add a `skipped_by_runtime_config` category and map it to `X010` in the runtime, and ensure it is actually produced in relevant code paths.
### Fix Focus Areas
- docs/json-output.md[128-144]
- src/agent_scan/models.py[24-48]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+114
to
+115
| | `--ci` | boolean | `false` | Exit with code **1** if any analysis issues or runtime failure codes remain after the scan. Requires `--dangerously-run-mcp-servers` in non-interactive environments. | | ||
| | `--ignore-issues-codes CODES` | string | — | Comma-separated issue/failure codes to ignore for `--ci` exit status (e.g. `W001,W015,X001`). **Only valid with `--ci`.** Ignored codes are also removed from JSON output in CI mode. | |
There was a problem hiding this comment.
3. Ci requirement misdocumented 🐞 Bug ≡ Correctness
The CLI reference says --ci requires --dangerously-run-mcp-servers only in non-interactive environments, but the CLI enforces this requirement unconditionally and exits with code 2 otherwise. Users may rely on the docs and hit unexpected failures when running --ci locally.
Agent Prompt
### Issue description
Docs state `--ci` requires `--dangerously-run-mcp-servers` only in non-interactive environments, but the implementation exits(2) for any `--ci` run without `--dangerously-run-mcp-servers`.
### Issue Context
`enforce_consent_requirements()` is called for every invocation before dispatch.
### Fix
Update the `--ci` flag description to match the runtime behavior (i.e., always requires `--dangerously-run-mcp-servers`), or change the implementation to only enforce the requirement when the run is non-interactive.
### Fix Focus Areas
- docs/cli-reference.md[110-115]
- src/agent_scan/cli.py[417-433]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
hemang-snyk
approved these changes
Jul 20, 2026
Clarify that --no-skills is the meaningful opt-out and remove redundant --skills from examples. Co-authored-by: Cursor <cursoragent@cursor.com>
mmilanta
reviewed
Jul 20, 2026
| | `error` | object \| null | Path-level error when discovery/parsing failed for this path. See [Execution failures](#1-checking-for-execution-failures). | | ||
| | `servers` | array \| null | Inspected MCP servers and skills. `null` when the config could not be read at all. | | ||
| | `issues` | array | Security findings from analysis (`E*`, `W*`). Empty in `inspect` mode. | | ||
| | `labels` | array | Per-tool risk label scores from analysis (MCP scans). Often empty for skills-only paths. | |
Contributor
There was a problem hiding this comment.
Labels are discontinued already. I do not remember if the list is empty, or just 0s, anyway not important
mmilanta
requested changes
Jul 20, 2026
| | --- | --- | --- | | ||
| | `code` | string | Finding code (e.g. `E001`, `W015`). See [Issue codes](issue-codes.md). | | ||
| | `message` | string | Human-readable description. | | ||
| | `reference` | array \| null | `(server_index, entity_index)` into `servers` / entity lists, or `[server_index, null]` for server-scoped issues. | |
Contributor
There was a problem hiding this comment.
Maybe we should mention that server really means server or skills
Contributor
There was a problem hiding this comment.
And that entity means tool/file
Mark labels as deprecated placeholders and clarify reference indices mean server-or-skill and tool-or-file. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/cli-reference.md— full reference for standalonesnyk-agent-scanandsnyk agent-scan --experimental(commands, flags, env vars, exit codes, handshake/consent matrix).docs/json-output.mdfor currentsnyk-agent-scannaming, JSON schema, runtime failure codes (X001–X010), and native--ciguidance.docs/scanning.mdwith links to the new reference.--no-uploadonly skips the push.Test plan
docs/cli-reference.mdScanPathResult/ServerScanResultmodelscli-extension-agent-scan