<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# CLI Reference

```
skillsaw [command] [options]
```

## `skillsaw lint`

Lint agent skills, plugins, and AI coding assistant context

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file (default: auto-discover from the first path) |  |
| `-v`, `--verbose` | Show info-level messages |  |
| `--strict` | Treat warnings as errors (equivalent to --fail-on warning; overrides the config file's strict/fail-on settings) |  |
| `--fail-on` | Fail on violations at this severity or above (default: error; --strict is equivalent to --fail-on warning). Overrides the config file's strict/fail-on settings. (choices: error, warning, info) |  |
| `--format` | Output format for stdout (default: text) (choices: text, json, sarif, html, code-climate, gitlab) | `text` |
| `--output` | Write output to FILE. Format is inferred from extension (.htm, .html, .json, .sarif, .txt) or set explicitly with a FORMAT: prefix (e.g. gitlab:report.json). Use the prefix when an extension is ambiguous (e.g. .json could be json or gitlab/code-climate). Can be specified multiple times. |  |
| `--type` | Replace packaging-type detection (repeatable). Tool types are always detected from the checkout, and plugin-contributed types too. Values: single-plugin, marketplace, agentskills, dot-claude, coderabbit, apm, promptfoo, codex-plugin, codex-marketplace, codex-project, agent-plugin, mcp-registry, cursor, copilot, cline, devin, opencode, muse, grok-project, grok-plugin, grok-marketplace, kiro, gemini, qwen, agents-md, claude-md, skills-lock, antigravity-plugin, antigravity. |  |
| `--rule` | Only run these rules and their validation dependencies (repeatable). Config still comes from .skillsaw.yaml. |  |
| `--skip-rule` | Skip these rules (repeatable). Cannot be combined with --rule. |  |
| `--no-baseline` | Ignore baseline file even if .skillsaw-baseline.json exists |  |
| `--no-custom-rules` | Skip custom rules defined in .skillsaw.yaml (recommended for CI on untrusted PRs) |  |
| `--no-plugins` | Skip rules from installed plugin packages (skillsaw.plugins entry points) |  |
| `--no-progress` | Disable the interactive per-rule progress indicator (auto-disabled when stderr is not a terminal) |  |
| `--color`, `--no-color` | Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored. |  |

### Path arguments

`lint` and `fix` accept files as well as directories. A file resolves
to the directory that owns it — never further out, so `lint` reads and
`fix` writes only under the path you named. Manifest rules discover
from a plugin's root, so to run them name the plugin's root directory
rather than a manifest file inside it. Duplicate paths and paths
nested inside another named path are dropped.

## `skillsaw fix`

Automatically fix lint violations

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file (default: auto-discover from the first path) |  |
| `--dry-run` | Preview fixes without writing changes |  |
| `--suggest` | Also apply suggested fixes (not just safe ones) |  |
| `--rule` | Only run these rules and their validation dependencies (repeatable). Config still comes from .skillsaw.yaml. |  |
| `--skip-rule` | Skip these rules (repeatable). Cannot be combined with --rule. |  |
| `--no-custom-rules` | Skip custom rules defined in .skillsaw.yaml (recommended for CI on untrusted PRs) |  |
| `--no-plugins` | Skip rules from installed plugin packages (skillsaw.plugins entry points) |  |
| `--no-progress` | Disable the interactive per-rule progress indicator (auto-disabled when stderr is not a terminal) |  |
| `--color`, `--no-color` | Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored. |  |

## `skillsaw init`

Generate a default .skillsaw.yaml config file

## `skillsaw feedback`

Create a local diagnostic bundle for a bug report

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file to copy into the bundle verbatim (default: auto-discover only; review it for secrets yourself) |  |
| `-o`, `--output` | Bundle ZIP path (default: .skillsaw-feedback/ under the repository) |  |
| `--message` | Short description of the problem to include in the bundle |  |
| `--include` | Copy a repository-relative UTF-8 text file into the bundle verbatim (repeatable; review it for secrets yourself) |  |
| `--max-file-bytes` | Maximum raw bytes per --include/--config file (positive integer; default: 4194304 / 4 MiB) | `4194304` |
| `--max-total-bytes` | Maximum retained --include/--config bytes across distinct ZIP members (positive integer; default: 16777216 / 16 MiB) | `16777216` |
| `--with-extensions` | Run custom and installed plugin rules in the diagnostic lint run |  |
| `--json` | Print the bundle result as JSON for agents and automation |  |

## `skillsaw list-rules`

List all available builtin and plugin rules

## `skillsaw plugins`

List installed rule plugins and the rules they provide

## `skillsaw explain`

Show documentation and effective configuration for a rule

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file (default: auto-discover) |  |
| `--color`, `--no-color` | Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored. |  |
| `--pager`, `--no-pager` | Use a pager (e.g. less) to display documentation (default: auto when tty present) |  |

## `skillsaw docs`

Deprecated: generate repository documentation

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file (default: auto-discover) |  |
| `--format` | Output format (default: html) (choices: html, markdown) | `html` |
| `-o`, `--output` | Output file or directory (default: skillsaw-docs/). If it ends with .html/.md, writes a single file directly. |  |
| `--title` | Custom title for the documentation |  |
| `--theme` | Color theme for HTML output. Presets: indigo (default), forest-green, ocean-blue, sunset-orange, royal-purple, crimson-red. |  |

## `skillsaw port`

Port Claude Code and Codex plugins to Agent Plugins v1 packages

| Flag | Description | Default |
|------|-------------|---------|
| `--to` | Target format (default and currently only: agent-plugin) | `agent-plugin` |
| `-c`, `--config` | Path to .skillsaw.yaml config file (default: auto-discover from the path) |  |
| `--marketplaces` | Comma-separated marketplace catalogs to generate for the ported plugins so catalog-driven clients can discover them (default: codex; use 'none' to skip) | `codex` |
| `--dry-run` | Show the files that would be written without writing them |  |
| `--no-progress` | Disable the interactive conversion progress indicator (auto-disabled when stderr is not a terminal) |  |
| `--color`, `--no-color` | Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored. |  |

## `skillsaw tree`

Display the repository lint tree

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file |  |
| `--format` | Output format (default: text) (choices: text, dot) | `text` |

## `skillsaw baseline`

Generate or update the baseline file from current violations

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file |  |
| `--include-info` | Include INFO findings (automatic with fail-on: info in config) |  |
| `--no-custom-rules` | Skip custom rules defined in .skillsaw.yaml (recommended for untrusted repositories) |  |
| `--no-plugins` | Skip rules from installed plugin packages (skillsaw.plugins entry points) |  |

## `skillsaw badge`

Grade the repository and write a shields.io badge JSON file

| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--config` | Path to .skillsaw.yaml config file (default: auto-discover) |  |
| `-o`, `--output` | Badge JSON output path (default: .skillsaw-badge.json in the repository root) |  |
| `--large` | Also render a self-contained SVG report card (.skillsaw-card.svg) next to the badge JSON |  |
| `--theme` | Report card color theme, used with --large (default: dark) (choices: light, dark) | `dark` |
| `--no-custom-rules` | Skip custom rules defined in .skillsaw.yaml (recommended for untrusted repositories) |  |
| `--no-plugins` | Skip rules from installed plugin packages (skillsaw.plugins entry points) |  |
| `--color`, `--no-color` | Force ANSI colors and terminal hyperlinks on (--color) or off (--no-color). Default: color only when stdout is a terminal; FORCE_COLOR and NO_COLOR are also honored. |  |

## `skillsaw add`

Deprecated: scaffold marketplaces, plugins, and components

### `skillsaw add marketplace`

Initialize a new marketplace

| Flag | Description | Default |
|------|-------------|---------|
| `--name` | Marketplace name |  |
| `--owner` | Owner name (e.g., GitHub username) |  |
| `--github-repo` | GitHub repository (owner/repo) |  |
| `--color-scheme` | Color scheme preset (choices: forest-green, ocean-blue, sunset-orange, royal-purple, crimson-red) |  |
| `--type` | Marketplace type (default: claude-code) (choices: claude-code) | `claude-code` |
| `--no-example-plugin` | Do not create the example plugin |  |
| `--interactive` | Prompt for missing values interactively |  |

### `skillsaw add plugin`

Add a new plugin

| Flag | Description | Default |
|------|-------------|---------|
| `--path` | Marketplace root path |  |

### `skillsaw add skill`

Add a skill to a plugin

| Flag | Description | Default |
|------|-------------|---------|
| `--plugin` | Target plugin name (auto-detected if unambiguous) |  |
| `--path` | Marketplace root path |  |

### `skillsaw add command`

Add a command to a plugin

| Flag | Description | Default |
|------|-------------|---------|
| `--plugin` | Target plugin name (auto-detected if unambiguous) |  |
| `--path` | Marketplace root path |  |

### `skillsaw add agent`

Add an agent to a plugin

| Flag | Description | Default |
|------|-------------|---------|
| `--plugin` | Target plugin name (auto-detected if unambiguous) |  |
| `--path` | Marketplace root path |  |

### `skillsaw add hook`

Add a hook to a plugin

| Flag | Description | Default |
|------|-------------|---------|
| `--plugin` | Target plugin name (auto-detected if unambiguous) |  |
| `--path` | Marketplace root path |  |

## Color and hyperlinks

Commands that produce terminal output (`lint`, `fix`, `explain`, `badge`)
decide whether to emit ANSI colors with the standard cascade, strongest
first:

1. `--color` / `--no-color`
2. `FORCE_COLOR` — a non-empty value forces color on even through a pipe
   (`0` forces it off); useful in CI logs that render ANSI
3. `NO_COLOR` — present (even empty) disables color
4. Otherwise color is used only when stdout is a terminal

Piped or redirected output is plain text by default. When color is
enabled on a real terminal (`TERM` other than `dumb`), text output also
emits [OSC 8
hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda):
rule ids link to their documentation pages, file paths become clickable
`file://` links, and the per-rule "Rule docs" URL footer collapses to a
one-line hint. Hyperlinks are never emitted through a pipe, even when
color is forced.