@skillguard/cli 0.1.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.0
+
+- Added `skillguard workflow` command to generate ready-to-use GitHub Actions CI gate workflow
+- Added `--auto-gh-push` option for workflow command (`git add/commit/push`)
+- Added `skillguard help <command>` and `skillguard man <command>` detailed help pages
+- Added `--workflow` alias for fast workflow generation
+- Updated CLI/web workflow snippets to default to zero-secret gate flow
+
+## 0.3.0
+
+- Added `skillguard gate` command for deterministic CI gating (`0` pass, `1` fail)
+- Added `skillguard limits` command with human and `--json` output
+- Added anonymous scan fallback when no API key is configured
+- Added CLI telemetry headers (`X-SkillGuard-Source`, `X-SkillGuard-CI`)
+- Added support for backend anonymous limits endpoint
+
+## 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,26 @@ Security scanner CLI for AI agent `SKILL.md` files.
 npx @skillguard/cli scan SKILL.md
 ```
 
+No API key configured? CLI falls back to anonymous scanning (rate-limited).
+
+### Scan all skills in current repo
+
+```bash
+npx @skillguard/cli scan
+```
+
+### Generate CI workflow (no secrets required)
+
+```bash
+npx @skillguard/cli workflow
+```
+
+### Command help (man-like)
+
+```bash
+npx @skillguard/cli help scan
+```
+
 ## Setup
 
 ```bash
@@ -40,6 +60,31 @@ npx @skillguard/cli scan ./skills --fail-on warning
 npx @skillguard/cli scan ./skills --json > skillguard-report.json
 ```
 
+### CI gate (recommended)
+
+```bash
+npx @skillguard/cli gate ./skills
+```
+
+### Check remaining limits
+
+```bash
+npx @skillguard/cli limits
+```
+
+### Generate and push workflow in one command
+
+```bash
+npx @skillguard/cli workflow --auto-gh-push
+```
+
+### Worst-score CI exit code (recommended)
+
+```bash
+npx @skillguard/cli scan
+# exit: safe=0, warning=1, dangerous=2
+```
+
 ### Verify signature
 
 ```bash
@@ -51,13 +96,42 @@ 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)
+
+### gate
+
+- same options as `scan`
+- defaults to CI gate behavior (`--fail-on warning` in threshold mode)
+
+### limits
+
+- `--json`
+- `--timeout <ms>` (default: `30000`)
+- `--base-url <url>` (default: `https://skillguard.ai`)
+- `--api-key <key>` (optional)
+- `--no-color`
+
+### workflow
+
+- `--path <file>` (default: `.github/workflows/skillguard.yml`)
+- `--scan-path <path>` (default: `.`)
+- `--fail-on <safe|warning|dangerous>` (default: `warning`)
+- `--print` (print yaml, do not write file)
+- `--force` (overwrite existing workflow file)
+- `--auto-gh-push` (git add/commit/push after write)
+
+### help / man
+
+- `help [command]`
+- `man [command]`
 
 ### verify
 
