@vigilbase/cli 0.2.1 → 0.2.2

package/dist/commands/one.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { executeOneOperation, formatOnePayload } from '../lib/one-operations.js';
 import { assertCommandFlags, ok, outputJson, requireOneClient, withSpinner } from './helpers.js';
+import { missingArguments } from './legacy-validation.js';
 const regions = ['ams', 'nyc', 'lon', 'sgp', 'iad', 'sfo', 'fra', 'dub', 'tok', 'syd', 'cpt', 'gru', 'dxb', 'ewr', 'lhr', 'jnb', 'atl', 'blr', 'bom', 'cdg', 'del', 'dfw', 'hnl', 'icn', 'itm', 'lax', 'mad', 'man', 'mel', 'mex', 'mia', 'mxp', 'nrt', 'ord', 'sao', 'scl', 'sea', 'sjc', 'sto', 'tlv', 'waw', 'yto'];
 function flag(ctx, name, max = 2048) {
     const value = ctx.values[name];
@@ -26,8 +27,28 @@ function identifier(value) {
         throw new Error('An ID containing only letters, numbers, underscores, or hyphens is required.');
     return result.data;
 }
+const customerSubcommands = ['show', 'summary', 'services', 'endpoints', 'contacts', 'organization', 'watchdog-targets', 'watchdog-scans', 'reports', 'investigations', 'contracts', 'billing', 'invoices', 'subscriptions', 'projects'];
+/** Positional placeholders of each subcommand (as in ONE_HELP), so a missing argument is named. */
+const POSITIONALS = {
+    customers: {
+        ...Object.fromEntries(customerSubcommands.map((command) => [command, '<customer-id>'])),
+        report: '<customer-id> <report-id>',
+        investigation: '<customer-id> <investigation-id>',
+    },
+    orgs: { show: '<organization-id>' },
+    monitoring: { metrics: '<target-id>...', targets: '<customer-id>', status: '<customer-id>', history: '<customer-id>' },
+};
+function positionalUsage(ctx) {
+    const [command] = ctx.rest;
+    const placeholders = POSITIONALS[ctx.command];
+    if (command === undefined || !placeholders || !Object.hasOwn(placeholders, command))
+        return undefined;
+    return `vigilbase ${ctx.command} ${command} ${placeholders[command]}`;
+}
 function check(ctx, arity, flags = []) {
-    if (ctx.rest.length !== arity)
+    if (ctx.rest.length < arity)
+        throw new Error(missingArguments(ctx.command, arity - ctx.rest.length, positionalUsage(ctx)));
+    if (ctx.rest.length > arity)
         throw new Error(`Unexpected arguments. Run \`vigilbase ${ctx.command} --help\` for usage.`);
     assertCommandFlags(ctx, flags);
 }
@@ -114,8 +135,10 @@ export function buildOneOperation(ctx) {
             return operation(fleetRoutes[command]);
         }
         if (command === 'metrics') {
-            check(ctx, ctx.rest.length);
-            const ids = z.array(z.string().uuid()).min(1).max(50).parse(ctx.rest.slice(1));
+            check(ctx, Math.max(ctx.rest.length, 2));
+            const ids = ctx.rest.slice(1).map(uuid);
+            if (ids.length > 50)
+                throw new Error('monitoring metrics accepts at most 50 target IDs.');
             return operation('/api/monitoring/metrics', { target_ids: [...new Set(ids)].join(',') });
         }
         if (command === 'targets' || command === 'status' || command === 'history') {
@@ -133,8 +156,11 @@ export function buildOneOperation(ctx) {
         }
     }
     if (ctx.command === 'support' && command === 'tickets') {
-        check(ctx, ctx.rest.length === 0 ? 0 : 1, ['isAll', 'limit']);
-        return operation('/api/support/tickets', { includeAll: ctx.values.isAll ? true : undefined, limit: integer(ctx, 'limit', 1, 100) });
+        check(ctx, ctx.rest.length === 0 ? 0 : 1, ['isAll', 'limit', 'customer-id']);
+        return operation('/api/support/tickets', {
+            includeAll: ctx.values.isAll ? true : undefined, limit: integer(ctx, 'limit', 1, 100),
+            customerId: ctx.values['customer-id'] === undefined ? undefined : uuid(ctx.values['customer-id']),
+        });
     }
     throw new Error(`Unknown ${ctx.command} command: ${command}. Run \`vigilbase ${ctx.command} --help\` for usage.`);
 }
