@skillguard/cli 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+- Added `skillguard scan` without path argument (defaults to recursive scan from current directory)
+- Added recursive skip controls: `--skip-node-modules` and `--scan-all`
+- Added worst-score default exit mode for scan: `safe=0`, `warning=1`, `dangerous=2`
+- Preserved legacy threshold mode when `--fail-on` is explicitly provided
+- Added JSON scan output fields: `worst_score`, `exit_code`, `mode`
+- Updated non-scan failure exits across commands: usage/input/config -> `4`, network/API/runtime -> `5`
+
 ## 0.1.0
 
 - Initial release of `@skillguard/cli`

package/README.md

@@ -8,6 +8,12 @@ Security scanner CLI for AI agent `SKILL.md` files.
 npx @skillguard/cli scan SKILL.md
 ```
 
+### Scan all skills in current repo
+
+```bash
+npx @skillguard/cli scan
+```
+
 ## Setup
 
 ```bash
@@ -40,6 +46,13 @@ npx @skillguard/cli scan ./skills --fail-on warning
 npx @skillguard/cli scan ./skills --json > skillguard-report.json
 ```
 
+### Worst-score CI exit code (recommended)
+
+```bash
+npx @skillguard/cli scan
+# exit: safe=0, warning=1, dangerous=2
+```
+
 ### Verify signature
 
 ```bash
@@ -51,13 +64,15 @@ npx @skillguard/cli verify ./SKILL.md
 ### scan
 
 - `--json`
-- `--fail-on <safe|warning|dangerous>` (default: `warning`)
+- `--fail-on <safe|warning|dangerous>` (optional, enables legacy threshold mode)
 - `--timeout <ms>` (default: `30000`)
 - `--base-url <url>` (default: `https://skillguard.ai`)
 - `--api-key <key>`
 - `--dry-run`
 - `--quiet`
 - `--no-color`
+- `--skip-node-modules` (default: enabled)
+- `--scan-all` (disable skip filters, scans everything recursively)
 
 ### verify
 
@@ -67,10 +82,19 @@ npx @skillguard/cli verify ./SKILL.md
 
 ## Exit codes
 
-- `0` success / below threshold
-- `1` threshold exceeded (scan) or invalid/tampered signature (verify)
-- `2` usage/input error
-- `3` network/API/runtime external failure
+- `scan` default mode (no `--fail-on`):
+  - `0` worst score is `safe`
+  - `1` worst score is `warning`
+  - `2` worst score is `dangerous`
+- `scan` threshold mode (`--fail-on` provided):
+  - `0` below threshold
+  - `1` threshold exceeded
+- `verify`:
+  - `0` signature valid
+  - `1` invalid/tampered/expired signature
+- all commands:
+  - `4` usage/input/config error
+  - `5` network/API/runtime external failure
 
 ## GitHub Actions example
 

package/dist/cli.js

@@ -3,13 +3,13 @@ import { parseArgs } from 'node:util';
 import { runInit } from './commands/init.js';
 import { runScan } from './commands/scan.js';
 import { runVerify } from './commands/verify.js';
