Shadscan CLI

Usage

shadscan [path] [options]

The optional path defaults to the current directory. Pass a relative or absolute path to scan another project.

Run with an AI agent (recommended)

Audit this project's UI with shadscan — a deterministic auditor for React shadcn apps that flags accessibility, state, form, and composition issues.

From the repo root, generate the agent handoff:
npx @shadscan/cli --prompt

The handoff groups findings into fix, decide, and verify work items with evidence and acceptance criteria. Then, without editing any code yet:
1. Summarize the work items by severity, and point out the files with the most issues.
2. Propose a prioritized remediation plan from the fix items, and list every decide item as a question for me rather than a task.
3. Stop and share the plan so I can review it, and wait for my approval before changing anything.

The recommended way to start is to hand the audit to your AI coding agent. Copy the prompt above and paste it in — it runs Shadscan, then, without editing any code, summarizes the findings by severity and proposes a prioritized remediation plan for you to approve before anything changes.

Hand the results off to an agent

$ pnpm dlx @shadscan/cli --prompt

After a scan, --prompt turns the results into a paste-ready Markdown handoff: the exact findings with evidence, suggested fixes, acceptance criteria, and the rescan command. Paste it into Claude Code, Codex, or any coding agent — or skip the paste entirely with --apply, which launches an installed agent with the same handoff.

A handoff works better than a "fix my UI" prompt because the agent starts from deterministic evidence instead of rediscovering problems: every task is scoped to a real finding, has acceptance criteria to meet, and ends with the exact command that verifies the fix. The same source always produces the same handoff, so agent sessions stay reproducible and reviewable.

To get the most out of a handoff:

• Start from a clean working tree, so the agent's diff contains nothing but remediation and stays easy to review.
• Narrow big audits with --category or a path — one focused session per category beats one sprawling session that loses context.
• Have the agent propose a plan before editing, and approve it first — the recommended prompt above already insists on this.
• When the agent says it is done, rescan. The score is the acceptance test, and --fail-under makes it a CI gate so regressions cannot merge.

Scan another directory

$ pnpm dlx @shadscan/cli ../my-shadcn-app

The default human report leads with an overall progress bar, then includes category scores, evidence, fixes, and agent-ready actionables. Local TTYs receive a width-aware Unicode and color bar; CI and redirected output receive a deterministic ASCII fallback with color disabled by default. NO_COLOR always wins, while FORCE_COLOR can color that fallback. Roast copy is enabled for local human output and disabled automatically in CI.

Options

[path]

Project directory to scan. Relative paths resolve from the current directory. Defaults to .

--format <format>

Choose human, json, or prompt output. Human output is the default.

--prompt

Print only a neutral, paste-ready Markdown prompt for an AI coding agent.

--json

Print the complete machine-readable audit report. Alias for --format json.

--apply

Validate and open an installed coding-agent CLI with the generated remediation prompt. Local interactive terminals only.

--agent <agent>

Choose claude, codex, or grok for --apply. Without it, choose a matching PATH candidate to validate and launch.

--fail-under <score>

Exit with status 1 when the score is below an integer from 0 to 100, or is unassessed.

--category <category>

Run only one audit category.

--no-roast

Keep human-readable findings neutral.

--roast

Include roast copy in CI or JSON output.

--no-interactive

Disable the local post-scan menu and all Shadscan follow-up prompts.

--help

Print command usage and all available options.

--version

Print the installed Shadscan version.

Categories are foundation, interaction, states, accessibility, forms, and production-polish. The --prompt and --json aliases cannot be combined with each other or with --format. --apply requires human output, and --agent requires --apply.

Create an agent prompt

$ pnpm dlx @shadscan/cli --prompt

--prompt is an alias for --format prompt. It prints only neutral Markdown that you can paste into an AI coding agent. This output mode does not call an AI model itself.

The generated prompt contains:

• The repository identity, score, and exact ruleset version.
• Grouped fixes, product decisions, and manual verification work.
• Evidence, suggested fixes, and acceptance criteria.
• Detected project gates and the exact rescan command.

Add a path or category before the flag to narrow the handoff, for example ../my-app --category accessibility --prompt.

Apply with an installed agent

$ pnpm dlx @shadscan/cli --apply --agent codex

--apply prints the report, creates the same neutral remediation prompt, and opens Claude Code, Codex CLI, or Grok Build in the package-manager root. Omit --agent to choose from the matching candidates Shadscan finds on PATH. The selected provider is validated before launch.