@@ -192,8 +218,9 @@ These commands read organization context; they do not switch the active organiza
   history <customer-id>   --range 24h|7d|30d --region CODE --target-id UUID
 All operations require read:monitoring and the API's tenant access checks.
 History defaults to 7d. Health metadata preserves unknown, partial, and unavailable states.`,
-    support: `Usage: vigilbase support tickets [--all] [--limit 1..100] [--json]
+    support: `Usage: vigilbase support tickets [--all] [--limit 1..100] [--customer-id <uuid>] [--json]
 Lists current organization's open tickets; --all includes closed tickets.
+Vigilbase staff must choose the customer with --customer-id.
 The API defaults to 50 results. Requires support:access and a linked Pylon account.
 The response retains hasMore; the API does not expose cursor pagination.`,
 };

package/dist/commands/public-tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { toolNameSchema, validateArguments } from './legacy-validation.js';
 import { NetworkError } from '../lib/network.js';
-import { VigilbaseApiError } from '../lib/client.js';
+import { PUBLIC_TOOLS_PATH, VigilbaseApiError } from '../lib/client.js';
 import { getOneAccessToken, getOptionalOneAccessToken, hasUsableSignIn, readCredentials } from '../auth/index.js';
 import { SignInUnsupportedError } from '../auth/store.js';
 import { formatExecuteResult, formatToolDescription, formatToolsList, } from '../lib/format.js';