@@ -67,16 +141,40 @@ 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
+- `limits`:
+  - `0` success
+- `gate`:
+  - `0` below threshold
+  - `1` threshold exceeded
+- `workflow`:
+  - `0` success
+- all commands:
+  - `4` usage/input/config error
+  - `5` network/API/runtime external failure
 
 ## GitHub Actions example
 
 ```yaml
-name: Skill Security Scan
-on: [push, pull_request]
+name: SkillGuard Gate
+on:
+  pull_request:
+    paths:
+      - '**/SKILL.md'
+      - '**/skill.md'
+  push:
+    paths:
+      - '**/SKILL.md'
+      - '**/skill.md'
 
 jobs:
   scan:
@@ -86,9 +184,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
-      - run: npx @skillguard/cli scan ./skills
-        env:
-          SKILLGUARD_API_KEY: ${{ secrets.SKILLGUARD_API_KEY }}
+      - run: npx @skillguard/cli gate . --fail-on warning
 ```
 
 More info: [skillguard.ai](https://skillguard.ai)

package/dist/cli.js

@@ -1,21 +1,16 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { runInit } from './commands/init.js';
+import { runGate } from './commands/gate.js';
+import { runLimits } from './commands/limits.js';
 import { runScan } from './commands/scan.js';
 import { runVerify } from './commands/verify.js';
-const VERSION = '0.1.0';
+import { runWorkflow } from './commands/workflow.js';
+import { renderGeneralHelp, renderTopicHelp } from './lib/help.js';
+import { CLI_VERSION } from './lib/version.js';
+const VERSION = CLI_VERSION;
 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 verify <path> [--json] [--timeout <ms>] [--base-url <url>]
-
-Options:
-  --help         Show help
-  --version      Show version
-`);
+    console.log(renderGeneralHelp(VERSION));
 }
 function toPositiveInteger(raw, fallback) {
     if (!raw) {
@@ -48,9 +43,16 @@ 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' },
+            path: { type: 'string' },
+            'scan-path': { type: 'string' },
+            print: { type: 'boolean' },
+            force: { type: 'boolean' },
+            'auto-gh-push': { type: 'boolean' },
         },
         strict: false,
     });
@@ -59,9 +61,17 @@ 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];
+    let command = argv[0];
+    let commandArgs = argv.slice(1);
+    if (command === '--workflow') {
+        command = 'workflow';
+        commandArgs = argv.slice(1);
+    }
     if (!command || command === '--help' || command === '-h') {
         printUsage();
         return 0;
@@ -70,13 +80,33 @@ async function run() {
         console.log(VERSION);
         return 0;
     }
-    const { options, positionals } = parseShared(argv.slice(1));
+    if (command === 'help' || command === 'man') {
+        const topic = argv[1];
+        if (!topic) {
+            printUsage();
+            return 0;
+        }
+        const helpText = renderTopicHelp(topic);
+        if (!helpText) {
+            console.error(`Unknown help topic: ${topic}`);
+            return 4;
+        }
+        console.log(helpText);
+        return 0;
+    }
+    const { options, positionals } = parseShared(commandArgs);
     if (options.version) {
         console.log(VERSION);
         return 0;
     }
     if (options.help) {
-        printUsage();
+        const topicHelp = renderTopicHelp(command);
+        if (topicHelp) {
+            console.log(topicHelp);
+        }
+        else {
+            printUsage();
+        }
         return 0;
     }
     if (command === 'init') {
@@ -87,23 +117,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,
@@ -113,11 +144,74 @@ async function run() {
         };
         return await runScan(pathArg, scanOptions);
     }
+    if (command === 'gate') {
+        const pathArg = positionals[0];
+        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);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 4;
+        }
+        const gateOptions = {
+            json: options.json === true,
+            failOn,
+            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,
+            dryRun: options['dry-run'] === true,
+            quiet: options.quiet === true,
+            noColor: options['no-color'] === true,
+        };
+        return await runGate(pathArg, gateOptions);
+    }
+    if (command === 'limits') {
+        let parsedTimeout;
+        try {
+            parsedTimeout = toPositiveInteger(typeof options.timeout === 'string' ? options.timeout : undefined, 30000);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 4;
+        }
+        const limitsOptions = {
+            json: options.json === true,
+            timeoutMs: parsedTimeout,
+            baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
+            apiKey: typeof options['api-key'] === 'string' ? options['api-key'] : undefined,
+            noColor: options['no-color'] === true,
+        };
+        return await runLimits(limitsOptions);
+    }
+    if (command === 'workflow') {
+        let failOn;
+        try {
+            failOn = toFailOn(typeof options['fail-on'] === 'string' ? options['fail-on'] : undefined);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 4;
+        }
+        const workflowOptions = {
+            outputPath: typeof options.path === 'string' ? options.path : undefined,
+            scanPath: typeof options['scan-path'] === 'string' ? options['scan-path'] : '.',
+            failOn,
+            print: options.print === true,
+            force: options.force === true,
+            autoGhPush: options['auto-gh-push'] === true,
+        };
+        return await runWorkflow(workflowOptions);
+    }
     if (command === 'verify') {
         const pathArg = positionals[0];
         if (!pathArg) {
             console.error('Missing required <path> argument.');
-            return 2;
+            return 4;
         }
         let parsedTimeout;
         try {
@@ -125,7 +219,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 +230,7 @@ async function run() {
     }
     console.error(`Unknown command: ${command}`);
     printUsage();
-    return 2;
+    return 4;
 }
 run()
     .then((code) => {
@@ -144,5 +238,5 @@ run()
 })
     .catch(() => {
     console.error('Unexpected CLI error.');
-    process.exitCode = 3;
+    process.exitCode = 5;
 });

package/dist/commands/gate.d.ts

@@ -0,0 +1,14 @@
+import type { ScanScore } from '../lib/api.js';
+export interface GateOptions {
+    json: boolean;
+    failOn?: ScanScore;
+    scanAll: boolean;
+    skipNodeModules: boolean;
+    timeoutMs: number;
+    baseUrl?: string;
+    apiKey?: string;
+    dryRun: boolean;
+    quiet: boolean;
+    noColor: boolean;
+}
+export declare function runGate(inputPath: string | undefined, options: GateOptions): Promise<number>;

package/dist/commands/gate.js

@@ -0,0 +1,17 @@
+import { runScan } from './scan.js';
+export async function runGate(inputPath, options) {
+    const scanOptions = {
+        json: options.json,
+        failOn: options.failOn || 'warning',
+        failOnExplicit: true,
+        scanAll: options.scanAll,
+        skipNodeModules: options.skipNodeModules,
+        timeoutMs: options.timeoutMs,
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+        dryRun: options.dryRun,
+        quiet: options.quiet,
+        noColor: options.noColor,
+    };
+    return runScan(inputPath, scanOptions);
+}

package/dist/commands/limits.d.ts

@@ -0,0 +1,8 @@
+export interface LimitsOptions {
+    json: boolean;
+    timeoutMs: number;
+    baseUrl?: string;
+    apiKey?: string;
+    noColor: boolean;
+}
+export declare function runLimits(options: LimitsOptions): Promise<number>;

package/dist/commands/limits.js

@@ -0,0 +1,98 @@
+import { fetchLimits } from '../lib/api.js';
+import { normalizeBaseUrl, readConfig, resolveApiKey } from '../lib/config.js';
+import { CLI_VERSION } from '../lib/version.js';
+function renderHuman(response) {
+    const lines = [];
+    const mode = typeof response.mode === 'string' ? response.mode : 'unknown';
+    lines.push(`Mode: ${mode}`);
+    if (typeof response.tokenBalance === 'number') {
+        lines.push(`Token balance: ${response.tokenBalance}`);
+    }
+    if (response.ownerTrial && typeof response.ownerTrial === 'object') {
+        const trial = response.ownerTrial;
+        lines.push('Owner trial:');
+        lines.push(`  scans: ${Number(trial.scansUsed || 0)} / ${Number(trial.scansLimit || 0)}`);
+        lines.push(`  remaining: ${Number(trial.remainingScans || 0)}`);
+        lines.push(`  active: ${trial.active === true ? 'yes' : 'no'}`);
+        if (typeof trial.expiresAt === 'string' && trial.expiresAt) {
+            lines.push(`  expires: ${trial.expiresAt}`);
+        }
+    }
+    if (response.apiKeyQuota && typeof response.apiKeyQuota === 'object') {
+        const quota = response.apiKeyQuota;
+        lines.push('API key quota:');
+        lines.push(`  key type: ${String(quota.keyType || 'standard')}`);
+        lines.push(`  unlimited: ${quota.unlimited === true ? 'yes' : 'no'}`);
+        lines.push(`  scans used: ${Number(quota.scansUsed || 0)}`);
+        if (typeof quota.maxScans === 'number') {
+            lines.push(`  max scans: ${quota.maxScans}`);
+        }
+        if (typeof quota.remainingScans === 'number') {
+            lines.push(`  remaining: ${quota.remainingScans}`);
+        }
+        lines.push(`  active: ${quota.active === true ? 'yes' : 'no'}`);
+        if (typeof quota.expiresAt === 'string' && quota.expiresAt) {
+            lines.push(`  expires: ${quota.expiresAt}`);
+        }
+    }
+    if (response.anonymousQuota && typeof response.anonymousQuota === 'object') {
+        const quota = response.anonymousQuota;
+        lines.push('Anonymous quota:');
+        lines.push(`  scans: ${Number(quota.scansUsed || 0)} / ${Number(quota.maxScans || 0)}`);
+        lines.push(`  remaining: ${Number(quota.remainingScans || 0)}`);
+        if (typeof quota.resetAt === 'string' && quota.resetAt) {
+            lines.push(`  reset at: ${quota.resetAt}`);
+        }
+    }
+    return lines.join('\n');
+}
+export async function runLimits(options) {
+    let baseUrl;
+    try {
+        baseUrl = normalizeBaseUrl(options.baseUrl);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 4;
+    }
+    const hasApiKeyFlag = typeof options.apiKey === 'string' && options.apiKey.trim().length > 0;
+    const hasApiKeyEnv = typeof process.env.SKILLGUARD_API_KEY === 'string' && process.env.SKILLGUARD_API_KEY.trim().length > 0;
+    let config = null;
+    if (!hasApiKeyFlag && !hasApiKeyEnv) {
+        try {
+            config = await readConfig();
+        }
+        catch (error) {
+            console.error(error.message);
+            return 4;
+        }
+    }
+    const resolvedApiKey = resolveApiKey({
+        apiKeyFlag: options.apiKey,
+        env: process.env,
+        config,
+    });
+    let response;
+    try {
+        response = await fetchLimits({
+            baseUrl,
+            timeoutMs: options.timeoutMs,
+            apiKey: resolvedApiKey?.apiKey,
+        });
+    }
+    catch (error) {
+        console.error(error.message);
+        return 5;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            cli_version: CLI_VERSION,
+            fetched_at: new Date().toISOString(),
+            ...response,
+        }, null, 2));
+    }
+    else {
+        console.log(renderHuman(response));
+    }
+    return 0;
+}

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>;