@commercelayer/agent-cli 1.0.0-dev.2 → 1.0.0-dev.21

package/dist/engine.js

@@ -4,19 +4,47 @@
 // destructive verb, then the request. A plain noun needs no code here: its schema says
 // everything. Every answer is the API's envelope, { data, state, warnings, next }.
 import { parseCommand, parseFields, toFlag } from './argv.js';
-import { outWritten, raiseProblem, resolveOrg } from './config.js';
-import { confirm, terminal } from './confirm.js';
+import { forgetOutWritten, raiseProblem, resolveOrg } from './config.js';
+import { confirm, terminal, withYes } from './confirm.js';
 import { CliError, closest, fail, fixWith } from './errors.js';
 import { indexHelp, nounHelp, verbHelp } from './help.js';
 import { envelope, request } from './http.js';
 import { readInputs } from './inputs.js';
 import { hasLogin, loginToken } from './login.js';
 import { resourceRequest } from './resources.js';
+import { markDrift } from './project.js';
 import { describePlan, OUT_NOT_TRACKED, planSecret, removeRecordFiles, writeSecret } from './secrets.js';
 import { verbOf } from './schema.js';
-import { apiNouns, apiSchema } from './schemas.js';
+import { apiNouns, apiSchema, refreshSchemas, refusedBySchema } from './schemas.js';
 import { VERSION } from './version.js';