Agent launch is disabled in CI and when the input, output, or error stream is not an interactive terminal. Shadscan rejects project-local executables, checks the provider identity, launches with an argument array and no user-controlled shell command or approval-bypass flags, and removes its private prompt file when the agent exits.

The external agent may read and edit files, run commands, and send prompt data to its provider. A failed agent exits non-zero and can never clear a failed --fail-under gate.

Use JSON and score gates

Read the complete report

$ pnpm dlx @shadscan/cli --json

JSON output includes the score, category summaries, every rule result, and agentHandoff. The current audit schema version is 4.

Fail CI below a score

$ pnpm dlx @shadscan/cli --json --fail-under 80

Findings normally exit with status 0. With --fail-under, Shadscan exits with status 1when the score is below the floor or cannot be assessed. Discovery and audit failures also exit with status 1.

Run one category

$ pnpm dlx @shadscan/cli --category accessibility

Audit every push with the GitHub Action

The shadscan repository doubles as a composite GitHub Action. It runs the CLI against your project, writes the score and category table to the job summary, optionally fails the job below a score floor, and can keep a single tracked issue up to date with the findings and a paste-ready agent handoff.

name: shadscan
on:
  push:
    branches: [main]

permissions:
  contents: read
  issues: write # only needed with create-issue

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: TheOrcDev/shadscan@main
        with:
          path: .
          version: 0.1.0 # pin an exact CLI version
          fail-under: "80"
          create-issue: "true"

Inputs: path, version, category, fail-under, create-issue, issue-label, and github-token. Outputs: score, grade, and report-path for downstream steps. Pin an exact CLI version in CI — a moving dist-tag is not a reproducible build input.

With create-issue enabled, the action needs the issues: write permission. Instead of filing a new issue on every run, it updates one open issue per label, and the issue body embeds the same --prompt handoff you would generate locally — assign the issue to your coding agent and the remediation plan is already inside it.

Add a pre-commit score gate

A local interactive scan ends with a post-scan menu: copy the agent handoff to your clipboard (it prints too), print it without copying, launch an installed agent, or add a score gate when no active blocking Shadscan hook protects the project yet. Pick with the arrow keys and Enter — the handoff is highlighted first, so a single Enter grabs it. Press Esc to keep just the score, or use --no-interactive to suppress the menu entirely. Category-scoped scans do not offer a hook because their score cannot establish a full-project floor.

Preview the exact hook plan

$ pnpm dlx @shadscan/cli setup --pre-commit --dry-run

Apply a reviewed plan without another prompt

$ pnpm dlx @shadscan/cli setup --pre-commit --yes

The plan pins the exact Shadscan version and uses the current complete assessed score as its --fail-under floor. Shadscan can safely create or extend simple native Git hooks using POSIX sh or dash. It preserves existing commands, never executes the hook, and gives manual instructions for Husky, Lefthook, simple-git-hooks, pre-commit, conflicting managers, other shell interpreters, and opaque native hooks.

Run it before agent commits

The optional shadscan-pre-commit skill establishes a baseline and requires AI agents to rerun the audit immediately before every commit. It adds no Git hook or project dependency; use shadscan setup --pre-commit when you want an actual repository hook.

$ pnpm dlx skills add TheOrcDev/skills --skill shadscan-pre-commit --global

Use $shadscan-pre-commit for this task. Establish the current score before editing, run Shadscan immediately before every commit, and do not commit if the audit is unassessed or below the task floor.

Make it a project rule

Add this policy to AGENTS.md, or the equivalent instruction file for your agent, to activate the skill for future commit tasks.

## Shadscan

Before creating any commit, use $shadscan-pre-commit. Establish the current score when work begins, run Shadscan immediately before each commit, and do not commit if the score is unassessed or below the task floor.

Troubleshooting

An older version runs right after a release

pnpm 11.15 and newer delays newly published versions through its minimumReleaseAge supply-chain setting, so pnpm dlx @shadscan/cli can silently resolve to the previous release for a few days after a new one ships. Pin the exact version (@shadscan/cli@<version>) to run it immediately, or wait for the delay to pass.

A stale version keeps running

One-shot runners cache downloads. If an old version persists after an update, pin the exact version, or clear the cache: npx --yes forces a fresh resolution and pnpm store prune drops unreferenced packages. Check what actually ran with --version.