@skillguard/cli 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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)

package/README.md

@@ -8,12 +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
@@ -46,6 +60,24 @@ 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
@@ -74,6 +106,33 @@ 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`
+
+### 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 +151,13 @@ 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
 - all commands:
   - `4` usage/input/config error
   - `5` network/API/runtime external failure
@@ -99,8 +165,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 +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.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 +48,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 +66,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 +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') {
@@ -119,6 +144,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/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 {};

package/dist/commands/workflow.js

@@ -0,0 +1,143 @@
+import { mkdir, access, writeFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+const DEFAULT_WORKFLOW_PATH = '.github/workflows/skillguard.yml';
+const DEFAULT_COMMIT_MESSAGE = 'chore(ci): add skillguard workflow';
+function buildWorkflowYaml(input) {
+    const scanPath = input.scanPath.trim() || '.';
+    return [
+        'name: SkillGuard Gate',
+        'on:',
+        '  pull_request:',
+        '    paths:',
+        "      - '**/SKILL.md'",
+        "      - '**/skill.md'",
+        '  push:',
+        '    paths:',
+        "      - '**/SKILL.md'",
+        "      - '**/skill.md'",
+        '',
+        'jobs:',
+        '  scan:',
+        '    runs-on: ubuntu-latest',
+        '    steps:',
+        '      - uses: actions/checkout@v4',
+        '      - uses: actions/setup-node@v4',
+        '        with:',
+        "          node-version: '20'",
+        '      - name: SkillGuard scan',
+        `        run: npx @skillguard/cli gate ${scanPath} --fail-on ${input.failOn}`,
+    ].join('\n');
+}
+function isCommandSafePath(value) {
+    return /^[./a-zA-Z0-9_-]+$/.test(value);
+}
+async function fileExists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createDefaultGitRunner(cwd) {
+    return (args) => {
+        const result = spawnSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.error) {
+            throw new Error('Git command failed.');
+        }
+        return {
+            stdout: typeof result.stdout === 'string' ? result.stdout : '',
+            stderr: typeof result.stderr === 'string' ? result.stderr : '',
+            status: typeof result.status === 'number' ? result.status : 1,
+        };
+    };
+}
+function ensureGitSuccess(result, fallbackMessage) {
+    if (result.status === 0) {
+        return;
+    }
+    const stderr = result.stderr.trim();
+    if (stderr) {
+        throw new Error(stderr);
+    }
+    throw new Error(fallbackMessage);
+}
+function resolveWorkflowPath(cwd, outputPath) {
+    return resolve(cwd, outputPath || DEFAULT_WORKFLOW_PATH);
+}
+function commitAndPushWorkflow(input) {
+    const git = input.gitRunner || createDefaultGitRunner(input.cwd);
+    const repoRootResult = git(['rev-parse', '--show-toplevel']);
+    ensureGitSuccess(repoRootResult, 'Not a git repository.');
+    const repoRoot = repoRootResult.stdout.trim();
+    const relativePath = relative(repoRoot, input.workflowPath);
+    if (!relativePath || relativePath.startsWith('..')) {
+        throw new Error('Workflow path must be inside the current git repository.');
+    }
+    ensureGitSuccess(git(['add', '--', relativePath]), 'Could not stage workflow file.');
+    const stagedResult = git(['diff', '--cached', '--name-only', '--', relativePath]);
+    ensureGitSuccess(stagedResult, 'Could not inspect staged changes.');
+    if (!stagedResult.stdout.trim()) {
+        return false;
+    }
+    ensureGitSuccess(git(['commit', '-m', input.commitMessage, '--', relativePath]), 'Could not create commit.');
+    ensureGitSuccess(git(['push']), 'Could not push commit.');
+    return true;
+}
+export async function runWorkflow(options, runtime) {
+    const cwd = runtime?.cwd || process.cwd();
+    const scanPath = (options.scanPath || '.').trim() || '.';
+    if (!isCommandSafePath(scanPath)) {
+        console.error('Invalid --scan-path value. Use simple relative paths only.');
+        return 4;
+    }
+    if (options.print && options.autoGhPush) {
+        console.error('Cannot use --auto-gh-push with --print.');
+        return 4;
+    }
+    const yaml = buildWorkflowYaml({
+        scanPath,
+        failOn: options.failOn,
+    });
+    if (options.print) {
+        console.log(yaml);
+        return 0;
+    }
+    const workflowPath = resolveWorkflowPath(cwd, options.outputPath);
+    const exists = await fileExists(workflowPath);
+    if (exists && !options.force) {
+        console.error(`Workflow file already exists: ${workflowPath}. Use --force to overwrite.`);
+        return 4;
+    }
+    await mkdir(dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, `${yaml}\n`, 'utf8');
+    console.log(`Workflow written to ${workflowPath}`);
+    if (!options.autoGhPush) {
+        return 0;
+    }
+    try {
+        const pushed = commitAndPushWorkflow({
+            cwd,
+            workflowPath,
+            commitMessage: (options.commitMessage || DEFAULT_COMMIT_MESSAGE).trim() || DEFAULT_COMMIT_MESSAGE,
+            gitRunner: runtime?.gitRunner,
+        });
+        if (!pushed) {
+            console.log('Workflow already up to date. No commit created.');
+            return 0;
+        }
+    }
+    catch (error) {
+        console.error(`Auto push failed: ${error.message}`);
+        return 5;
+    }
+    console.log('Workflow committed and pushed.');
+    return 0;
+}

package/dist/lib/api.d.ts

@@ -14,6 +14,34 @@ export interface ScanApiResponse {
     signedSkillContent?: string;
     [key: string]: unknown;
 }
+export interface LimitsApiResponse {
+    mode?: 'anonymous' | 'owner' | 'agent';
+    tokenBalance?: number;
+    ownerTrial?: {
+        scansLimit?: number;
+        scansUsed?: number;
+        remainingScans?: number;
+        expiresAt?: string | null;
+        active?: boolean;
+    };
+    apiKeyQuota?: {
+        keyType?: 'standard' | 'trial';
+        maxScans?: number | null;
+        scansUsed?: number;
+        remainingScans?: number | null;
+        expiresAt?: string | null;
+        unlimited?: boolean;
+        active?: boolean;
+    };
+    anonymousQuota?: {
+        windowMs?: number;
+        maxScans?: number;
+        scansUsed?: number;
+        remainingScans?: number;
+        resetAt?: string;
+    };
+    [key: string]: unknown;
+}
 export interface SanitizedApiError {
     message: string;
     exitCode: 2 | 3;
@@ -26,6 +54,18 @@ export declare function scanContent(input: {
     timeoutMs: number;
     fetchImpl?: typeof fetch;
 }): Promise<ScanApiResponse>;
+export declare function scanContentAnonymous(input: {
+    baseUrl: string;
+    content: string;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}): Promise<ScanApiResponse>;
+export declare function fetchLimits(input: {
+    baseUrl: string;
+    timeoutMs: number;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<LimitsApiResponse>;
 export declare function fetchJwks(input: {
     baseUrl: string;
     timeoutMs: number;

package/dist/lib/api.js

@@ -58,6 +58,47 @@ function mapStatusMessage(status) {
     }
     return 'SkillGuard API request failed.';
 }
+function mapLimitsStatusMessage(status) {
+    if (status === 401) {
+        return "Invalid API key. Run 'skillguard init' or set SKILLGUARD_API_KEY.";
+    }
+    if (status === 403) {
+        return 'Access denied for this API key.';
+    }
+    if (status === 429) {
+        return 'Rate limit exceeded. Wait and retry.';
+    }
+    if (status >= 500) {
+        return 'SkillGuard API error. Try again later.';
+    }
+    return 'SkillGuard limits request failed.';
+}
+function detectCiSource(env = process.env) {
+    if (env.GITHUB_ACTIONS === 'true')
+        return 'github-actions';
+    if (env.GITLAB_CI === 'true')
+        return 'gitlab';
+    if (env.BUILDKITE === 'true')
+        return 'buildkite';
+    if (env.CIRCLECI === 'true')
+        return 'circleci';
+    if (env.JENKINS_URL)
+        return 'jenkins';
+    if (env.TF_BUILD === 'True' || env.AZURE_HTTP_USER_AGENT)
+        return 'azure-pipelines';
+    return null;
+}
+function buildCliHeaders(extra = {}) {
+    const headers = {
+        'X-SkillGuard-Source': 'cli',
+        ...extra,
+    };
+    const ciSource = detectCiSource();
+    if (ciSource) {
+        headers['X-SkillGuard-CI'] = ciSource;
+    }
+    return headers;
+}
 export async function scanContent(input) {
     const fetchFn = input.fetchImpl || fetch;
     const endpoint = `${input.baseUrl}/api/v1/scan`;
@@ -66,6 +107,7 @@ export async function scanContent(input) {
         const response = await fetchWithRetry(fetchFn, endpoint, {
             method: 'POST',
             headers: {
+                ...buildCliHeaders(),
                 'X-API-Key': input.apiKey,
                 'Content-Type': 'application/json',
             },
@@ -101,6 +143,91 @@ export async function scanContent(input) {
         timeout.cancel();
     }
 }
+export async function scanContentAnonymous(input) {
+    const fetchFn = input.fetchImpl || fetch;
+    const endpoint = `${input.baseUrl}/api/v1/scan/anonymous`;
+    const timeout = withTimeout(input.timeoutMs);
+    try {
+        const response = await fetchWithRetry(fetchFn, endpoint, {
+            method: 'POST',
+            headers: {
+                ...buildCliHeaders(),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ content: input.content }),
+            signal: timeout.signal,
+        }, 1);
+        if (!response.ok) {
+            throw new Error(mapStatusMessage(response.status));
+        }
+        const parsed = await parseJsonSafe(response);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Unexpected API response.');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const typed = error;
+        if (typed.name === 'AbortError') {
+            throw new Error('Cannot reach skillguard.ai. Check your connection.');
+        }
+        if (typed.message === 'Unexpected API response.') {
+            throw typed;
+        }
+        if (typed.message.includes('Rate limit exceeded.') ||
+            typed.message.includes('SkillGuard API error.') ||
+            typed.message.includes('SkillGuard API request failed.')) {
+            throw typed;
+        }
+        throw new Error('Cannot reach skillguard.ai. Check your connection.');
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+export async function fetchLimits(input) {
+    const fetchFn = input.fetchImpl || fetch;
+    const endpoint = `${input.baseUrl}/api/v1/limits`;
+    const timeout = withTimeout(input.timeoutMs);
+    try {
+        const response = await fetchWithRetry(fetchFn, endpoint, {
+            method: 'GET',
+            headers: {
+                ...buildCliHeaders(),
+                ...(input.apiKey ? { 'X-API-Key': input.apiKey } : {}),
+            },
+            signal: timeout.signal,
+        }, 1);
+        if (!response.ok) {
+            throw new Error(mapLimitsStatusMessage(response.status));
+        }
+        const parsed = await parseJsonSafe(response);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Unexpected API response.');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const typed = error;
+        if (typed.name === 'AbortError') {
+            throw new Error('Cannot reach skillguard.ai. Check your connection.');
+        }
+        if (typed.message === 'Unexpected API response.') {
+            throw typed;
+        }
+        if (typed.message.includes('Invalid API key.') ||
+            typed.message.includes('Access denied') ||
+            typed.message.includes('Rate limit exceeded.') ||
+            typed.message.includes('SkillGuard API error.') ||
+            typed.message.includes('SkillGuard limits request failed.')) {
+            throw typed;
+        }
+        throw new Error('Cannot reach skillguard.ai. Check your connection.');
+    }
+    finally {
+        timeout.cancel();
+    }
+}
 export async function fetchJwks(input) {
     const fetchFn = input.fetchImpl || fetch;
     const endpoint = `${input.baseUrl}/.well-known/skillguard-jwks.json`;

package/dist/lib/help.d.ts

@@ -0,0 +1,2 @@
+export declare function renderGeneralHelp(version: string): string;
+export declare function renderTopicHelp(command: string | undefined): string | null;

package/dist/lib/help.js

@@ -0,0 +1,240 @@
+const COMMAND_ALIASES = {
+    man: 'help',
+};
+function normalizeTopic(topic) {
+    if (!topic) {
+        return null;
+    }
+    const normalized = topic.trim().toLowerCase();
+    const aliased = COMMAND_ALIASES[normalized] || normalized;
+    if (aliased === 'help' ||
+        aliased === 'init' ||
+        aliased === 'scan' ||
+        aliased === 'gate' ||
+        aliased === 'limits' ||
+        aliased === 'verify' ||
+        aliased === 'workflow') {
+        return aliased;
+    }
+    return null;
+}
+export function renderGeneralHelp(version) {
+    return `SkillGuard CLI ${version}
+
+Usage:
+  skillguard <command> [options]
+
+Core commands:
+  init        Save API key in local CLI config
+  scan        Scan one file or recursively scan a directory
+  gate        CI gate mode (0 pass, 1 fail)
+  limits      Show anonymous/owner/agent remaining limits
+  verify      Verify signed SKILL.md via SkillGuard JWKS
+  workflow    Generate GitHub Actions workflow file
+
+Help commands:
+  help [command]
+  man [command]
+
+Quick start:
+  skillguard scan SKILL.md
+  skillguard gate .
+  skillguard workflow
+  skillguard workflow --auto-gh-push
+
+Global flags:
+  -h, --help     Show help
+  -v, --version  Show version
+  --workflow     Alias for "workflow"
+
+Run "skillguard help <command>" for full command details.`;
+}
+function renderHelpCommandHelp() {
+    return `NAME
+  skillguard help, skillguard man - show detailed command help
+
+SYNOPSIS
+  skillguard help [command]
+  skillguard man [command]
+
+DESCRIPTION
+  Shows command-level help in a man-page style format.
+  If no command is provided, prints general CLI help.
+
+EXAMPLES
+  skillguard help scan
+  skillguard man workflow`;
+}
+function renderInitHelp() {
+    return `NAME
+  skillguard init - save API key in local config
+
+SYNOPSIS
+  skillguard init [--api-key <key>] [--base-url <url>]
+
+DESCRIPTION
+  Writes ~/.config/skillguard/config.json with apiKey and apiUrl.
+  If --api-key is omitted, prompts interactively.
+
+OPTIONS
+  --api-key <key>     API key to persist
+  --base-url <url>    API base URL (default: https://skillguard.ai)
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 external runtime error`;
+}
+function renderScanHelp() {
+    return `NAME
+  skillguard scan - scan SKILL.md content for risk
+
+SYNOPSIS
+  skillguard scan [path] [options]
+
+DESCRIPTION
+  Scans one file or recursively scans a directory for SKILL.md files.
+  If no path is provided, scans from current directory.
+  If no API key is configured, uses anonymous mode (rate-limited).
+
+OPTIONS
+  --json                       Machine-readable JSON output
+  --fail-on <safe|warning|dangerous>
+                               Explicit threshold mode (exit 0/1)
+  --timeout <ms>              Request timeout (default: 30000)
+  --base-url <url>            API base URL
+  --api-key <key>             Override API key
+  --dry-run                   Show target files, skip API call
+  --quiet                     Suppress output, keep exit code
+  --no-color                  Disable ANSI colors
+  --skip-node-modules         Skip node_modules (default: enabled)
+  --scan-all                  Disable skip filters for recursive scan
+
+EXIT CODES
+  default mode (no --fail-on): safe=0, warning=1, dangerous=2
+  threshold mode (--fail-on): 0 below threshold, 1 threshold reached
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderGateHelp() {
+    return `NAME
+  skillguard gate - CI gate mode for deterministic pass/fail
+
+SYNOPSIS
+  skillguard gate [path] [options]
+
+DESCRIPTION
+  Wrapper around scan with explicit threshold mode enabled.
+  Default fail-on is warning.
+
+OPTIONS
+  Same as "skillguard scan".
+  --fail-on defaults to warning in gate mode.
+
+EXIT CODES
+  0 below threshold
+  1 threshold reached
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderLimitsHelp() {
+    return `NAME
+  skillguard limits - show remaining limits/quota
+
+SYNOPSIS
+  skillguard limits [--json] [--timeout <ms>] [--base-url <url>] [--api-key <key>] [--no-color]
+
+DESCRIPTION
+  Fetches /api/v1/limits and prints current request mode:
+  anonymous, owner, or agent.
+
+OPTIONS
+  --json             JSON output
+  --timeout <ms>     Request timeout (default: 30000)
+  --base-url <url>   API base URL
+  --api-key <key>    Optional API key
+  --no-color         Disable ANSI colors
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderVerifyHelp() {
+    return `NAME
+  skillguard verify - verify signed SKILL.md content
+
+SYNOPSIS
+  skillguard verify <path> [--json] [--timeout <ms>] [--base-url <url>]
+
+DESCRIPTION
+  Verifies SkillGuard Ed25519 signature and content hash using JWKS.
+
+OPTIONS
+  --json             JSON output
+  --timeout <ms>     Request timeout (default: 30000)
+  --base-url <url>   API base URL
+
+EXIT CODES
+  0 signature valid
+  1 invalid/tampered/expired signature
+  4 usage/input/config error
+  5 network/API/runtime failure`;
+}
+function renderWorkflowHelp() {
+    return `NAME
+  skillguard workflow - generate GitHub Actions workflow for CI gate
+
+SYNOPSIS
+  skillguard workflow [options]
+  skillguard --workflow [options]
+
+DESCRIPTION
+  Writes .github/workflows/skillguard.yml configured to run:
+  npx @skillguard/cli gate . --fail-on warning
+
+OPTIONS
+  --path <file>              Output workflow path
+                             (default: .github/workflows/skillguard.yml)
+  --scan-path <path>         Path passed to gate command (default: .)
+  --fail-on <safe|warning|dangerous>
+                             Gate threshold (default: warning)
+  --print                    Print YAML to stdout, do not write files
+  --force                    Overwrite existing file
+  --auto-gh-push             Run git add/commit/push after writing
+
+EXIT CODES
+  0 success
+  4 usage/input/config error
+  5 runtime/git failure
+
+EXAMPLES
+  skillguard workflow
+  skillguard workflow --print
+  skillguard workflow --auto-gh-push
+  skillguard --workflow --force`;
+}
+export function renderTopicHelp(command) {
+    const topic = normalizeTopic(command);
+    if (!topic) {
+        return null;
+    }
+    switch (topic) {
+        case 'help':
+            return renderHelpCommandHelp();
+        case 'init':
+            return renderInitHelp();
+        case 'scan':
+            return renderScanHelp();
+        case 'gate':
+            return renderGateHelp();
+        case 'limits':
+            return renderLimitsHelp();
+        case 'verify':
+            return renderVerifyHelp();
+        case 'workflow':
+            return renderWorkflowHelp();
+        default:
+            return null;
+    }
+}

package/dist/lib/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION = "0.4.0";

package/dist/lib/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = '0.4.0';

package/package.json

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