@skillguard/cli 0.2.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.5.0
+
+- Added `skillguard auth` command group:
+  - `auth login` (store key),
+  - `auth status` (show effective auth source),
+  - `auth logout` (remove local config key)
+- Added auth help/man coverage in CLI help pages
+
+## 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)

package/README.md

@@ -8,18 +8,38 @@ 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
 npx @skillguard/cli init
 ```
 
+Or via auth command:
+
+```bash
+npx @skillguard/cli auth login
+```
+
 You can also provide the key via env:
 
 ```bash
@@ -46,6 +66,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
+```
+
+### Auth status and logout
+
+```bash
+npx @skillguard/cli auth status
+npx @skillguard/cli auth logout
+```
+
+### Generate and push workflow in one command
+
+```bash
+npx @skillguard/cli workflow --auto-gh-push
+```
+
 ### Worst-score CI exit code (recommended)
 
 ```bash
@@ -74,6 +119,39 @@ npx @skillguard/cli verify ./SKILL.md
 - `--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`
+
+### auth
+
+- `auth login [--api-key <key>] [--base-url <url>]`
+- `auth status [--json] [--api-key <key>] [--base-url <url>]`
+- `auth logout`
+
+### 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
 
 - `--json`
@@ -92,6 +170,15 @@ npx @skillguard/cli verify ./SKILL.md
 - `verify`:
   - `0` signature valid
   - `1` invalid/tampered/expired signature
+- `limits`:
+  - `0` success
+- `gate`:
+  - `0` below threshold
+  - `1` threshold exceeded
+- `workflow`:
+  - `0` success
+- `auth`:
+  - `0` success
 - all commands:
   - `4` usage/input/config error
   - `5` network/API/runtime external failure
@@ -99,8 +186,16 @@ npx @skillguard/cli verify ./SKILL.md
 ## 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:
@@ -110,9 +205,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,17 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
+import { runAuth } from './commands/auth.js';
 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.2.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] [--skip-node-modules] [--scan-all]
-  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) {
@@ -53,6 +49,11 @@ function parseShared(args) {
             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,
     });
@@ -66,7 +67,12 @@ function isFailOnExplicit(args) {
 }
 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;
@@ -75,13 +81,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') {
@@ -90,6 +116,15 @@ async function run() {
             baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
         });
     }
+    if (command === 'auth') {
+        const authOptions = {
+            subcommand: positionals[0],
+            json: options.json === true,
+            baseUrl: typeof options['base-url'] === 'string' ? options['base-url'] : undefined,
+            apiKey: typeof options['api-key'] === 'string' ? options['api-key'] : undefined,
+        };
+        return await runAuth(authOptions);
+    }
     if (command === 'scan') {
         const pathArg = positionals[0];
         let parsedTimeout;
@@ -119,6 +154,69 @@ 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) {

package/dist/commands/auth.d.ts

@@ -0,0 +1,7 @@
+export interface AuthOptions {
+    subcommand?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    json: boolean;
+}
+export declare function runAuth(options: AuthOptions): Promise<number>;

package/dist/commands/auth.js

@@ -0,0 +1,103 @@
+import { clearConfig, DEFAULT_BASE_URL, getConfigPath, normalizeBaseUrl, readConfig, resolveApiKey } from '../lib/config.js';
+import { runInit } from './init.js';
+function toAuthSubcommand(raw) {
+    if (!raw) {
+        return null;
+    }
+    const value = raw.trim().toLowerCase();
+    if (value === 'login')
+        return 'login';
+    if (value === 'status')
+        return 'status';
+    if (value === 'logout')
+        return 'logout';
+    return null;
+}
+function renderStatusHuman(input) {
+    const lines = [
+        `Auth: ${input.authenticated ? 'configured' : 'not configured'}`,
+        `Source: ${input.source}`,
+        `Base URL: ${input.baseUrl}`,
+        `Config file: ${input.configPath}`,
+    ];
+    if (!input.authenticated) {
+        lines.push('No API key found. Use "skillguard auth login" or set SKILLGUARD_API_KEY.');
+    }
+    if (input.hasEnvKey) {
+        lines.push('Env key detected: SKILLGUARD_API_KEY');
+    }
+    if (input.hasConfigKey) {
+        lines.push('Config key detected.');
+    }
+    return lines.join('\n');
+}
+async function runStatus(options) {
+    const configPath = getConfigPath();
+    let config = null;
+    try {
+        config = await readConfig(configPath);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 4;
+    }
+    const resolvedApiKey = resolveApiKey({
+        apiKeyFlag: options.apiKey,
+        env: process.env,
+        config,
+    });
+    let baseUrl;
+    try {
+        baseUrl = normalizeBaseUrl(options.baseUrl || config?.apiUrl || DEFAULT_BASE_URL);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 4;
+    }
+    const payload = {
+        authenticated: Boolean(resolvedApiKey),
+        source: (resolvedApiKey?.source || 'none'),
+        baseUrl,
+        configPath,
+        hasConfigKey: typeof config?.apiKey === 'string' && config.apiKey.trim().length > 0,
+        hasEnvKey: typeof process.env.SKILLGUARD_API_KEY === 'string' && process.env.SKILLGUARD_API_KEY.trim().length > 0,
+    };
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return 0;
+    }
+    console.log(renderStatusHuman(payload));
+    return 0;
+}
+async function runLogout() {
+    const configPath = getConfigPath();
+    try {
+        const removed = await clearConfig(configPath);
+        console.log(removed ? `Logged out. Removed ${configPath}` : `No config found at ${configPath}`);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 4;
+    }
+    if (typeof process.env.SKILLGUARD_API_KEY === 'string' && process.env.SKILLGUARD_API_KEY.trim().length > 0) {
+        console.log('Note: SKILLGUARD_API_KEY is set in environment and will still be used by this shell.');
+    }
+    return 0;
+}
+export async function runAuth(options) {
+    const subcommand = toAuthSubcommand(options.subcommand);
+    if (!subcommand) {
+        console.error('Auth subcommand is required: login | status | logout');
+        return 4;
+    }
+    if (subcommand === 'login') {
+        return runInit({
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+        });
+    }
+    if (subcommand === 'status') {
+        return runStatus(options);
+    }
+    return runLogout();
+}

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.js