+/**
+ * One command. When it was read against a cached schema the API has since changed (a deploy), and
+ * the refusal is one that explains (refusedBySchema), it runs once more on fresh schemas. The API
+ * refused, so nothing happened; the second run asks again what the fresh schema asks, and never
+ * adds confirm=true on its own.
+ */
 export async function execute(argv, opts = {}) {
+    try {
+        return await executeOnce(argv, opts);
+    }
+    catch (e) {
+        if (!(e instanceof CliError) || !refusedBySchema(e.code) || !refusedBeforeEffect(e))
+            throw e;
+        refreshSchemas();
+        process.stderr.write(JSON.stringify({ retrying: { code: e.code, why: 'the schema changed on the API: read again' } }) + '\n');
+        return executeOnce(argv, opts);
+    }
+}
+/** A refusal the API answered (4xx), or a flag or verb the cached schema did not know: nothing was done. */
+function refusedBeforeEffect(e) {
+    const status = e.body.details?.status;
+    if (typeof status === 'number')
+        return status >= 400 && status < 500;
+    return e.code === 'unknown_field' || e.code === 'unknown_verb';
+}
+/** Verbs that only run in live mode. */
+const LIVE_ONLY = new Set(['events writes']);
+async function executeOnce(argv, opts) {
     const cmd = parseCommand(argv);
     const builtins = opts.builtins ?? {};
     if (cmd.globals.version && !cmd.noun)
@@ -28,7 +56,10 @@ export async function execute(argv, opts = {}) {
     const schema = builtins[cmd.noun]?.schema ?? (await apiSchema(cmd.noun, Object.keys(builtins)));
     if (cmd.globals.help && !cmd.verb && !builtins[cmd.noun]?.defaultVerb)
         return envelope(nounHelp(schema));
-    const verb = verbOf(schema, cmd.verb ?? builtins[cmd.noun]?.defaultVerb);
+    const ext = opts.extensions?.[schema.noun];
+    const found = verbOf(schema, cmd.verb ?? builtins[cmd.noun]?.defaultVerb);
+    const local = ext?.flags?.[found.name];
+    const verb = local ? { ...found, flags: { ...found.flags, ...local } } : found;
     if (cmd.globals.help)
         return envelope(verbHelp(schema, verb));
     // A verb the schema lists as refused: no request, no confirmation for something that cannot happen.
@@ -36,9 +67,11 @@ export async function execute(argv, opts = {}) {
         const by = verb.refused.by === 'commercelayer' ? 'Commerce Layer' : verb.refused.by;
         fail('not_supported', `c11r ${schema.noun} ${verb.name} is refused by ${by}: ${verb.description || 'it cannot be done through the API.'}`, { details: { refused_by: verb.refused.by }, next_step: { action: 'none' } });
     }
-    const ext = opts.extensions?.[schema.noun];
-    const positional = ext?.positional?.[verb.name];
-    const rest = positional && !verb.id && cmd.rest[0] !== undefined && !cmd.rest[0].startsWith('-') ? [`--${positional}`, ...cmd.rest] : cmd.rest;
+    // A bare value that is a flag's: the first for a verb with no id (sales-calls book <slot>), the
+    // second, after the id, for one with (shop order <store> <checkout>).
+    const positional = (builtins[schema.noun]?.positional ?? ext?.positional)?.[verb.name];
+    const bare = (i) => cmd.rest[i] !== undefined && !cmd.rest[i].startsWith('-');
+    const rest = !positional ? cmd.rest : !verb.id && bare(0) ? [`--${positional}`, ...cmd.rest] : verb.id && bare(0) && bare(1) ? [cmd.rest[0], `--${positional}`, ...cmd.rest.slice(1)] : cmd.rest;
     const parsed = parseFields(schema.noun, verb, rest);
     ext?.prepare?.(verb, parsed);
     // Files first, so a required document given with --file counts; a secret is typed only once
@@ -46,16 +79,41 @@ export async function execute(argv, opts = {}) {
     await readInputs(schema.noun, verb, parsed, null);
     check(schema, verb, parsed);
     await readInputs(schema.noun, verb, parsed, opts.prompter ?? terminal);
+    const unknown = unknownValues(verb, parsed.values);
     const line = ['c11r', ...argv.filter((a) => a !== '--yes' && a !== '-y')].map(quote).join(' ');
     const org = resolveOrg(cmd.globals.org);
     const login = hasLogin();
+    const live = cmd.globals.live;
+    // The command as typed: c11r status, not c11r status get, when the verb was left out.
+    const named = `c11r ${schema.noun}${cmd.verb ? ` ${verb.name}` : ''}`;
+    if (live && !verb.live) {
+        fail('state_required', `${named} does not run in live mode.`, { required_state: 'claimed', path: 'live', next_step: fixWith(line.replace(/\s--live\b/, '')) });
+    }
+    // A verb that only reads live data (events writes, the audit of live writes): without --live the
+    // API answers the login a bare 401, so the command says what it needs first.
+    if (!live && LIVE_ONLY.has(`${schema.noun} ${verb.name}`)) {
+        const org = cmd.globals.org ? '' : ' --org ORG_SLUG';
+        fail('missing_value', `${named} reads live data only: it needs --live and the organization, named with --org.`, { path: 'live', next_step: fixWith(`${line}${org} --live`) });
+    }
+    // Live mode acts on an organization named on the command, never the folder's link or the
+    // default, which are a sandbox's: --org, or C11R_ORG.
+    const liveOrg = live ? (cmd.globals.org ?? (process.env.C11R_ORG || null)) : null;
+    if (live && !liveOrg) {
+        // The folder's link is not taken in live mode; named, it is the value to pass when it is the one meant.
+        const linked = org.source === 'link' ? org.org : null;
+        fail('missing_value', `${named} --live acts on a claimed organization, named with --org.${linked ? ` This folder is linked to ${linked}: pass it with --org when it is the one meant.` : ''}`, { path: 'org', next_step: fixWith(`${line.replace(/\s--live\b/, '')} --org ${linked ?? 'ORG_SLUG'} --live`) });
+    }
     // The bearer, from the schema (contract section 23). An organization token for the organization
     // nouns, the login for the Provisioning ones; credentials take the login when there is one and
     // the organization token is not a sandbox's.
-    let bearer = verb.credential === 'login' ? 'login' : verb.credential === 'organization|login' ? (login && !org.token?.startsWith('sbx_') ? 'login' : 'organization') : verb.credential === 'none' ? 'none' : 'organization';
+    // In live mode, always the login, never an organization token: the API answers login_required
+    // to anything else, and to no token at all.
+    let bearer = live
+        ? 'login'
+        : verb.credential === 'login' ? 'login' : verb.credential === 'organization|login' ? (login && !org.token?.startsWith('sbx_') ? 'login' : 'organization') : verb.credential === 'none' ? 'none' : 'organization';
     // members and roles with an organization token and no login: the API says what is needed (a
     // claim for a sandbox, a login for a claimed organization). organizations and auth stop here.
-    if (bearer === 'login' && !login && org.token && schema.noun !== 'organizations' && schema.noun !== 'auth')
+    if (!live && bearer === 'login' && !login && org.token && schema.noun !== 'organizations' && schema.noun !== 'auth')
         bearer = 'organization';
     // A verb that needs an organization token: say which is missing before the API does.
     if (bearer === 'organization' && verb.state !== 'none' && !org.token) {
@@ -68,20 +126,37 @@ export async function execute(argv, opts = {}) {
     // The login names its organization with ?org=, from --org, C11R_ORG, .c11r.json or the default:
     // never a guess from the only token stored, which may be a sandbox the login does not reach.
     const loginOrg = org.source && org.source !== 'only_stored' ? org.org : null;
-    if (cmd.globals.live && !verb.live) {
-        fail('state_required', `c11r ${schema.noun} ${verb.name} does not run in live mode.`, { required_state: 'claimed', path: 'live', next_step: fixWith(line.replace(/\s--live\b/, '')) });
-    }
     let confirmed = false;
     const confirmFlags = verb.confirmIf.filter((k) => parsed.values[k] !== undefined && parsed.values[k] !== false);
-    if ((verb.destructive || confirmFlags.length) && !cmd.globals.dryRun) {
-        const what = `${verb.name} ${schema.noun}${parsed.id ? ` ${parsed.id}` : ''}${confirmFlags.length ? ` with ${confirmFlags.map(toFlag).join(' ')}` : ''}`;
-        await confirm(what.charAt(0).toUpperCase() + what.slice(1), line, { yes: cmd.globals.yes, prompter: opts.prompter });
+    // In live mode the API asks for the verbs it confirms, with a sentence naming the action, the
+    // amount and the mode ("Refunds EUR 1.00 on order N, in LIVE mode, real money."): the CLI sends
+    // without confirm=true and shows that 428 as it is, or asks it in a terminal. --yes sends
+    // confirm=true on every live write, payments capture included.
+    // So does a login verb (organizations disconnect), whose sentence names what stops answering.
+    const apiAsks = (live || verb.credential === 'login') && (verb.confirm || confirmFlags.length > 0);
+    if (apiAsks && cmd.globals.yes && !cmd.globals.dryRun)
+        confirmed = true;
+    if (live && cmd.globals.yes && verb.method !== 'GET')
+        confirmed = true;
+    if ((verb.destructive || verb.confirm || confirmFlags.length) && !cmd.globals.dryRun && !apiAsks) {
+        // The command itself names the action ("c11r markets delete eu"): no verb to inflect.
+        const sentence = `c11r ${schema.noun} ${verb.name}${parsed.id ? ` ${parsed.id}` : ''}${confirmFlags.length ? ` ${confirmFlags.map(toFlag).join(' ')}` : ''}`;
+        await confirm(sentence, line, { yes: cmd.globals.yes, prompter: opts.prompter });
         confirmed = true;
     }
+    // A live secret goes only to a file the human chose: never the default folder, never printed.
+    if (live && verb.secret && parsed.values.out === undefined) {
+        fail('missing_value', `${named} --live answers a live secret: it is written only to a file the human chooses, with --out.`, { path: 'out', next_step: fixWith(`${line} --out FILE`) });
+    }
     // Where a secret goes, checked before the request makes one.
-    const secretPlan = verb.secret ? planSecret({ org: org.org, verb: verb.name, id: parsed.id, values: parsed.values, yes: cmd.globals.yes }) : null;
-    const ctx = { live: cmd.globals.live, token: bearer === 'login' ? await loginToken() : org.token };
-    const orgQuery = bearer === 'login' && loginOrg && schema.noun !== 'organizations' && schema.noun !== 'auth' ? { org: loginOrg } : {};
+    const secretPlan = verb.secret ? planSecret({ org: org.org, noun: schema.noun, verb: verb.name, id: parsed.id, values: parsed.values, yes: cmd.globals.yes }) : null;
+    // Live without a login: the organization token this machine holds for the organization named,
+    // and no other (never C11R_TOKEN, whose organization is unknown). The API answers a sandbox's
+    // state_required with its claim step, a claimed one's login_required; a slug alone stays
+    // login_required, so no one learns which slugs exist.
+    const liveOwn = live && !login && org.org === liveOrg && (org.source === 'flag' || org.source === 'env') ? org.token : null;
+    const ctx = { live, token: live ? (login ? await loginToken() : liveOwn) : bearer === 'login' ? await loginToken() : org.token };
+    const orgQuery = liveOrg ? { org: liveOrg } : bearer === 'login' && loginOrg && schema.noun !== 'organizations' && schema.noun !== 'auth' ? { org: loginOrg } : {};
     const sendOnce = (req) => request({ ...req, query: { ...(req.query ?? {}), ...orgQuery }, dryRun: req.dryRun ?? cmd.globals.dryRun, confirm: confirmed || req.confirm }, ctx);
     const run = {
         globals: cmd.globals,
@@ -98,6 +173,16 @@ export async function execute(argv, opts = {}) {
                 return await sendOnce(req);
             }
             catch (e) {
+                // The API's own confirmation, in live: as it is with no terminal; asked with its words in one.
+                if (apiAsks && !confirmed && e instanceof CliError && e.code === 'confirmation_required') {
+                    const p = opts.prompter ?? terminal;
+                    // Without a command of the API's, the next step is this one with --yes, under confirm.
+                    if (!p.interactive)
+                        throw e.body.next_step?.command ? e : new CliError({ ...e.body, next_step: { action: 'confirm', command: withYes(line), url: null } }, e.kind, e.state);
+                    await confirm(e.body.message, line, { yes: false, prompter: p, sentence: e.body.message });
+                    confirmed = true;
+                    return sendOnce(req);
+                }
                 // A login token Commerce Layer no longer takes: mint a new one, once.
                 if (!(e instanceof CliError && e.code === 'login_required') || !login)
                     throw e;
@@ -107,29 +192,108 @@ export async function execute(argv, opts = {}) {
                     throw e;
                 ctx.token = await loginToken({ fresh: bearer === 'login' });
                 run.bearer = 'login';
-                if (loginOrg && schema.noun !== 'organizations')
+                if (!live && loginOrg && schema.noun !== 'organizations')
                     Object.assign(orgQuery, { org: loginOrg });
                 return sendOnce(req);
             }
         },
     };
-    const own = (await builtins[schema.noun]?.run?.(run)) ?? (await ext?.run?.(run));
-    const r = own ?? (await run.send(resourceRequest(schema.noun, verb, parsed.id, parsed.values)));
-    return filesGone(secretOf(r, run, secretPlan), run);
+    // A secret read from a file (provider or payment keys) is never printed, whatever the answer
+    // holds: a dry run or an error that echoes it shows [secret] in its place.
+    const secrets = secretValues(verb, parsed.values);
+    try {
+        const own = (await builtins[schema.noun]?.run?.(run)) ?? (await ext?.run?.(run));
+        const r = own ?? (await run.send(resourceRequest(schema.noun, verb, parsed.id, parsed.values)));
+        const out = drifted(filesGone(secretOf(r, run, secretPlan), run), run);
+        return scrub(unknown.length ? { ...out, warnings: [...unknown, ...out.warnings] } : out, secrets);
+    }
+    catch (e) {
+        if (e instanceof CliError && secrets.length)
+            throw new CliError(scrub(e.body, secrets), e.kind, scrub(e.state, secrets));
+        throw e;
+    }
+}
+/** The string values of the secret fields given, longest first. */
+function secretValues(verb, values) {
+    const out = [];
+    const walk = (v) => {
+        if (typeof v === 'string' && v.length >= 4)
+            out.push(v);
+        else if (v && typeof v === 'object')
+            for (const x of Object.values(v))
+                walk(x);
+    };
+    for (const spec of Object.values(verb.flags))
+        if (spec.input?.kind === 'secret')
+            walk(values[spec.input.target]);
+    return [...new Set(out)].sort((a, b) => b.length - a.length);
+}
+function scrub(v, secrets) {
+    if (!secrets.length || v === undefined)
+        return v;
+    let text = JSON.stringify(v);
+    if (text === undefined)
+        return v;
+    for (const s of secrets)
+        text = text.split(JSON.stringify(s).slice(1, -1)).join('[secret]');
+    return JSON.parse(text);
+}
+/**
+ * A value outside a flag's documented values (known: webhook topics): not enforced, so it is sent,
+ * with a warning and the closest documented ones.
+ */
+function unknownValues(verb, values) {
+    const out = [];
+    for (const [key, f] of Object.entries(verb.flags)) {
+        const v = values[key];
+        if (!f.known || v === undefined || v === null)
+            continue;
+        for (const x of (Array.isArray(v) ? v : [v]).filter((x) => typeof x === 'string' && x !== '')) {
+            if (f.known.includes(x))
+                continue;
+            const near = closest(x, f.known);
+            out.push({
+                code: 'unknown_value',
+                message: `${x} is not one of the documented values of ${toFlag(key)}${near.length ? ` (closest: ${near.join(', ')})` : ''}; it was sent anyway.`,
+                path: key,
+                ...(near.length ? { did_you_mean: near } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * A Configure write that went through, in a folder whose store.yml names this organization: the
+ * file is now behind it. Noted in .c11r/drift, with the warning config_drift.
+ */
+function drifted(r, run) {
+    if (run.globals.dryRun || !run.org.org || run.verb.method === 'GET')
+        return r;
+    if (run.schema.doc?.group !== 'configure')
+        return r;
+    const data = (r.data && typeof r.data === 'object' ? r.data : {});
+    const id = [run.parsed.id, data.code, data.name, data.id].find((k) => typeof k === 'string' && k !== '');
+    const warning = markDrift(run.org.org, run.globals.live ? 'live' : 'test', { noun: run.schema.noun, verb: run.verb.name, id: id ?? null });
+    return warning ? { ...r, warnings: [...r.warnings, warning] } : r;
 }
 /**
- * A delete of a record whose verbs answer secrets (credentials, webhooks): the files c11r wrote
- * for it go with it, listed in removed_files. out_files_not_tracked only when it may apply:
- * nothing found here, or a secret of this organization written with --out on this machine.
+ * A delete on a noun that answers secrets: the files c11r wrote for that record in the secrets
+ * folder go with it, listed in removed_files. out_files_not_tracked only when that record's secret
+ * was written with --out on this machine: that file stays where it was written.
  */
 function filesGone(r, run) {
     if (run.verb.name !== 'delete' || run.globals.dryRun || !run.org.org)
         return r;
     if (!Object.values(run.schema.verbs).some((v) => v.secret))
         return r;
+    // In live mode the secret went to a file the human chose, which is theirs to delete; the
+    // secrets folder holds the test mode's files of the same organization, which stay.
+    if (run.globals.live)
+        return { ...r, warnings: [...r.warnings, OUT_NOT_TRACKED] };
     const data = (r.data && typeof r.data === 'object' ? r.data : {});
-    const removed = removeRecordFiles(run.org.org, run.schema.noun, [run.parsed.id, data.id, data.name, data.code]);
-    const warn = removed.length === 0 || outWritten(run.org.org);
+    const keys = [run.parsed.id, data.id, data.name, data.code].filter((k) => typeof k === 'string' && k !== '');
+    const removed = removeRecordFiles(run.org.org, run.schema.noun, keys);
+    const warn = forgetOutWritten(run.org.org, { noun: run.schema.noun, keys });
     return { ...r, data: { ...data, removed_files: removed }, warnings: [...r.warnings, ...(warn ? [OUT_NOT_TRACKED] : [])] };
 }
 /** A secret in the answer goes to its file; a dry run says where it would go. */
@@ -138,7 +302,7 @@ function secretOf(r, run, plan) {
     const secret = data && typeof data === 'object' ? data.secret : undefined;
     if (secret && typeof secret === 'object' && 'value' in secret) {
         // A verb the schema did not mark: still never printed.
-        const p = plan ?? planSecret({ org: run.org.org, verb: run.verb.name, id: run.parsed.id, values: run.parsed.values, yes: true });
+        const p = plan ?? planSecret({ org: run.org.org, noun: run.schema.noun, verb: run.verb.name, id: run.parsed.id, values: run.parsed.values, yes: true });
         return writeSecret(r, p, { org: run.org.org, noun: run.schema.noun, verb: run.verb.name, id: run.parsed.id });
     }
     if (plan && run.globals.dryRun)

package/dist/errors.js

@@ -62,6 +62,12 @@ const KIND = {
     no_credentials: 'auth',
     forbidden: 'rejected',
     claim_not_found: 'not_found',
+    // A store spoken to over UCP (c11r shop).
+    store_unavailable: 'unavailable',
+    store_refused: 'rejected',
+    payment_handler_unsupported: 'rejected',
+    // The site that publishes the skills (c11r skills sync).
+    site_unavailable: 'unavailable',
 };
 /** For an API error whose code the CLI does not know: from the HTTP status. */
 export function kindOfStatus(status) {

package/dist/help.js

@@ -3,13 +3,14 @@
 // reads it and offers to do the work.
 import { toFlag } from './argv.js';
 import { EXIT } from './errors.js';
+import { clearable } from './schema.js';
 export const USAGE = 'c11r <noun> <verb> [id] [--field value ...]';
 export const GLOBAL_FLAG_HELP = {
     '--json': 'Output as JSON. The default, and the only format: one object on stdout, { data, state, warnings, next } or { error, state }.',
     '--dry-run': 'On a write, the API checks everything and says what would change, and changes nothing. Reads ignore it.',
     '--yes': 'Confirms a destructive verb in advance. Without it a destructive verb asks in the terminal, or, with no terminal, stops with confirmation_required.',
     '--org <slug>': 'The organization to act on, by its stored token. Without it: C11R_ORG, then the folder\'s .c11r.json, then the only stored organization.',
-    '--live': 'Acts on live data, on a claimed organization. Without it every command works in test mode.',
+    '--live': 'Acts on live data, on a claimed organization named with --org, with the human\'s login. Without it every command works in test mode.',
     '--help': 'Describes the noun or verb it follows, from its schema.',
 };
 export const EXIT_CODE_HELP = {
@@ -21,7 +22,7 @@ export const EXIT_CODE_HELP = {
     [EXIT.not_found]: 'no such resource',
     [EXIT.rejected]: 'the API or Commerce Layer refused the request as it is',
     [EXIT.unavailable]: 'the API did not answer, is busy, or answered with an error of its own',
-    [EXIT.auth]: 'a wrong or revoked token, or no token stored for the organization named',
+    [EXIT.auth]: 'a wrong or revoked token, no token stored for the organization named, or no login (login_required)',
 };
 export function indexHelp(builtins, api) {
     return {
@@ -29,7 +30,7 @@ export function indexHelp(builtins, api) {
         description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
         nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
         standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
-        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A dotted flag sets part of an object (--customer.email). Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). Any other array takes the flag repeated or a JSON array, and the same rule holds: enums, numbers and dates also separated by commas, a name or text one value per flag (--payment-settings "Invoice, 60 days"); an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
         global_flags: GLOBAL_FLAG_HELP,
         exit_codes: EXIT_CODE_HELP,
         more: 'c11r <noun> --help describes a noun and its verbs; c11r <noun> <verb> --help a verb and its flags; c11r schema <noun> returns the full schema.',
@@ -53,19 +54,48 @@ export function verbHelp(s, v) {
         state: v.state,
         ...(v.plan ? { plan: v.plan } : {}),
         ...(v.refused ? { served: false, refused_by: v.refused.by } : {}),
-        ...(v.destructive ? { destructive: true, confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
+        ...(v.destructive ? { destructive: true } : {}),
+        ...(v.confirm ? { confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
         ...(v.loopable ? { loopable: 'A loop policy may allow this verb.' } : {}),
         ...(v.live ? {} : { live: 'Not in live mode.' }),
-        flags: Object.entries(v.flags).map(([key, f]) => flagHelp(key, f)),
+        flags: Object.entries(v.flags).map(([key, f]) => flagHelp(key, f, s.noun)),
     };
 }
-function flagHelp(key, f) {
+/** Up to this many documented values are listed in help; past it, help says where they are. */
+const KNOWN_IN_FULL = 20;
+const CAPS = (name) => name.toUpperCase().replace(/-/g, '_');
+/** How an array flag takes several values, built from its items and, for objects, their parts. */
+function repeatOf(key, f) {
+    if (f.repeat)
+        return f.repeat;
+    const flag = toFlag(key);
+    const item = f.items ?? 'string';
+    if (item === 'object') {
+        const parts = Object.entries(f.properties ?? {});
+        const required = parts.filter(([, p]) => p.required);
+        const shown = required.length ? required : parts;
+        const optional = required.length ? parts.filter(([, p]) => !p.required).map(([n]) => n) : [];
+        const pairs = shown.length ? shown.map(([n]) => `${n}=${CAPS(n)}`).join(',') : 'KEY=VALUE,KEY=VALUE';
+        return `${flag} ${pairs}, the flag once per item, or one JSON array of objects.${optional.length ? ` Optional parts: ${optional.join(', ')}.` : ''}`;
+    }
+    if (item === 'string' || item === 'ref') {
+        const v = item === 'ref' ? 'ID' : 'VALUE';
+        return `${flag} ${v} ${flag} ${v}, one value per flag (a comma is part of the value), or one JSON array.`;
+    }
+    const v = item === 'integer' || item === 'number' || item === 'money' ? 'N' : item === 'date' || item === 'datetime' ? 'DATE' : 'VALUE';
+    return `${flag} ${v},${v}, or the flag repeated, or one JSON array.`;
+}
+function flagHelp(key, f, noun) {
     return {
         flag: toFlag(key),
         type: f.type === 'array' ? `array of ${f.items ?? 'string'}` : f.type === 'ref' ? `${f.noun ?? 'resource'} id` : f.type === 'money' ? 'amount in major units' : f.type,
+        ...(f.type === 'array' ? { repeat: repeatOf(key, f) } : {}),
         ...(f.required || (f.input?.kind === 'secret' && f.input.required) ? { required: true } : {}),
         ...(f.input ? { reads: f.input.kind === 'secret' ? `${f.input.target}, a secret: never a flag value, never printed` : `${f.input.target}, a JSON document` } : {}),
         ...(f.values ? { values: f.values } : {}),
+        ...(f.bare ? { alone: `${toFlag(key)} with no value sends true` } : {}),
+        ...(f.known ? { known: f.known.length <= KNOWN_IN_FULL ? f.known : `one of ${f.known.length} documented values: c11r schema ${noun}` } : {}),
+        ...(clearable(f) ? { clear: 'null, or an empty value, takes it off' } : {}),
         ...(f.filter ? { filter: f.filter.op } : {}),
         ...(f.description ? { description: f.description } : {}),
     };

package/dist/http.js

@@ -33,6 +33,13 @@ export function urlOf(req, ctx) {
     const qs = q.toString();
     return `${apiUrl()}${req.path}${qs ? `?${qs}` : ''}`;
 }
+/** The header with the hash of the schemas the API serves: it changes with a deploy that changes them. */
+export const SCHEMA_HEADER = 'c11r-schema';
+let schemaWatcher = null;
+/** Called with the header's value on every answer that has it (the schema cache listens). */
+export function watchSchemaHeader(fn) {
+    schemaWatcher = fn;
+}
 /** Sends the request: the envelope, or the API's error as a CliError. */
 export async function request(req, ctx) {
     for (let attempt = 1;; attempt++) {
@@ -76,6 +83,9 @@ async function once(req, ctx) {
             next_step: req.method === 'GET' ? { action: 'retry_later' } : { action: 'none' },
         });
     }
+    const version = res.headers.get(SCHEMA_HEADER);
+    if (version && schemaWatcher)
+        schemaWatcher(version);
     const text = await res.text();
     let data;
     try {

package/dist/inputs.js

@@ -4,6 +4,8 @@
 // KEY=value lines, from a plain file only its owner can read; or, in a terminal, typed without
 // echo. Never from a flag value or --data, never printed: an error names the file, not the value.
 // A document field (file_input: price rules, rule filters) is also read from a JSON file, --file.
+// Where the verb takes --format csv (imports), the file is sent as CSV text with --format csv, or
+// when it ends in .csv and no format is given; JSON otherwise.
 import fs from 'node:fs';
 import { toFlag } from './argv.js';
 import { fail } from './errors.js';
@@ -29,7 +31,12 @@ export async function readInputs(noun, verb, parsed, prompter) {
                 continue;
             if (parsed.values[input.target] !== undefined)
                 fail('invalid_value', `${cmd} takes ${input.target} from ${toFlag(input.target)} or from ${toFlag(key)}, not both.`, { path: key });
-            parsed.values[input.target] = documentOf(file, key, spec);
+            if (isCsv(verb, parsed, file)) {
+                parsed.values.format ??= 'csv';
+                parsed.values[input.target] = csvOf(file, key);
+            }
+            else
+                parsed.values[input.target] = documentOf(file, key, spec);
             continue;
         }
         if (file !== undefined) {
@@ -51,6 +58,19 @@ export async function readInputs(noun, verb, parsed, prompter) {
         });
     }
 }
+const isCsv = (verb, parsed, file) => Boolean(verb.flags.format?.values?.includes('csv')) && (parsed.values.format === 'csv' || (parsed.values.format === undefined && /\.csv$/i.test(file)));
+function csvOf(file, key) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        fail('invalid_value', `${toFlag(key)} ${file}: ${e.code === 'ENOENT' ? 'no such file' : e.message}.`, { path: key });
+    }
+    if (!text.trim())
+        fail('invalid_value', `${file} is empty: a CSV file starts with its header row.`, { path: key });
+    return text;
+}
 function documentOf(file, key, spec) {
     let text;
     try {