-const VERSION = '0.1.0';
+const VERSION = '0.2.0';
 function printUsage() {
     console.log(`SkillGuard CLI ${VERSION}
 
 Usage:
   skillguard init [--api-key <key>] [--base-url <url>]
-  skillguard scan <path> [--json] [--fail-on <safe|warning|dangerous>] [--timeout <ms>] [--base-url <url>] [--api-key <key>] [--dry-run] [--quiet] [--no-color]
+  skillguard scan [path] [--json] [--fail-on <safe|warning|dangerous>] [--timeout <ms>] [--base-url <url>] [--api-key <key>] [--dry-run] [--quiet] [--no-color] [--skip-node-modules] [--scan-all]
   skillguard verify <path> [--json] [--timeout <ms>] [--base-url <url>]
 
 Options:
@@ -48,6 +48,8 @@ function parseShared(args) {
             quiet: { type: 'boolean' },
             'no-color': { type: 'boolean' },
             'fail-on': { type: 'string' },
+            'scan-all': { type: 'boolean' },
+            'skip-node-modules': { type: 'boolean' },
             timeout: { type: 'string' },
             'base-url': { type: 'string' },
             'api-key': { type: 'string' },
@@ -59,6 +61,9 @@ function parseShared(args) {
         positionals: parsed.positionals,
     };
 }
+function isFailOnExplicit(args) {
+    return args.some((arg) => arg === '--fail-on' || arg.startsWith('--fail-on='));
+}
 async function run() {
     const argv = process.argv.slice(2);
     const command = argv[0];
@@ -87,23 +92,24 @@ async function run() {
     }
     if (command === 'scan') {
         const pathArg = positionals[0];
-        if (!pathArg) {
-            console.error('Missing required <path> argument.');
-            return 2;
-        }
         let parsedTimeout;
         let failOn;
         try {
             parsedTimeout = toPositiveInteger(typeof options.timeout === 'string' ? options.timeout : undefined, 30000);
-            failOn = toFailOn(typeof options['fail-on'] === 'string' ? options['fail-on'] : undefined);
+            if (isFailOnExplicit(argv.slice(1))) {
+                failOn = toFailOn(typeof options['fail-on'] === 'string' ? options['fail-on'] : undefined);
+            }
         }
         catch (error) {
             console.error(error.message);
-            return 2;
+            return 4;
         }
         const scanOptions = {
             json: options.json === true,
             failOn,
+            failOnExplicit: isFailOnExplicit(argv.slice(1)),
+            scanAll: options['scan-all'] === true,
+            skipNodeModules: options['scan-all'] === true ? false : options['skip-node-modules'] !== false,
             timeoutMs: parsedTimeout,
             baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
             apiKey: typeof options['api-key'] === 'string' ? options['api-key'] : undefined,
@@ -117,7 +123,7 @@ async function run() {
         const pathArg = positionals[0];
         if (!pathArg) {
             console.error('Missing required <path> argument.');
-            return 2;
+            return 4;
         }
         let parsedTimeout;
         try {
@@ -125,7 +131,7 @@ async function run() {
         }
         catch (error) {
             console.error(error.message);
-            return 2;
+            return 4;
         }
         const verifyOptions = {
             baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
@@ -136,7 +142,7 @@ async function run() {
     }
     console.error(`Unknown command: ${command}`);
     printUsage();
-    return 2;
+    return 4;
 }
 run()
     .then((code) => {
@@ -144,5 +150,5 @@ run()
 })
     .catch(() => {
     console.error('Unexpected CLI error.');
-    process.exitCode = 3;
+    process.exitCode = 5;
 });

package/dist/commands/scan.d.ts

@@ -1,7 +1,10 @@
 import { type ScanFinding, type ScanScore } from '../lib/api.js';
 export interface ScanOptions {
     json: boolean;
-    failOn: ScanScore;
+    failOn?: ScanScore;
+    failOnExplicit: boolean;
+    scanAll: boolean;
+    skipNodeModules: boolean;
     timeoutMs: number;
     baseUrl?: string;
     apiKey?: string;
@@ -15,4 +18,4 @@ export interface ScanResult {
     findings: ScanFinding[];
     signatureStatus: string;
 }
-export declare function runScan(inputPath: string, options: ScanOptions): Promise<number>;
+export declare function runScan(inputPath: string | undefined, options: ScanOptions): Promise<number>;

package/dist/commands/scan.js

@@ -8,12 +8,26 @@ const FAIL_LEVELS = {
     warning: 1,
     dangerous: 2,
 };
+const WORST_EXIT_CODES = {
+    safe: 0,
+    warning: 1,
+    dangerous: 2,
+};
 function shouldFail(score, failOn) {
     if (failOn === 'safe') {
         return score !== 'safe';
     }
     return FAIL_LEVELS[score] >= FAIL_LEVELS[failOn];
 }
+function resolveWorstScore(results) {
+    if (results.some((result) => result.score === 'dangerous')) {
+        return 'dangerous';
+    }
+    if (results.some((result) => result.score === 'warning')) {
+        return 'warning';
+    }
+    return 'safe';
+}
 function isForbiddenFilePath(filePath) {
     const name = basename(filePath).toLowerCase();
     return (name === '.env' ||
@@ -28,7 +42,16 @@ function isWithinRoot(rootPath, candidatePath) {
     }
     return candidatePath.startsWith(`${rootPath}${sep}`);
 }
-async function findSkillFiles(rootPath) {
+function shouldSkipDirectory(entryName, options) {
+    if (options.scanAll) {
+        return false;
+    }
+    if (options.skipNodeModules && entryName.toLowerCase() === 'node_modules') {
+        return true;
+    }
+    return false;
+}
+async function findSkillFiles(rootPath, options) {
     const rootRealPath = await realpath(rootPath);
     const queue = [rootPath];
     const found = new Set();
@@ -44,6 +67,9 @@ async function findSkillFiles(rootPath) {
                 continue;
             }
             if (entry.isDirectory()) {
+                if (shouldSkipDirectory(entry.name, options)) {
+                    continue;
+                }
                 const resolvedDir = await realpath(fullPath);
                 if (!isWithinRoot(rootRealPath, resolvedDir)) {
                     continue;
@@ -70,14 +96,14 @@ async function findSkillFiles(rootPath) {
     }
     return Array.from(found).sort();
 }
-async function resolveTargets(inputPath) {
+async function resolveTargets(inputPath, traversalOptions) {
     const path = resolve(inputPath);
     const stat = await import('node:fs/promises').then((mod) => mod.lstat(path));
     if (stat.isSymbolicLink()) {
         throw new Error('Symlink paths are not supported.');
     }
     if (stat.isDirectory()) {
-        const files = await findSkillFiles(path);
+        const files = await findSkillFiles(path, traversalOptions);
         if (files.length === 0) {
             throw new Error('No SKILL.md files found in directory.');
         }
@@ -92,21 +118,25 @@ async function resolveTargets(inputPath) {
     return [path];
 }
 export async function runScan(inputPath, options) {
+    const scanRoot = inputPath ? resolve(inputPath) : process.cwd();
     let baseUrl;
     try {
         baseUrl = normalizeBaseUrl(options.baseUrl);
     }
     catch (error) {
         console.error(error.message);
-        return 2;
+        return 4;
     }
     let targets;
     try {
-        targets = await resolveTargets(inputPath);
+        targets = await resolveTargets(scanRoot, {
+            scanAll: options.scanAll,
+            skipNodeModules: options.skipNodeModules,
+        });
     }
     catch (error) {
         console.error(error.message);
-        return 2;
+        return 4;
     }
     if (options.dryRun) {
         if (!options.quiet) {
@@ -126,7 +156,7 @@ export async function runScan(inputPath, options) {
         }
         catch (error) {
             console.error(error.message);
-            return 2;
+            return 4;
         }
     }
     const resolvedApiKey = resolveApiKey({
@@ -136,7 +166,7 @@ export async function runScan(inputPath, options) {
     });
     if (!resolvedApiKey) {
         console.error("No API key found. Run 'skillguard init' or set SKILLGUARD_API_KEY.");
-        return 2;
+        return 4;
     }
     const color = shouldUseColor(options.noColor);
     const results = [];
@@ -153,7 +183,7 @@ export async function runScan(inputPath, options) {
         }
         catch (error) {
             console.error(error.message);
-            return 3;
+            return 5;
         }
         const findings = normalizeFindings(apiResponse.findings);
         const score = toScanScore(apiResponse.score || apiResponse.overallRisk);
@@ -167,14 +197,23 @@ export async function runScan(inputPath, options) {
             signatureStatus,
         });
     }
-    const failedFiles = results.filter((result) => shouldFail(result.score, options.failOn)).map((result) => result.file);
+    const failOn = options.failOn || 'warning';
+    const mode = options.failOnExplicit ? 'threshold' : 'worst';
+    const worstScore = resolveWorstScore(results);
+    const failedFiles = results.filter((result) => shouldFail(result.score, failOn)).map((result) => result.file);
+    const exitCode = mode === 'threshold'
+        ? (failedFiles.length > 0 ? 1 : 0)
+        : WORST_EXIT_CODES[worstScore];
     if (!options.quiet) {
         if (options.json) {
             const summary = summarizeScores(results);
             console.log(JSON.stringify({
-                cli_version: '0.1.0',
+                cli_version: '0.2.0',
                 scanned_at: new Date().toISOString(),
-                fail_on: options.failOn,
+                mode,
+                worst_score: worstScore,
+                exit_code: exitCode,
+                fail_on: mode === 'threshold' ? failOn : undefined,
                 summary,
                 failed_files: failedFiles,
                 results,
@@ -185,9 +224,9 @@ export async function runScan(inputPath, options) {
                 console.log(renderSingleScan(result, color));
             }
             const summary = summarizeScores(results);
-            const rootLabel = targets.length === 1 ? targets[0] : resolve(inputPath);
+            const rootLabel = targets.length === 1 ? targets[0] : scanRoot;
             console.log(renderSummary(summary, rootLabel, color, failedFiles));
         }
     }
-    return failedFiles.length > 0 ? 1 : 0;
+    return exitCode;
 }

package/dist/commands/verify.js

@@ -29,7 +29,7 @@ export async function runVerify(inputPath, options) {
     }
     catch (error) {
         console.error(error.message);
-        return 2;
+        return 4;
     }
     let rawContent;
     try {
@@ -37,7 +37,7 @@ export async function runVerify(inputPath, options) {
     }
     catch {
         console.error('Could not read file.');
-        return 2;
+        return 4;
     }
     const parsedSkill = parseSkillContent(rawContent);
     if (!parsedSkill.security || typeof parsedSkill.security.signature !== 'string') {
@@ -59,7 +59,7 @@ export async function runVerify(inputPath, options) {
     }
     catch (error) {
         console.error(error.message);
-        return 3;
+        return 5;
     }
     const verification = verifySignature({ parsedSkill, jwks });
     const valid = verification.signatureValid && verification.hashMatches && !verification.expired;

package/dist/lib/format.js

@@ -113,6 +113,8 @@ export function renderSummary(summary, rootPath, color, failedFiles) {
         `  ${formatCell(maybeColor(color, GREEN, 'safe:'), 11)}${String(summary.safe)}`,
         `  ${formatCell(maybeColor(color, YELLOW, 'warning:'), 11)}${String(summary.warning)}`,
         `  ${formatCell(maybeColor(color, RED, 'dangerous:'), 11)}${String(summary.dangerous)}`,
+        '',
+        `Worst score: ${summary.dangerous > 0 ? 'dangerous' : summary.warning > 0 ? 'warning' : 'safe'}`,
     ];
     if (failedFiles.length > 0) {
         lines.push('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillguard/cli",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Security scanner for AI agent skill files",
   "type": "module",
   "bin": {