@@ -58,7 +58,10 @@ export const handleList = async (ctx) => {
     return ok();
 };
 export const handleRun = async (ctx) => {
-    validateArguments(ctx, ctx.command === 'headers' || ctx.command === 'email' ? 1 : 2, ['via', 'isPublic']);
+    const usage = ctx.command === 'headers' ? 'vigilbase headers <url>'
+        : ctx.command === 'email' ? 'vigilbase email <domain>'
+            : 'vigilbase run <tool> <target>';
+    validateArguments(ctx, ctx.command === 'run' ? 2 : 1, ['via', 'isPublic'], usage);
     let toolName;
     let target;
     if (ctx.command === 'headers') {
@@ -73,11 +76,8 @@ export const handleRun = async (ctx) => {
         toolName = ctx.rest[0] ?? '';
         target = ctx.rest[1] ?? '';
     }
-    if (!toolName || !target) {
-        throw new Error(ctx.command === 'run'
-            ? 'Usage: vigilbase run <tool> <target>'
-            : `Usage: vigilbase ${ctx.command} <target>`);
-    }
+    if (!toolName || !target)
+        throw new Error(`Usage: ${usage}`);
     toolName = toolNameSchema.parse(toolName);
     target = z.string().trim().min(1).max(2048).refine((value) => !/[\u0000-\u001f\u007f]/.test(value), 'Target must not contain control characters.').parse(target);
     const via = ctx.values.via;
@@ -116,7 +116,7 @@ export const handleRun = async (ctx) => {
     return result.success ? ok() : EXIT.ERROR;
 };
 export const handleDescribe = async (ctx) => {
-    validateArguments(ctx, 1, ['isNoSkill']);
+    validateArguments(ctx, 1, ['isNoSkill'], 'vigilbase describe <tool>');
     toolNameSchema.parse(ctx.rest[0]);
     const toolName = ctx.rest[0];
     if (!toolName)
@@ -139,7 +139,7 @@ export const handleDescribe = async (ctx) => {
     return ok();
 };
 export const handleSkill = async (ctx) => {
-    validateArguments(ctx, 1);
+    validateArguments(ctx, 1, [], 'vigilbase skill <tool>');
     toolNameSchema.parse(ctx.rest[0]);
     const toolName = ctx.rest[0];
     if (!toolName)
@@ -163,7 +163,7 @@ export const handleSkill = async (ctx) => {
     return ok();
 };
 export const handleBadge = async (ctx) => {
-    validateArguments(ctx, 1, ['style']);
+    validateArguments(ctx, 1, ['style'], 'vigilbase badge <domain>');
     const domain = ctx.rest[0];
     if (!domain)
         throw new Error('Usage: vigilbase badge <domain>');
@@ -230,7 +230,7 @@ export const handleDoctor = async (ctx) => {
         };
     };
     const checks = {
-        publicApi: checkResult(publicResult, `${ctx.config.publicBaseUrl}/api/agent/tools`),
+        publicApi: checkResult(publicResult, `${ctx.config.publicBaseUrl}${PUBLIC_TOOLS_PATH}`),
         one: checkResult(oneResult, oneCheckUrl),
         signIn: checkResult(signInResult),
     };

package/dist/commands/runs.js

@@ -10,7 +10,7 @@ export const handleRuns = async (ctx) => {
         toolName = toolNameSchema.optional().parse(ctx.values.tool);
     }
     else if (subcommand === 'get' || subcommand === 'show') {
-        validateArguments(ctx, 2);
+        validateArguments(ctx, 2, [], `vigilbase runs ${subcommand} <UUID>`);
         z.string().uuid().parse(ctx.rest[1]);
     }
     else if (z.string().uuid().safeParse(subcommand).success)

package/dist/commands/security.d.ts

@@ -2,4 +2,4 @@ import { type SecurityRequest } from '../lib/security-client.js';
 import { type CommandContext, type CommandHandler } from './helpers.js';
 export declare function buildSecurityRequest(ctx: CommandContext): SecurityRequest;
 export declare const handleSecurity: CommandHandler;
-export declare const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections                            --asset-id\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";
+export declare const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections --asset-id <asset-id>\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";

package/dist/commands/security.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { SecurityClient } from '../lib/security-client.js';
 import { assertCommandFlags, asArray, asRecord, ok, outputJson, requireOneClient, withSpinner } from './helpers.js';
+import { missingArguments } from './legacy-validation.js';
 const statuses = ['open', 'active', 'acknowledged', 'investigating', 'mitigating', 'mitigated', 'resolved', 'false_positive'];
 const updateStatuses = ['acknowledged', 'mitigating', 'resolved', 'false_positive'];
 function textFlag(ctx, flag) {
@@ -20,8 +21,11 @@ function integer(ctx, flag, max, fallback) {
 function allowed(ctx, flags) {
     assertCommandFlags(ctx, [...flags, 'customer-id']);
 }
-function arity(ctx, length) {
-    if (ctx.rest.length !== length)
+/** `usage` follows `vigilbase security` and ends with the positional placeholders, so a missing one is named. */
+function arity(ctx, length, usage) {
+    if (ctx.rest.length < length)
+        throw new Error(missingArguments('security', length - ctx.rest.length, usage && `vigilbase security ${usage}`));
+    if (ctx.rest.length > length)
         throw new Error('Unexpected security arguments. Run `vigilbase security --help` for usage.');
 }
 function uuid(value) {
@@ -92,7 +96,7 @@ function extendedSecurityRequest(ctx, scope) {
         const views = { 'device-health': 'deviceHealth', 'app-tests': 'appTests', gateway: 'gateway', access: 'access', sessions: 'sessions', 'device-posture': 'devicePosture' };
         if (!sub || !views[sub])
             throw new Error('Choose a zero-trust command: device-health, app-tests, gateway, access, sessions, device-posture.');
-        arity(ctx, sub === 'gateway' ? 3 : 2);
+        arity(ctx, sub === 'gateway' ? 3 : 2, 'zero-trust gateway <dns|http|network>');
         const query = window();
         if (sub === 'gateway')
             query.surface = z.enum(['dns', 'http', 'network']).parse(id);
@@ -128,28 +132,28 @@ function extendedSecurityRequest(ctx, scope) {
     }
     if (group === 'assets' && sub !== undefined) {
         const routes = {
-            allowlist: [`/domains/${uuid(id)}/allowlist`, 'ipList'], blocklist: [`/domains/${uuid(id)}/blocklist`, 'ipList'],
-            remediation: [`/assets/${uuid(id)}/remediation-settings`, 'assetRemediation'], autonomy: [`/assets/${uuid(id)}/vigil-autonomy`, 'autonomy'],
-            datasets: [`/fabric/assets/${uuid(id)}/datasets`, 'datasets'], graph: [`/fabric/assets/${uuid(id)}/graph`, 'graph'],
+            allowlist: (assetId) => [`/domains/${assetId}/allowlist`, 'ipList'], blocklist: (assetId) => [`/domains/${assetId}/blocklist`, 'ipList'],
+            remediation: (assetId) => [`/assets/${assetId}/remediation-settings`, 'assetRemediation'], autonomy: (assetId) => [`/assets/${assetId}/vigil-autonomy`, 'autonomy'],
+            datasets: (assetId) => [`/fabric/assets/${assetId}/datasets`, 'datasets'], graph: (assetId) => [`/fabric/assets/${assetId}/graph`, 'graph'],
         };
-        const route = routes[sub];
+        const route = Object.hasOwn(routes, sub) ? routes[sub] : undefined;
         if (!route)
             throw new Error(`Unknown assets command: ${sub}`);
-        arity(ctx, 3);
+        arity(ctx, 3, `assets ${sub} <asset-id>`);
         if (sub !== 'graph')
             allowed(ctx, []);
-        return request(...route, sub === 'graph' ? graph(false) : {});
+        return request(...route(uuid(id)), sub === 'graph' ? graph(false) : {});
     }
     if (group === 'fabric') {
-        arity(ctx, 2);
-        allowed(ctx, []);
         if (sub !== 'default-asset')
             throw new Error('Usage: vigilbase security fabric default-asset');
+        arity(ctx, 2);
+        allowed(ctx, []);
         return request('/fabric/default-asset', 'defaultAsset');
     }
     if (group === 'connections' && sub && ['available-assets', 'remediation', 'logpush-status', 'worker-stats'].includes(sub)) {
         const isJob = sub === 'logpush-status' || sub === 'worker-stats';
-        arity(ctx, isJob ? 4 : 3);
+        arity(ctx, isJob ? 4 : 3, isJob ? `connections ${sub} <connection-id> <job-id>` : `connections ${sub} <id>`);
         allowed(ctx, []);
         const connectionId = uuid(id);
         if (sub === 'available-assets')
@@ -165,7 +169,7 @@ function extendedSecurityRequest(ctx, scope) {
     }
     if (group === 'alerts') {
         if (sub === 'show' || sub === 'get') {
-            arity(ctx, 3);
+            arity(ctx, 3, `alerts ${sub} <id>`);
             allowed(ctx, []);
             return request(`/alerts/${uuid(id)}`, 'alert');
         }
@@ -179,7 +183,7 @@ function extendedSecurityRequest(ctx, scope) {
         return request('/alerts', 'alerts', { limit: integer(ctx, 'limit', 100, 100), asset_id: ctx.values['asset-id'] !== undefined ? uuid(ctx.values['asset-id']) : undefined, since });
     }
     if (group === 'incidents' && (sub === 'fabric' || sub === 'share-links')) {
-        arity(ctx, 3);
+        arity(ctx, 3, `incidents ${sub} <id>`);
         if (sub === 'share-links')
             allowed(ctx, []);
         return request(`/incidents/${uuid(id)}/${sub}`, sub === 'fabric' ? 'graph' : 'shareLinks', sub === 'fabric' ? graph(true) : {});
@@ -211,17 +215,17 @@ export function buildSecurityRequest(ctx) {
     }
     if (['incidents', 'connections', 'reports'].includes(group)) {
         if (command === 'show' || command === 'get') {
-            arity(ctx, 3);
+            arity(ctx, 3, `${group} ${command} <id>`);
             allowed(ctx, []);
             return request(`/${group}/${uuid(ctx.rest[2])}`, group === 'incidents' ? 'incident' : group === 'connections' ? 'connection' : 'report');
         }
         if (group === 'incidents' && command === 'timeline') {
-            arity(ctx, 3);
+            arity(ctx, 3, 'incidents timeline <id>');
             allowed(ctx, ['before', 'limit']);
             return request(`/incidents/${uuid(ctx.rest[2])}/timeline`, 'timeline', { limit: integer(ctx, 'limit', 200, 100), before: textFlag(ctx, 'before') });
         }
         if (group === 'incidents' && command === 'update') {
-            arity(ctx, 4);
+            arity(ctx, 4, 'incidents update <id> <status>');
             allowed(ctx, ['note', 'isConfirm']);
             const id = uuid(ctx.rest[2]);
             const status = z.enum(updateStatuses).parse(ctx.rest[3]);
@@ -250,10 +254,18 @@ export function buildSecurityRequest(ctx) {
             order_direction: z.enum(['asc', 'desc']).optional().parse(textFlag(ctx, 'order-direction')),
         });
     }
-    if (group === 'assets' || group === 'detections') {
+    if (group === 'assets') {
+        arity(ctx, 1);
+        allowed(ctx, []);
+        return request('/domains', 'assets');
+    }
+    if (group === 'detections') {
+        // Detections are configured per asset; the API has no tenant-wide list.
         arity(ctx, 1);
-        allowed(ctx, group === 'detections' ? ['asset-id'] : []);
-        return request(group === 'assets' ? '/domains' : '/detections', group, group === 'detections' && ctx.values['asset-id'] !== undefined ? { asset_id: uuid(ctx.values['asset-id']) } : {});
+        allowed(ctx, ['asset-id']);
+        if (ctx.values['asset-id'] === undefined)
+            throw new Error('security detections requires --asset-id <uuid>. List asset IDs with `vigilbase security assets`.');
+        return request('/detections', 'detections', { asset_id: uuid(ctx.values['asset-id']) });
     }
     if (group === 'logs') {
         arity(ctx, 1);
@@ -289,7 +301,7 @@ export function buildSecurityRequest(ctx) {
             arity(ctx, 2);
             return request('/intel/quota', 'quota');
         }
-        arity(ctx, 3);
+        arity(ctx, 3, 'intel <ip|asn|cidr|ja3|ja4> <query>');
         const type = z.enum(['ip', 'asn', 'cidr', 'ja3', 'ja4']).parse(command);
         const q = z.string().trim().min(1).max(512).parse(ctx.rest[2]);
         return request('/intel/lookup', 'intel', { q, type });
@@ -387,4 +399,4 @@ export const handleSecurity = async (ctx) => {
         display(ctx, request, payload);
     return ok();
 };
-export const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections                            --asset-id\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";
+export const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections --asset-id <asset-id>\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";

package/dist/lib/client.d.ts

@@ -7,15 +7,20 @@ export declare class VigilbaseApiError extends Error {
     readonly code?: string;
     /** The server's sanitised explanation, set only for known vigilbase.com problem errors. */
     readonly reason?: string;
+    /** CLI-authored remediation, never server text (see one-error-hints.ts). */
+    readonly hint?: string;
     constructor(message: string, options: {
         status: number;
         body?: unknown;
         retryAfterSec?: number;
         code?: string;
         reason?: string;
+        hint?: string;
     });
 }
 export declare function retryAfterSeconds(response: Response, body: unknown): number | undefined;
+/** The versioned public tools API. The unversioned /api/agent/tools aliases sunset on 2027-09-01. */
+export declare const PUBLIC_TOOLS_PATH = "/api/v1/agent/tools";
 /**
  * Public (unauthenticated) vigilbase.com tools client.
  * Vigilbase One authenticated calls will use a separate client + device-auth tokens.

package/dist/lib/client.js

@@ -10,6 +10,8 @@ export class VigilbaseApiError extends Error {
     code;
     /** The server's sanitised explanation, set only for known vigilbase.com problem errors. */
     reason;
+    /** CLI-authored remediation, never server text (see one-error-hints.ts). */
+    hint;
     constructor(message, options) {
         super(message);
         this.name = 'VigilbaseApiError';
@@ -18,6 +20,7 @@ export class VigilbaseApiError extends Error {
         this.retryAfterSec = options.retryAfterSec;
         this.code = options.code;
         this.reason = options.reason;
+        this.hint = options.hint;
     }
 }
 export function retryAfterSeconds(response, body) {
@@ -68,6 +71,8 @@ function publicApiError(fallback, response, body) {
         reason: reason?.message,
     });
 }
+/** The versioned public tools API. The unversioned /api/agent/tools aliases sunset on 2027-09-01. */
+export const PUBLIC_TOOLS_PATH = '/api/v1/agent/tools';
 /**
  * Public (unauthenticated) vigilbase.com tools client.
  * Vigilbase One authenticated calls will use a separate client + device-auth tokens.
@@ -93,7 +98,7 @@ export class VigilbaseClient {
         return { response, body: parseJsonResponse(response, text) };
     }
     async listTools() {
-        const { response, body } = await this.request('/api/agent/tools');
+        const { response, body } = await this.request(PUBLIC_TOOLS_PATH);
         if (!response.ok) {
             throw publicApiError(`Failed to list tools (HTTP ${response.status})`, response, body);
         }
@@ -110,7 +115,7 @@ export class VigilbaseClient {
         return body;
     }
     async executeTool(toolName, target) {
-        const { response, body } = await this.request(`/api/agent/tools/${encodeURIComponent(toolName)}/execute`, {
+        const { response, body } = await this.request(`${PUBLIC_TOOLS_PATH}/${encodeURIComponent(toolName)}/execute`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ target }),

package/dist/lib/cloudflare-client.js

@@ -61,7 +61,7 @@ export class CloudflareClient {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ customerId: scope.customerId, accountId: scope.accountId }),
-            });
+            }, { hasCustomerScope: Boolean(scope.customerId) });
         }
         const params = new URLSearchParams();
         if (scope.customerId)

package/dist/lib/help.d.ts

@@ -1,3 +1,6 @@
 export declare const HELP_TAGLINE = "one \u00B7 security \u00B7 tools";
+/** A tool from the catalog the CLI knows offline: it runs as `run <tool> <target>`, not as a command. */
+export declare function isCatalogTool(name: string): boolean;
 export declare const HELP_TEXT: string;
+export declare const HELP_USAGE = "Usage: vigilbase help [<command> | <tool>]";
 export declare function helpForCommand(command: string): string | null;

package/dist/lib/help.js

@@ -2,7 +2,21 @@ import { CLOUDFLARE_HELP } from '../commands/cloudflare.js';
 import { LOCAL_HELP } from '../commands/local.js';
 import { ONE_HELP } from '../commands/one.js';
 import { SECURITY_HELP } from '../commands/security.js';
+import { isOneAuthRequiredTool, ONE_AUTH_REQUIRED_TOOLS } from './one-client.js';
 export const HELP_TAGLINE = 'one · security · tools';
+/** vigilbase.com's public catalog, with each tool's shortcut command. `help <tool>` answers offline. */
+const PUBLIC_TOOL_SHORTCUTS = {
+    'security-headers': 'headers <url>',
+    'email-security': 'email <domain>',
+};
+const PUBLIC_TOOLS = Object.keys(PUBLIC_TOOL_SHORTCUTS);
+function isPublicTool(name) {
+    return Object.hasOwn(PUBLIC_TOOL_SHORTCUTS, name);
+}
+/** A tool from the catalog the CLI knows offline: it runs as `run <tool> <target>`, not as a command. */
+export function isCatalogTool(name) {
+    return isPublicTool(name) || isOneAuthRequiredTool(name);
+}
 /** Column where descriptions start in the main help: two-space indent, term, at least two spaces. */
 const DESCRIPTION_COLUMN = 31;
 /** Two-column help rows whose descriptions all start at DESCRIPTION_COLUMN. */
@@ -32,7 +46,7 @@ Public tools (no login)
   badge <domain> · doctor      Badge URL · connectivity
 
 Auth-required tools (after login)
-  website-security · react2shell · fortibleed-check
+${ONE_AUTH_REQUIRED_TOOLS.map((tool) => `  run ${tool} <target>`).join('\n')}
 
 On this machine (no login)
   cloudflare-checkup           Run the Cloudflare Checkup on this machine in one
@@ -57,7 +71,7 @@ Account (login required)
 Options
 ${GLOBAL_OPTIONS}
 
-Use vigilbase <command> --help for command options.
+Use vigilbase <command> --help or vigilbase help <tool> for usage.
 
 Examples
   vigilbase headers https://vigilbase.com
@@ -68,16 +82,40 @@ Examples
   vigilbase cf zones
   vigilbase security incidents --severity high
 `;
+/** How to run a catalog tool: `help <tool>` and `<tool> --help`, since tools run as `run <tool> <target>`. */
+function helpForTool(tool) {
+    if (isPublicTool(tool)) {
+        return `Usage: vigilbase run ${tool} <target> [--json] [--via public|one] [--public]
+
+Public tool, no login needed. Shortcut: vigilbase ${PUBLIC_TOOL_SHORTCUTS[tool]}
+Details: vigilbase describe ${tool}`;
+    }
+    if (isOneAuthRequiredTool(tool)) {
+        return `Usage: vigilbase run ${tool} <target> [--json]
+
+Runs through Vigilbase One: run \`vigilbase login\` first.
+Details: vigilbase describe ${tool}`;
+    }
+    return null;
+}
+export const HELP_USAGE = 'Usage: vigilbase help [<command> | <tool>]';
 export function helpForCommand(command) {
     switch (command) {
+        case 'help':
+            return `${HELP_USAGE}
+
+Shows the usage of a command or of a tool, for example vigilbase help run or
+vigilbase help website-security. Without one, shows every command.`;
         case 'tools':
         case 'list':
             return `Usage: vigilbase list [--json]`;
         case 'run':
             return `Usage: vigilbase run <tool> <target> [--json] [--via public|one] [--public]
 
-Public: security-headers, email-security
-Login:  website-security, react2shell, fortibleed-check`;
+Public: ${PUBLIC_TOOLS.join(', ')}
+Login:  ${ONE_AUTH_REQUIRED_TOOLS.join(', ')}
+
+Run vigilbase help <tool> for a tool's usage.`;
         case 'describe':
             return `Usage: vigilbase describe <tool> [--json] [--no-skill]`;
         case 'skill':
@@ -131,6 +169,6 @@ Prefer --token-stdin with piped input to keep tokens out of command arguments.`;
         case 'email':
             return `Usage: vigilbase email <domain> [--json] [--via public|one] [--public]`;
         default:
-            return null;
+            return helpForTool(command);
     }
 }

package/dist/lib/one-client.d.ts

@@ -54,6 +54,8 @@ export declare class VigilbaseOneClient {
     /** Authenticated JSON transport shared by the One command clients. */
     requestJson<T extends ApiErrorBody = Record<string, unknown>>(path: string, init?: RequestInit, options?: {
         allowStatuses?: number[];
+        /** Whether the request names a customer outside the query string (a JSON body). */
+        hasCustomerScope?: boolean;
     }): Promise<T>;
     getSession(): Promise<OneSessionResponse>;
     getAccount(): Promise<Record<string, unknown>>;

package/dist/lib/one-client.js

@@ -6,6 +6,7 @@ import { z } from 'zod';
 import { validateOneOrigin } from './config.js';
 import { validateStripePortalUrl } from './open-url.js';
 import { parseJsonResponse, requestText } from './network.js';
+import { oneErrorHint } from './one-error-hints.js';
 import { retryAfterSeconds, VigilbaseApiError } from './client.js';
 /**
  * Tools that require Vigilbase One authentication (auth-required scanners).
@@ -129,9 +130,12 @@ export class VigilbaseOneClient {
         if (errorDetails.code === 'FLAREHAWK_VIEW_AS_REQUIRED') {
             message = 'Select a customer with --customer-id <customer UUID> for security commands.';
         }
+        const hint = response.ok ? undefined : oneErrorHint({
+            method: init?.method ?? 'GET', path, status: response.status, code: errorDetails.code, hasCustomerScope: options?.hasCustomerScope,
+        });
         if (response.status === 401 || response.status === 403) {
             throw new VigilbaseApiError(message ||
-                'Authentication required. Run `vigilbase login`.', { status: response.status, body: parsed, code: errorDetails.code });
+                'Authentication required. Run `vigilbase login`.', { status: response.status, body: parsed, code: errorDetails.code, hint });
         }
         if (response.status === 429) {
             throw new VigilbaseApiError(message || 'Rate limit exceeded.', {
@@ -144,7 +148,7 @@ export class VigilbaseOneClient {
         const allowed = options?.allowStatuses ?? [];
         if (!response.ok && !allowed.includes(response.status)) {
             throw new VigilbaseApiError(message ||
-                `Request failed (HTTP ${response.status})`, { status: response.status, body: parsed, code: errorDetails.code });
+                `Request failed (HTTP ${response.status})`, { status: response.status, body: parsed, code: errorDetails.code, hint });
         }
         if (!z.record(z.string(), z.unknown()).safeParse(body).success) {
             throw new VigilbaseApiError('Invalid One API response. Expected a JSON object.', { status: response.status });

package/dist/lib/one-error-hints.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI-authored hints for One errors the CLI recognises. They are chosen only
+ * from the request (method, route, whether a customer was selected), the HTTP
+ * status and One's own error codes. One's free-text messages are never shown:
+ * they can describe its configuration.
+ */
+export declare const STAFF_CUSTOMER_SCOPE_HINT = "Vigilbase staff: add --customer-id <uuid>.";
+export declare const PERSONAL_SETTINGS_HINT = "Personal settings belong to each user, so View-as (--customer-id) cannot read them.";
+export declare const BROWSER_SESSION_HINT = "Invitations need a One browser session: manage them at https://one.vigilbase.com.";
+export type OneErrorContext = {
+    method: string;
+    /** The One path the CLI requested, with its query string. */
+    path: string;
+    status: number;
+    code?: string;
+    /** Whether the request named a customer; defaults to a `customerId` query parameter. */
+    hasCustomerScope?: boolean;
+};
+export declare function oneErrorHint(context: OneErrorContext): string | undefined;

package/dist/lib/one-error-hints.js

@@ -0,0 +1,47 @@
+/**
+ * CLI-authored hints for One errors the CLI recognises. They are chosen only
+ * from the request (method, route, whether a customer was selected), the HTTP
+ * status and One's own error codes. One's free-text messages are never shown:
+ * they can describe its configuration.
+ */
+export const STAFF_CUSTOMER_SCOPE_HINT = 'Vigilbase staff: add --customer-id <uuid>.';
+export const PERSONAL_SETTINGS_HINT = 'Personal settings belong to each user, so View-as (--customer-id) cannot read them.';
+export const BROWSER_SESSION_HINT = 'Invitations need a One browser session: manage them at https://one.vigilbase.com.';
+/** One's security boundary codes that already explain a 403 (apps/one/src/lib/flarehawk/access.ts). */
+const SECURITY_ACCESS_CODES = new Set([
+    'FLAREHAWK_CUSTOMER_ACCESS_DENIED',
+    'FLAREHAWK_ROLE_UNSUPPORTED',
+    'FLAREHAWK_ROLE_INSUFFICIENT',
+    'FLAREHAWK_ORGANIZATION_REQUIRED',
+    'FLAREHAWK_VIEW_AS_REQUIRED',
+]);
+const RULES = [
+    // Staff sessions must name the customer; One answers 400 without one.
+    { method: 'GET', route: /^\/api\/support\/tickets$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    { method: 'GET', route: /^\/api\/services\/cloudflare\/checkups$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    { method: 'POST', route: /^\/api\/services\/cloudflare\/checkups\/start$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    { method: 'GET', route: /^\/api\/services\/cloudflare\/workspace(?:\/[a-z-]+)?$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    // Personal security settings are per user; a View-as read is refused.
+    {
+        method: 'GET',
+        route: /^\/api\/flarehawk\/(?:settings\/(?:lifecycle-emails|broadcast-emails)|integrations\/grants|notifications\/preferences)$/u,
+        status: 403,
+        hasCustomerScope: true,
+        hint: PERSONAL_SETTINGS_HINT,
+        excludedCodes: SECURITY_ACCESS_CODES,
+    },
+    // Identity's management API accepts only One browser sessions, so CLI tokens can't read or send invitations.
+    { method: 'GET', route: /^\/api\/auth\/orgs\/invitations$/u, status: 403, hasCustomerScope: false, hint: BROWSER_SESSION_HINT, code: 'browser_session_required' },
+    { method: 'POST', route: /^\/api\/auth\/orgs\/invite$/u, status: 403, hasCustomerScope: false, hint: BROWSER_SESSION_HINT, code: 'browser_session_required' },
+];
+export function oneErrorHint(context) {
+    const [pathname = '', query = ''] = context.path.split('?', 2);
+    const hasCustomerScope = context.hasCustomerScope ?? new URLSearchParams(query).has('customerId');
+    const method = context.method.toUpperCase();
+    return RULES.find((rule) => rule.method === method &&
+        rule.status === context.status &&
+        rule.hasCustomerScope === hasCustomerScope &&
+        rule.route.test(pathname) &&
+        (rule.code === undefined || rule.code === context.code) &&
+        !(context.code !== undefined && rule.excludedCodes?.has(context.code)))?.hint;
+}

package/dist/local/cloudflare-checkup/errors.d.ts

@@ -10,6 +10,8 @@ export declare const LOCAL_ERROR_HINTS: Record<LocalCheckupErrorCode, string>;
  * hint names both ways out.
  */
 export declare const ENV_TOKEN_AUTH_HINT = "Set CLOUDFLARE_API_TOKEN in this shell to a valid read-only Cloudflare API token (read -rs CLOUDFLARE_API_TOKEN && export CLOUDFLARE_API_TOKEN) and run the same command again, or unset it (or use --cf-auth profile) to sign in with your browser instead.";
+/** SNAPSHOT_INVALID for an `inspect` or `submit` path with no file: nothing to collect again, so how to make one. */
+export declare const SNAPSHOT_MISSING_HINT = "Check the file path. To collect a snapshot into a file, run `npx @vigilbase/cli cloudflare-checkup collect --out <file>`.";
 /** CF_PERMISSION_DENIED in env mode: the token lacks a read permission; the browser sign-in is the other way out. */
 export declare const ENV_TOKEN_PERMISSION_HINT = "The API token in CLOUDFLARE_API_TOKEN cannot read everything the checkup needs. Add the read permissions to it, or unset it (or use --cf-auth profile) to sign in with your browser instead, then run the same command again.";
 export declare class LocalCheckupError extends Error {