@@ -1,8 +1,9 @@
 import { readFile, readdir, realpath } from 'node:fs/promises';
 import { basename, resolve, sep } from 'node:path';
-import { normalizeFindings, scanContent, toScanScore } from '../lib/api.js';
+import { normalizeFindings, scanContent, scanContentAnonymous, toScanScore } from '../lib/api.js';
 import { normalizeBaseUrl, readConfig, resolveApiKey } from '../lib/config.js';
 import { renderSingleScan, renderSummary, shouldUseColor, summarizeScores } from '../lib/format.js';
+import { CLI_VERSION } from '../lib/version.js';
 const FAIL_LEVELS = {
     safe: 0,
     warning: 1,
@@ -164,22 +165,32 @@ export async function runScan(inputPath, options) {
         env: process.env,
         config,
     });
-    if (!resolvedApiKey) {
+    const useAnonymous = !resolvedApiKey;
+    if (!useAnonymous && !resolvedApiKey) {
         console.error("No API key found. Run 'skillguard init' or set SKILLGUARD_API_KEY.");
         return 4;
     }
     const color = shouldUseColor(options.noColor);
     const results = [];
+    if (useAnonymous && !options.quiet && !options.json) {
+        console.log('Scanning anonymously (limited). Add API key for higher limits.');
+    }
     for (const filePath of targets) {
         const content = await readFile(filePath, 'utf8');
         let apiResponse;
         try {
-            apiResponse = await scanContent({
-                baseUrl,
-                apiKey: resolvedApiKey.apiKey,
-                content,
-                timeoutMs: options.timeoutMs,
-            });
+            apiResponse = useAnonymous
+                ? await scanContentAnonymous({
+                    baseUrl,
+                    content,
+                    timeoutMs: options.timeoutMs,
+                })
+                : await scanContent({
+                    baseUrl,
+                    apiKey: resolvedApiKey.apiKey,
+                    content,
+                    timeoutMs: options.timeoutMs,
+                });
         }
         catch (error) {
             console.error(error.message);
@@ -208,7 +219,7 @@ export async function runScan(inputPath, options) {
         if (options.json) {
             const summary = summarizeScores(results);
             console.log(JSON.stringify({
-                cli_version: '0.2.0',
+                cli_version: CLI_VERSION,
                 scanned_at: new Date().toISOString(),
                 mode,
                 worst_score: worstScore,

package/dist/commands/workflow.d.ts

@@ -0,0 +1,21 @@
+import type { ScanScore } from '../lib/api.js';
+export interface WorkflowOptions {
+    outputPath?: string;
+    scanPath: string;
+    failOn: ScanScore;
+    print: boolean;
+    force: boolean;
+    autoGhPush: boolean;
+    commitMessage?: string;
+}
+interface GitCommandResult {
+    stdout: string;
+    stderr: string;
+    status: number;
+}
+type GitRunner = (args: string[]) => GitCommandResult;
+export declare function runWorkflow(options: WorkflowOptions, runtime?: {
+    cwd?: string;
+    gitRunner?: GitRunner;
+}): Promise<number>;
+export {};