# Quality suite commands

> Choose between scan, lint, verify, submit, and doctor based on the release question you need to answer.

Canonical: https://hol.org/guard/docs/plugin-scanner/quality-suite-commands · Updated: 2026-10-23 · Applies to: Guard 3.x

`plugin-scanner` has five maintainer and CI commands. Each one answers a different release question. A bare path such as `plugin-scanner .` runs `scan`.

Run `plugin-scanner <command> --help` for the flags in your installed version.

## `scan`

Use `scan` for the weighted summary view:

```bash
plugin-scanner scan ./my-plugin --format json --profile public-marketplace
plugin-scanner scan . --format sarif --output plugin-scanner.sarif
plugin-scanner scan . --min-score 80 --fail-on-severity high
```

`scan` evaluates only the surfaces a plugin actually exposes, then normalizes the final score across applicable checks.

| Flag | Meaning |
| :--- | :--- |
| `--format` | `text` (default), `json`, `markdown`, or `sarif`. `--json` is shorthand for `--format json`. |
| `--output`, `-o` | write the report to a file instead of printing it |
| `--profile` | `default`, `public-marketplace`, or `strict-security` |
| `--config`, `--baseline` | scanner config file and baseline suppression file |
| `--min-score` | exit with an error when the score is below this number (default `0`) |
| `--fail-on-severity` | exit with an error when a finding meets this severity: `none` (default), `critical`, `high`, `medium`, `low`, or `info` |
| `--strict` | exit with an error when any finding is present |
| `--ecosystem` | `auto` (default) or one ecosystem id, see [Ecosystems and repository mode](https://hol.org/guard/docs/plugin-scanner/ecosystems-and-repo-mode) |
| `--cisco-skill-scan`, `--cisco-mcp-scan` | `auto` (default), `on`, or `off` |
| `--cisco-policy` | `permissive`, `balanced` (default), or `strict` |

`scan` exits with status 1 when the score is below `--min-score`, a severity or `--strict` gate trips, or the selected policy profile fails.

## `lint`

Use `lint` for rule-oriented authoring feedback:

```bash
plugin-scanner lint ./my-plugin --list-rules
plugin-scanner lint ./my-plugin --explain README_MISSING
plugin-scanner lint ./my-plugin --fix --profile strict-security
```

`--list-rules` prints one rule per line with its category, default severity, and whether it is fixable. `--explain <rule id>` prints the rule definition as JSON. `--fix` applies safe mechanical fixes to the files before linting and prints each change. `lint` accepts `--format text` or `--format json`, the same policy flags as `scan` (`--profile`, `--config`, `--baseline`, `--strict`), and exits with status 1 when the policy profile fails.

## `verify`

Use `verify` for manifest, marketplace, MCP, skill, app, and asset readiness checks:

```bash
plugin-scanner verify ./my-plugin --format json
plugin-scanner verify . --format json
plugin-scanner verify ./my-plugin --online --format text
```

`verify` accepts `--format text` (default) or `--format json` and exits with status 1 unless every case passes.

MCP checks work like this:

- Remote MCP URLs must use HTTPS, must not embed credentials, and must not point at local or non-public addresses.
- Without `--online`, remote endpoints are recorded as an `offline-skip` and no network request is made.
- With `--online`, the scanner resolves the hostname, requires public addresses, and probes the endpoint over a pinned HTTPS connection with a short timeout. A `2xx` response is reachable. `401` and `403` are recorded as auth required. Redirects are refused.
- Stdio MCP server commands are never executed. Each declared stdio server is recorded as a `safety-skip` case that counts as not passed, so it needs manual review before you trust it.

## `submit`

Use `submit` for one artifact-backed gate before release or ecosystem intake:

```bash
plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plugin-quality.json
```

`submit` runs scan, policy, and verify. It writes the quality artifact to the `--attest` path only when the score meets the minimum, the policy profile passes, and `verify` passes. The minimum is the profile's own minimum score unless you pass `--min-score`. It also accepts `--config`, `--baseline`, and `--online`, and it has no `--format` flag.

`submit` stays single-plugin on purpose so the artifact points at one concrete package. A marketplace root exits with an error. See [Submission and registry payloads](https://hol.org/guard/docs/plugin-scanner/submission-and-registry-payloads) for the artifact shape.

## `doctor`

Use `doctor` for targeted diagnostics or a troubleshooting bundle:

```bash
plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip
```

`--component` is one of `all` (default), `manifest`, `marketplace`, `mcp`, `skills`, `apps`, or `assets`. `doctor` always runs offline. Without `--bundle` it prints the report as JSON. With `--bundle` it writes a zip file that contains:

- `doctor-report.json`
- `environment.txt`, with the working directory, Python version, and OS name
- `workspace-manifest.txt`
- `command-metadata.json`
- `stdout.log`, `stderr.log`, and `timeout-markers.txt`

Read `environment.txt` and the logs before you attach a bundle to a public issue.

## When to use which command

| Command | Best use |
| :--- | :--- |
| `scan` | weighted release summary and policy evaluation |
| `lint` | authoring feedback and safe mechanical fixes |
| `verify` | manifest, marketplace, MCP, and asset readiness checks |
| `submit` | artifact-backed release or submission gate |
| `doctor` | targeted offline diagnostics and support bundles |

## Next guides

- [Ecosystems and repository mode](https://hol.org/guard/docs/plugin-scanner/ecosystems-and-repo-mode)
- [Policies, output, and trust provenance](https://hol.org/guard/docs/plugin-scanner/policies-and-output)
- [Submission and registry payloads](https://hol.org/guard/docs/plugin-scanner/submission-and-registry-payloads)