DevGuard CLI

DevGuard CLI is a local-first developer tool that scans projects for risky code patterns, SQL migration issues, deployment concerns, and configuration problems. It can generate terminal output, JSON, Markdown, HTML reports, and an interactive local report UI.

No login. No backend. No telemetry. No external report upload.

Installation

Install globally:

npm install -g devguardcli

Run without installing:

npx devguardcli scan

After global installation, use the devguard command:

devguard scan

Package name: devguardcli
CLI command: devguard

Quick Start

Scan the current project:

npx devguardcli scan

Export a Markdown report:

npx devguardcli scan --format markdown --output report.md

Export a standalone HTML report:

npx devguardcli scan --format html --output report.html

Launch the local interactive report UI:

npx devguardcli scan --ui

Commands

devguard --help
devguard --version
devguard scan
devguard init
devguard rules
devguard serve
devguard ci
devguard doctor

Scan a Project

devguard scan
devguard scan --path .
devguard scan --path ./my-project

By default, scan prints a console report and writes the latest JSON report to:

.devguard/latest-report.json

Output Formats

DevGuard supports multiple output formats:

devguard scan --format console
devguard scan --format json
devguard scan --format markdown
devguard scan --format html

Write output to a specific file:

devguard scan --format markdown --output devguard-report.md
devguard scan --format html --output devguard-report.html
devguard scan --format json --output devguard-report.json

JSON Output

JSON output is designed for editor integrations, CI pipelines, and future automation.

devguard scan --format json

Example shape:

{
  "tool": "devguard",
  "version": "0.1.0",
  "generatedAt": "2026-04-26T00:00:00.000Z",
  "projectPath": "/path/to/project",
  "riskScore": 82,
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 1,
    "low": 0,
    "info": 0
  },
  "stats": {
    "filesScanned": 120,
    "rulesRun": 25,
    "durationMs": 840
  },
  "findings": [
    {
      "id": "sql-unsafe-query",
      "title": "Unsafe SQL query pattern detected",
      "severity": "high",
      "file": "src/db/query.ts",
      "line": 12,
      "column": 4,
      "message": "Potentially unsafe SQL query construction was detected.",
      "recommendation": "Use parameterized queries or prepared statements.",
      "ruleCategory": "sql"
    }
  ]
}

Markdown Reports

Generate a Markdown report:

devguard scan --format markdown --output report.md

Markdown reports are useful for:

• Pull request comments
• GitHub issue attachments
• Documentation
• CI artifacts
• Team review notes

HTML Reports

Generate a standalone HTML report:

devguard scan --format html --output report.html

The HTML report includes embedded CSS, JavaScript, and report data. It does not require external CDNs, analytics, authentication, or network access.

You can open the generated file directly in your browser.

Local Report UI

Launch an interactive local report dashboard:

devguard scan --ui

This will:

1. Scan the project.
2. Write .devguard/latest-report.json.
3. Write .devguard/latest-report.html.
4. Start a local server.
5. Open the report UI in your browser.

Default URL:

http://localhost:4827

You can also serve an existing report:

devguard serve

Serve a specific report file:

devguard serve --report .devguard/latest-report.json

Use a custom port:

devguard serve --port 4828

Start the server without opening the browser:

devguard serve --no-open

The local UI includes:

• Risk score summary
• Severity counts
• Findings list
• Search
• Severity filters
• Category filters
• File filters
• Sort controls
• Expandable finding details
• Copyable recommendations
• JSON and Markdown export actions

CI Usage

Run DevGuard in CI mode:

devguard ci

By default, CI mode fails on high-severity findings.

Fail on high or critical findings:

devguard ci --fail-on high

Fail on medium, high, or critical findings:

devguard ci --fail-on medium

Write a CI report:

devguard ci --format json --output devguard-report.json

Example GitHub Actions step:

- name: Run DevGuard
  run: npx devguardcli ci --fail-on high

Configuration

Create a default config file:

devguard init

This creates:

devguard.config.json

Default config:

{
  "ignore": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "coverage/**"
  ],
  "rules": {}
}

Example custom config:

{
  "ignore": ["generated/**", "vendor/**"],
  "rules": {
    "sql-unsafe-query": "error",
    "migration-no-rollback": "warn"
  }
}

Force overwrite an existing config:

devguard init --force

Rules

List available rules:

devguard rules

Output rule metadata as JSON:

devguard rules --format json

Rule metadata includes:

• Rule ID
• Title
• Category
• Default severity
• Description

Doctor

Check your local DevGuard setup:

devguard doctor

The doctor command prints:

• DevGuard version
• Node.js version
• Platform
• Current working directory
• .devguard write status
• Config file status
• Latest report status

Common Examples

Scan current folder:

npx devguardcli scan

Scan another project:

npx devguardcli scan --path ../my-app

Generate Markdown:

npx devguardcli scan --format markdown --output report.md

Generate HTML:

npx devguardcli scan --format html --output report.html

Open interactive UI:

npx devguardcli scan --ui

Run in CI:

npx devguardcli ci --fail-on high

Local-First Design

DevGuard CLI runs locally on your machine.

It does not:

• Require an account
• Require a hosted backend
• Upload scan results
• Use telemetry
• Send project data to external services
• Require internet access at runtime

Package Safety

The npm package is designed to publish only the files needed to run the CLI.

Before publishing, preview package contents:

pnpm build
pnpm test
pnpm typecheck
npm pack --dry-run

The package should only include build output and public package documents such as:

dist
README.md
CHANGELOG.md
LICENSE
package.json

Development

Install dependencies:

pnpm install

Build:

pnpm build

Run tests:

pnpm test

Typecheck:

pnpm typecheck

Run locally after build:

node dist/index.js scan

Link locally for global testing:

npm link
devguard --help
devguard scan

Publishing

Publish to npm:

npm publish

For this package name, users can run:

npx devguardcli scan

or install globally:

npm install -g devguardcli
devguard scan

Roadmap

• Add more framework-specific rules
• Add richer per-rule configuration
• Add SARIF output for security tooling
• Add GitHub Actions examples
• Add more SQL migration checks
• Add Cloudflare/D1-specific rules
• Add dependency and environment risk checks
• Improve local report UI filtering and visualizations

License

MIT License

Copyright (c) 2026 Dharsan Guruparan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.