@ciphrix/cli 0.1.0 → 0.2.0

package/README.md

@@ -72,8 +72,8 @@ changes show the proposed action and ask for confirmation; automation can opt in
 - **Manage operational registers** — work with assets, vendors, risks, treatments, ownership, and files.
 - **Operate monitoring** — inspect checks, resources, runs, findings, integrations, and background jobs.
 
-Names and stable Ciphrix codes are accepted throughout, so neither people nor agents need to work with
-opaque database identifiers.
+Established record commands accept names and stable Ciphrix codes where advertised. Access inventory,
+review tasks and proposals require the exact IDs returned by their read commands; never guess identifiers.
 
 ## Built for agent workspaces
 
@@ -99,7 +99,9 @@ The skill works with compatible agent harnesses including Codex, Claude Code, Cu
 is also included in the npm package at [`skills/ciphrix/SKILL.md`](skills/ciphrix/SKILL.md). Installing
 the npm package never modifies an agent's configuration directories.
 
-Run `npx skills update` to update installed skills when a newer version is available.
+Run `npx skills update` to update installed skills when a newer version is available. Keep the skill
+aligned with your installed CLI version; its generated command reference and local help describe the
+available grammar. Server capability discovery remains authoritative for which operations you can use.
 
 ### Ask in natural language, operate through the CLI
 
@@ -155,6 +157,47 @@ one command. Installed help is authoritative. The complete generated reference i
 
 </details>
 
+### Context, reviews and agent-assisted work
+
+The onboarding group reads separate Business and Operating Context, saves agreed questionnaire answers,
+and offers explicit optional setup and completion. Business Context readiness is decided by the server;
+Operating Context and optional setup do not block journey completion. Saving context never automatically
+starts agents or completes the journey. Local `--help` works offline; `onboarding --help-onboarding`
+returns authenticated server guidance and the current status pack.
+
+The access group separates inventory, reviewed import proposals, assigned reviewer decisions and campaign
+results. A revoke decision records a removal request, not provider-side revocation. Recording decisions,
+completing a reviewer task, and ending a campaign are separate operations. Imports merge only explicitly
+selected reviewed rows; inspect per-row failures even when some rows applied.
+
+Agent findings and advisory test/control assessments do not make formal human decisions. Assigned-task
+discovery does not complete work. File staging and processing are explicit, separate operations; processing
+may update context or create vendors. Evidence/CSV commands return expiring signed references without
+automatically downloading files. Use each command's help for the exact inputs, next reads and effects.
+
+### Manifest compatibility, JSON and retries
+
+The CLI discovers allowed tools and their effects from the authenticated server manifest. New command
+groups require server-declared command bindings. An unavailable binding is reported as unsupported;
+the CLI never guesses a different endpoint or interprets the manifest as authorization. Existing
+commands keep their successful JSON formats. New capability commands emit complete success/error
+envelopes with `--json`, preserving warnings, pagination, truncation and structured error details.
+Failures and partially applied mutations return a nonzero exit status.
+
+Confirmed writes require explicit consent. New commands in JSON/non-interactive mode require `--yes`
+for confirmed operations; immediate writes do not accept that flag. Write controls are rejected for
+reads. The optional `--idempotency-key` names one logical write: reuse identical input for a retry,
+never a new key to bypass an unknown outcome. There are no automatic write retries. Confirmed replay
+also needs a valid confirmation token; a fresh invocation re-preflights and may be blocked by changed
+state or expiry. The CLI does not save confirmation tokens or promise recovery across invocations.
+Inspect current records/jobs when uncertain. Replayed status packs and signed URLs are original
+snapshots, not refreshed state or renewed downloads.
+
+Mutation JSON files must be regular files, at most 1 MiB, containing an explicitly selected array.
+Use clear flags or JSON null where supported, not the string `"null"`. Do not infer confirmations
+from suggested matches. New repeated flags collect separate values; existing command conventions remain
+compatible. See the generated command reference for all options and nested payload details.
+
 ## Safe by default
 
 - Credentials use the operating system keychain by default and are isolated by API environment.
@@ -164,7 +207,7 @@ one command. Installed help is authoritative. The complete generated reference i
 - Destructive and consequential actions require confirmation unless `--yes` is explicitly supplied.
 - JSON output is undecorated and suitable for programs and agents.
 - Requests time out, responses are size-limited, and local evidence uploads reject symbolic links and
-  files over 50 MiB.
+  files over 25 MiB.
 
 Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
 

package/dist/actions.d.ts

