Periderm CLI

The easiest way to install Periderm CLI is using our installation script:

Alternative (NPM):

Verify Installation:

Prereqs: Node 18+ (for CLI). Flutter/Swift developers can use the install script or dashboard web scan without npm.

Updating

To update Periderm CLI to the latest version, run the update command:

The CLI will automatically notify you when a new update is available in the npm registry.

periderm scan requires a linked account. Run login once from any terminal:

Your browser opens the dashboard CLI login page. After you approve the device, the CLI stores your token locally. Check the session anytime with periderm whoami.

From the project you want to check:

cd ~/path/to/your-project
periderm scan

You get a terminal verdict plus report files at:

.periderm/last-report.md
.periderm/last-report.json

Scans upload to your dashboard by default. The CLI shows each file as it scans, detects your project type (web, mobile, monorepo), and filters findings that don't apply to admin/internal surfaces.

No CLI? Open your dashboard and click run scan to pick a folder or upload a zip.

Admin dashboard in the same repo? Add .periderm/context.json:

{
  "profile": "monorepo",
  "internal_globs": ["**/_authenticated/**", "**/admin/**"]
}

Scan the current directory, upload results to your Periderm dashboard, and write .periderm/last-report.md and .periderm/last-report.json. Requires login.

Scan a directory other than the current working directory.

Scale/Unlimited. AI agent review for edge cases static checks miss. Appends to your last report.

Link the CLI to your Periderm account via browser.

Clear the locally stored CLI token.

Print API URL, user id, plan, and remaining scan quota.

Re-run scans on file change (no login required; no report files written).

Supported file types

.js, .jsx, .ts, .tsx, .mjs, .cjs, .dart, .swift

Project context

Periderm uses route structure + optional AI classification to skip legal, SEO, and accessibility checks on internal admin surfaces. Override with .periderm/context.json in your repo root.

When viewing scan reports in the dashboard, you may notice a string like 1c 5h · 5m · 2l. This breaks down findings by severity:

• c (Critical): Application-breaking bugs, severe security vulnerabilities, or runaway cloud costs.
• h (High): Data corruption risks or major UI/accessibility failures.
• m (Medium): Standard technical debt, missing error boundaries, or minor logic flaws.
• l (Low): Best practice warnings and optimization suggestions.

periderm review --deep runs an AI agent locally against your codebase after a scan. It is designed for nuanced edge cases that deterministic rules cannot enumerate upfront — legal copy mismatches, subtle UX traps, business-logic contradictions, and one-off launch risks.

Requirements:

• Scale or Unlimited plan (checked via your CLI token)
• A recent scan (.periderm/last-report.json)

periderm scan
periderm review --deep

Deep review adds findings; it does not replace the fast deterministic layer. Every scan also runs a lightweight AI context pass (when configured) to filter false positives like missing favicons when you already have one under a nonstandard path.

If you ever need to remove the CLI and its local configuration:

npm uninstall -g periderm-cli
rm -rf ~/.periderm

Periderm detects what kind of app you have before applying consumer-facing checks.

Automatic detection

• Monorepo: marketing routes + _authenticated / admin routes → legal & SEO only on public surfaces
• Admin-only: no public landing routes → skips legal, SEO globally
• Mobile: Flutter, Expo, React Native, Swift → skips web SEO checks

Detection uses route structure and manifests (pubspec.yaml, app.json, Package.swift) — not your project folder name.

Manual override

Create .periderm/context.json in your repo:

{
  "profile": "monorepo",
  "internal_globs": [
    "**/_authenticated/**",
    "**/routes/admin/**",
    "**/src/admin/**"
  ],
  "skip_categories": ["Legal & Compliance"],
  "skip_check_ids": ["missing-favicon"]
}

| Field | Purpose | | --- | --- | | profile | consumer-app, admin-only, internal-tool, mobile-app, monorepo, library | | internal_globs | Paths where legal/SEO/accessibility checks are skipped | | skip_categories | Categories to skip project-wide | | skip_check_ids | Specific check IDs to always ignore |

AI triage

When Groq is configured server-side (dashboard scans) or via GROQ_API_KEY locally, Periderm runs a post-scan triage pass to remove obvious false positives before writing your markdown report.

When you run a scan, Periderm generates three distinct scores out of 100 to help you understand your app's readiness.

• Launch confidence: The overall score. It starts at 100 and is heavily penalized by critical and high-severity findings across all categories (including Security, Legal, SEO, and Best Practices). A score below 75 results in a hold verdict, while any critical finding immediately results in a blocked verdict.
• Reality: Measures your application's robustness against real-world chaos. This score drops when Periderm detects missing error boundaries, poor network failure handling, data integrity risks, or unhandled routing loops. If your app is built perfectly for the "happy path" but breaks when the network drops, your reality score will reflect it.
• Perceived performance: Measures how the application feels to the user. This score is penalized by unoptimized images, missing loading states, layout shifts, jarring transitions, and poor accessibility practices. It is completely independent of raw server speed.

It is common to see a Reality and Perceived Performance score of 100 while having a low Launch Confidence score. This simply means your app is robust and feels fast, but has blocking issues in other areas (such as missing legal pages or severe security vulnerabilities).

Every scan runs a Random Forest classifier trained on the PROMISE ant-1.7 software-defect dataset (745 Java modules, 83% accuracy). It predicts whether each source file is likely to contain defects using five CK-style metrics extracted at scan time.

| Feature | What it measures | | --- | --- | | loc | Lines of code | | wmc | Weighted methods / function count | | npm | Number of public methods | | max_cc | Max cyclomatic complexity (branch count) | | avg_cc | Average cyclomatic complexity |

When a file's predicted defect probability exceeds 50%, Periderm emits a HIGH finding:

Check id : ai-defect-prediction
Category : Code Quality
Message  : AI Defect Prediction: High Risk

The scan detail page shows a dedicated ML Defect Analysis card with the predictor status badge, high-risk file count, and the list of flagged files.

Python scripts

The ML layer is fully implemented in Python (scikit-learn). Three scripts cover the complete lifecycle:

# Train — exports defect_model.onnx + defect_model.json
pip install pandas scikit-learn skl2onnx onnx
python scripts/train_defect_model.py

# Evaluate — 5-fold CV, confusion matrix, ROC curve, feature importance
pip install pandas scikit-learn matplotlib seaborn
python scripts/evaluate_model.py

# Standalone Python scanner (no Node.js required)
pip install pandas scikit-learn requests rich
python scripts/analyze.py --cwd /path/to/project
python scripts/analyze.py --cwd /path/to/project --upload

scripts/analyze.py is a complete Python reimplementation of the scan pipeline — it extracts the same metrics, runs inference natively via sklearn, and optionally uploads findings to your dashboard.

Debug

PERIDERM_DEBUG_ML=1 periderm scan
# [periderm-ml] model path: .../defect_model.json
# [periderm-ml] session loaded — 100 trees, pure-JS inference