@@ -8,6 +8,8 @@ export interface ApplyOptions {
     fallback: string;
     yes?: boolean | undefined;
     confirm?: ((question: string) => Promise<boolean>) | undefined;
+    idempotencyKey?: string | undefined;
+    quiet?: boolean | undefined;
 }
 /**
  * Runs a tool, handling the two-step confirm contract when the tool requires it.
@@ -16,4 +18,4 @@ export interface ApplyOptions {
  * - Tools that require confirmation: the first call is a preflight (summary + token), the user is asked
  *   once, then the change is applied with the token and an idempotency key.
  */
-export declare const applyTool: ({ ctx, io, toolName, input, fallback, yes, confirm, }: ApplyOptions) => Promise<Record<string, unknown> | null>;
+export declare const applyTool: ({ ctx, io, toolName, input, fallback, yes, confirm, idempotencyKey: suppliedKey, quiet, }: ApplyOptions) => Promise<Record<string, unknown> | null>;

package/dist/actions.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { promptConfirm, writeLine } from './io.js';
+import { ApiError } from './api.js';
+import { getTool } from './manifest.js';
 import { asRecord, asText, callTool, errorMessage } from './toolSurface.js';
 /**
  * Runs a tool, handling the two-step confirm contract when the tool requires it.
@@ -8,23 +10,30 @@ import { asRecord, asText, callTool, errorMessage } from './toolSurface.js';
  * - Tools that require confirmation: the first call is a preflight (summary + token), the user is asked
  *   once, then the change is applied with the token and an idempotency key.
  */
-export const applyTool = async ({ ctx, io, toolName, input, fallback, yes = false, confirm, }) => {
+export const applyTool = async ({ ctx, io, toolName, input, fallback, yes = false, confirm, idempotencyKey: suppliedKey, quiet = false, }) => {
     const ask = confirm ?? ((question) => promptConfirm(io, question));
-    const idempotencyKey = randomUUID();
+    const idempotencyKey = suppliedKey ?? randomUUID();
+    const tool = await getTool(ctx, toolName);
+    if (tool.effect !== 'write')
+        throw new Error('Expected a write operation.');
     const first = await callTool(ctx, toolName, input, { idempotencyKey });
     if (first.status !== 'ok')
-        throw new Error(errorMessage(first, fallback));
+        throw new ApiError(errorMessage(first, fallback), 400, asText(asRecord(first.error).code), asRecord(first.error).details, first);
     const confirmation = asRecord(asRecord(first.meta).confirmation);
     const token = asText(confirmation.token);
-    if (!token)
+    if (tool.confirmation === 'none')
         return first;
-    writeLine(io.stdout, asText(confirmation.summary, 'Apply this change?'));
+    if (!token)
+        throw new Error('The server did not return the required confirmation token. No change was applied.');
+    if (!quiet)
+        writeLine(io.stdout, asText(confirmation.summary, 'Apply this change?'));
     if (!yes && !(await ask('Apply this change?'))) {
-        writeLine(io.stdout, 'Cancelled.');
+        if (!quiet)
+            writeLine(io.stdout, 'Cancelled.');
         return null;
     }
     const result = await callTool(ctx, toolName, input, { confirmationToken: token, idempotencyKey });
     if (result.status !== 'ok')
-        throw new Error(errorMessage(result, fallback));
+        throw new ApiError(errorMessage(result, fallback), 400, asText(asRecord(result.error).code), asRecord(result.error).details, result);
     return result;
 };

package/dist/api.d.ts

@@ -1,7 +1,9 @@
 export declare class ApiError extends Error {
     readonly status: number;
     readonly code: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
+    readonly details: unknown;
+    readonly envelope: unknown;
+    constructor(message: string, status: number, code?: string | undefined, details?: unknown, envelope?: unknown);
 }
 export interface RequestOptions {
     method?: string;

package/dist/api.js

@@ -1,11 +1,15 @@
 export class ApiError extends Error {
     status;
     code;
-    constructor(message, status, code = undefined) {
+    details;
+    envelope;
+    constructor(message, status, code = undefined, details = undefined, envelope = undefined) {
         super(message);
         this.name = 'ApiError';
         this.status = status;
         this.code = code;
+        this.details = details;
+        this.envelope = envelope;
     }
 }
 /** Default time allowed for an API request, including reading its response body. */
@@ -104,7 +108,7 @@ const errorPayload = (data) => {
             : typeof nested?.code === 'string'
                 ? nested.code
                 : undefined;
-    const details = Array.isArray(nested?.details) ? nested?.details : [];
+    const details = nested?.details;
     return { message, code, details };
 };
 /**
@@ -172,7 +176,7 @@ export const createApiClient = (baseUrl, limits = {}) => ({
             }
             if (!response.ok) {
                 const { message, code, details } = errorPayload(data);
-                throw new ApiError(withDetails(message || `Request failed with status ${response.status}`, code, details), response.status, code);
+                throw new ApiError(withDetails(message || `Request failed with status ${response.status}`, code, Array.isArray(details) ? details : []), response.status, code, details, data);
             }
             return data;
         });

package/dist/cli.js

@@ -1,4 +1,6 @@
 import { Command, CommanderError } from 'commander';
+import { registerCapabilities, RenderedCommandError } from './commands/capabilities.js';
+import { asRecord } from './toolSurface.js';
 import { formatBanner } from './banner.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
@@ -247,7 +249,9 @@ export const createProgram = (io = createDefaultIO()) => {
             json: readBooleanOption(options, 'json'),
         });
     });
-    const testRun = test.command('run').description('Create, result and delete runs');
+    const testRun = test
+        .command('run')
+        .description('Run lifecycle, human results/notes, linked evidence references and advisory assessments');
     testRun
         .command('create <name>')
         .description('Create a new pending run')
@@ -266,17 +270,21 @@ export const createProgram = (io = createDefaultIO()) => {
     testRun
         .command('result <name>')
         .description('Record a run result: passing | failing | skipped | pending (reopen)')
-        .requiredOption('--status <status>', 'passing | failing | skipped | pending')
+        .option('--status <status>', 'human-decided result: passing | failing | skipped | pending; omit for note-only changes')
         .option('--note <text>', 'note for the run')
+        .option('--clear-note', 'clear the note without changing the result; conflicts with --note')
         .option('--run <id>', 'a specific run')
         .option('--api-url <url>', 'override the API base URL for this command')
         .option('--json', 'output raw JSON')
         .action(async (name, options) => {
+        if (readBooleanOption(options, 'clearNote') &&
+            readStringOption(options, 'note') !== undefined)
+            throw new Error('--clear-note conflicts with --note.');
         await testRunResultCommand({
             io,
             name,
-            status: readStringOption(options, 'status') ?? '',
-            note: readStringOption(options, 'note'),
+            status: readStringOption(options, 'status'),
+            note: readBooleanOption(options, 'clearNote') ? null : readStringOption(options, 'note'),
             runId: readStringOption(options, 'run'),
             apiUrl: readStringOption(options, 'apiUrl'),
             json: readBooleanOption(options, 'json'),
@@ -305,6 +313,8 @@ export const createProgram = (io = createDefaultIO()) => {
         .requiredOption('--type <type>', 'item type: native_doc or check')
         .option('--run <id>', 'a specific run')
         .option('--search <text>', 'filter by item name')
+        .option('--page <n>', 'page number')
+        .option('--limit <n>', 'page size')
         .option('--api-url <url>', 'override the API base URL for this command')
         .option('--json', 'output raw JSON')
         .action(async (name, options) => {
@@ -314,6 +324,8 @@ export const createProgram = (io = createDefaultIO()) => {
             runId: readStringOption(options, 'run'),
             itemType: readStringOption(options, 'type') ?? 'native_doc',
             search: readStringOption(options, 'search'),
+            page: readNumberOption(options, 'page'),
+            limit: readNumberOption(options, 'limit'),
             apiUrl: readStringOption(options, 'apiUrl'),
             json: readBooleanOption(options, 'json'),
         });
@@ -454,6 +466,8 @@ export const createProgram = (io = createDefaultIO()) => {
         .description('List items that can be mapped to a clause')
         .requiredOption('--type <type>', 'item type: test or document')
         .option('--search <text>', 'filter by item name')
+        .option('--page <n>', 'page number')
+        .option('--limit <n>', 'page size')
         .option('--api-url <url>', 'override the API base URL for this command')
         .option('--json', 'output raw JSON')
         .action(async (frameworkName, clause, options) => {
@@ -463,6 +477,8 @@ export const createProgram = (io = createDefaultIO()) => {
             clause,
             itemType: readStringOption(options, 'type') ?? 'test',
             search: readStringOption(options, 'search'),
+            page: readNumberOption(options, 'page'),
+            limit: readNumberOption(options, 'limit'),
             apiUrl: readStringOption(options, 'apiUrl'),
             json: readBooleanOption(options, 'json'),
         });
@@ -523,10 +539,13 @@ export const createProgram = (io = createDefaultIO()) => {
         .command('list')
         .description('List assets with their code, status and classification')
         .option('--name <text>', 'filter by name')
-        .option('--category <value>', 'filter by category')
+        .option('--category <csv>', 'filter by category')
+        .option('--sub-category <csv>', 'filter by sub-category')
         .option('--status <csv>', 'filter by status')
-        .option('--business-impact <value>', 'filter by business impact')
-        .option('--data-classification <value>', 'filter by data classification')
+        .option('--business-impact <csv>', 'filter by business impact')
+        .option('--data-classification <csv>', 'filter by data classification')
+        .option('--source <csv>', 'filter by discovery source (provider, e.g. aws, azure, gcp)')
+        .option('--technical-owner-email <email>', 'filter by technical owner email')
         .option('--page <n>', 'page number')
         .option('--limit <n>', 'page size')
         .option('--api-url <url>', 'override the API base URL for this command')
@@ -536,9 +555,12 @@ export const createProgram = (io = createDefaultIO()) => {
             io,
             name: readStringOption(options, 'name'),
             category: readStringOption(options, 'category'),
+            subCategory: readStringOption(options, 'subCategory'),
             status: readStringOption(options, 'status'),
             businessImpact: readStringOption(options, 'businessImpact'),
             dataClassification: readStringOption(options, 'dataClassification'),
+            source: readStringOption(options, 'source'),
+            technicalOwnerEmail: readStringOption(options, 'technicalOwnerEmail'),
             page: readNumberOption(options, 'page'),
             limit: readNumberOption(options, 'limit'),
             apiUrl: readStringOption(options, 'apiUrl'),
@@ -756,7 +778,10 @@ export const createProgram = (io = createDefaultIO()) => {
         .description('Create a vendor')
         .requiredOption('--name <name>', 'vendor name')
         .option('--category <value>', 'category')
+        .option('--subcategory <value>', 'sub-category')
         .option('--criticality <value>', 'criticality')
+        .option('--data-sensitivity <value>', 'data sensitivity')
+        .option('--service-availability <value>', 'service availability')
         .option('--description <text>', 'description')
         .option('--api-url <url>', 'override the API base URL for this command')
         .option('--json', 'output raw JSON')
@@ -765,7 +790,10 @@ export const createProgram = (io = createDefaultIO()) => {
             io,
             name: readStringOption(options, 'name') ?? '',
             category: readStringOption(options, 'category'),
+            subcategory: readStringOption(options, 'subcategory'),
             criticality: readStringOption(options, 'criticality'),
+            dataSensitivity: readStringOption(options, 'dataSensitivity'),
+            serviceAvailability: readStringOption(options, 'serviceAvailability'),
             description: readStringOption(options, 'description'),
             apiUrl: readStringOption(options, 'apiUrl'),
             json: readBooleanOption(options, 'json'),
@@ -828,14 +856,16 @@ export const createProgram = (io = createDefaultIO()) => {
     });
     const control = program
         .command('control')
-        .description('Controls: status, applicability, owner and design requirements');
+        .description('Controls: status, applicability, ownership, design requirements and advisory assessments');
     control
         .command('list')
         .description('List controls with their status, applicability and owner')
+        .option('--framework <code>', 'filter by catalogue framework code; repeat for multiple values', (value, previous = []) => [...previous, value])
         .option('--search <text>', 'filter by name or code')
         .option('--domain <value>', 'filter by control domain')
         .option('--status <csv>', 'filter by status')
         .option('--applicability <value>', 'filter by applicability (in_scope|out_of_scope)')
+        .option('--owner <csv>', 'filter by owner user id')
         .option('--page <n>', 'page number')
         .option('--limit <n>', 'page size')
         .option('--api-url <url>', 'override the API base URL for this command')
@@ -843,10 +873,14 @@ export const createProgram = (io = createDefaultIO()) => {
         .action(async (options) => {
         await controlListCommand({
             io,
+            framework: Array.isArray(asRecord(options).framework)
+                ? asRecord(options).framework
+                : undefined,
             search: readStringOption(options, 'search'),
             domain: readStringOption(options, 'domain'),
             status: readStringOption(options, 'status'),
             applicability: readStringOption(options, 'applicability'),
+            ownerId: readStringOption(options, 'owner'),
             page: readNumberOption(options, 'page'),
             limit: readNumberOption(options, 'limit'),
             apiUrl: readStringOption(options, 'apiUrl'),
@@ -914,6 +948,7 @@ export const createProgram = (io = createDefaultIO()) => {
         .option('--justification <text>', 'why the applicability changed')
         .option('--design-requirements <state>', 'not_assessed | not_needed | not_met | partial | met')
         .option('--notes <text>', 'notes (Markdown)')
+        .option('--description <text>', 'description (custom controls only)')
         .option('--rename <text>', 'new name (custom controls only)')
         .option('--yes', 'apply without prompting')
         .option('--api-url <url>', 'override the API base URL for this command')
@@ -928,6 +963,7 @@ export const createProgram = (io = createDefaultIO()) => {
             ['justification', 'justification'],
             ['designRequirements', 'designRequirements'],
             ['notes', 'notes'],
+            ['description', 'description'],
             ['rename', 'name'],
         ]) {
             const value = readStringOption(options, flag);
@@ -1543,6 +1579,7 @@ export const createProgram = (io = createDefaultIO()) => {
             json: readBooleanOption(options, 'json'),
         });
     });
+    registerCapabilities(program, io);
     // A bare `ciphrix` shows the banner and help; commands never print the banner.
     program.action(() => {
         writeBlock(io.stdout, `${formatBanner(io.theme)}\n\n`);
@@ -1566,6 +1603,8 @@ export const main = async (argv = process.argv, io = createDefaultIO()) => {
         return 0;
     }
     catch (error) {
+        if (error instanceof RenderedCommandError)
+            return 1;
         if (error instanceof CommanderError) {
             return error.exitCode;
         }

package/dist/commands/asset.d.ts

@@ -6,12 +6,15 @@ export interface AssetCommonOptions {
     json?: boolean | undefined;
     credentialStore?: CredentialStore | undefined;
 }
-export declare const assetListCommand: ({ io, apiUrl, json, credentialStore, name, category, status, businessImpact, dataClassification, page, limit, }: AssetCommonOptions & {
+export declare const assetListCommand: ({ io, apiUrl, json, credentialStore, name, category, subCategory, status, businessImpact, dataClassification, source, technicalOwnerEmail, page, limit, }: AssetCommonOptions & {
     name?: string | undefined;
     category?: string | undefined;
+    subCategory?: string | undefined;
     status?: string | undefined;
     businessImpact?: string | undefined;
     dataClassification?: string | undefined;
+    source?: string | undefined;
+    technicalOwnerEmail?: string | undefined;
     page?: number | undefined;
     limit?: number | undefined;
 }) => Promise<void>;

package/dist/commands/asset.js

@@ -2,22 +2,29 @@ import { applyTool } from '../actions.js';
 import { writeLine, writeNextHint, writePageFooter, writeTable, clip } from '../io.js';
 import { asRecord, asText, callTool, errorMessage, resolveToolContext } from '../toolSurface.js';
 const text = (value, fallback = '-') => typeof value === 'string' ? value : typeof value === 'number' ? String(value) : fallback;
-export const assetListCommand = async ({ io, apiUrl, json = false, credentialStore, name, category, status, businessImpact, dataClassification, page, limit, }) => {
+export const assetListCommand = async ({ io, apiUrl, json = false, credentialStore, name, category, subCategory, status, businessImpact, dataClassification, source, technicalOwnerEmail, page, limit, }) => {
     const ctx = await resolveToolContext(apiUrl, credentialStore);
+    const csv = (value) => value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
     const input = {};
     if (name)
         input.name = name;
     if (category)
-        input.category = [category];
+        input.category = csv(category);
+    if (subCategory)
+        input.subCategory = csv(subCategory);
     if (status)
-        input.status = status
-            .split(',')
-            .map((value) => value.trim())
-            .filter(Boolean);
+        input.status = csv(status);
     if (businessImpact)
-        input.businessImpact = [businessImpact];
+        input.businessImpact = csv(businessImpact);
     if (dataClassification)
-        input.dataClassification = [dataClassification];
+        input.dataClassification = csv(dataClassification);
+    if (source)
+        input.source = csv(source);
+    if (technicalOwnerEmail)
+        input.technicalOwnerEmail = technicalOwnerEmail;
     if (page)
         input.page = page;
     if (limit)

package/dist/commands/capabilities.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { type CliIO } from '../io.js';
+import { type ToolContext } from '../toolSurface.js';
+export declare class RenderedCommandError extends Error {
+}
+export declare const registerCapabilities: (program: Command, io: CliIO, context?: (apiUrl?: string) => Promise<ToolContext>) => void;