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

package/README.md

@@ -14,8 +14,11 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - A plain noun has no code in the CLI. Its fields, filters and verbs come from the API's schema, and `c11r schema <noun>` returns that schema.
 - Flags are the schema's fields, in kebab or snake case: `--price-list` and `--price_list` are the same.
 - On `list`, `--<field> <value>` filters by equality and `--<field>.<op> <value>` by another operator: `--placed-at.gte 2026-11-01`, `--status.in placed,approved`. `--waiting` lists what needs a decision now.
-- A dotted flag sets part of an object: `--customer.email ada@example.com`. An array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
+- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter 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 (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
 - Amounts are in major units: `--amount 12.50`.
+- A secret field the schema marks `secret_input` (provider credentials) has no flag of its own: `--credentials-file <file>` reads it, as JSON or `KEY=value` lines, from a plain file only its owner can read (mode 600). Without the file, a terminal asks for it without echo; with neither, the command stops with `secret_required`. It is refused as a flag value or in `--data`, and never printed.
+- A document field the schema marks `file_input` (price rules, rule filters) also reads from a JSON file: `--file <file>`, or `--<field>-file` when a verb has more than one.
+- A verb whose schema lists `id_alternative` takes the id or those flags in its place: `c11r prices get pr_1`, or `c11r prices get --sku BEANS-1KG --price-list eur`. Both at once, or half the flags, stop before sending.
 
 ## Built-in nouns
 
@@ -47,7 +50,7 @@ Never from a flag or the environment. c11r exchanges the pair for a two hour tok
 
 `organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
 
-`credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. `credentials delete` removes the files c11r wrote for that credential in `~/.config/c11r/secrets/<org>/` (its secret and its tokens) and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so, when a secret of that organization was written with `--out` on this machine, or when a delete found nothing to remove. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
+`credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so, when a secret of that organization was written with `--out` on this machine, or when a delete found nothing to remove. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
 
 ## Global flags
 
@@ -66,7 +69,7 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 
 `--org`, then `C11R_ORG`, then `.c11r.json` in the project folder (found by walking up, like `.git`), then the default set by `auth switch --global`, then the stored organization when exactly one is stored (never for a login noun's `?org=`). With several stored and nothing naming one, the command stops with `org_required` and lists them.
 
-- Tokens are only in `~/.config/c11r/credentials.json` (or under `XDG_CONFIG_HOME`), mode 600. The CLI never prints one, only its hint.
+- Tokens are only in `~/.config/c11r/credentials.json` (or under `XDG_CONFIG_HOME`), mode 600. The CLI never prints one, only its hint. Each token records the host that issued it: organization and cancel tokens the API base, the login the auth endpoint. One is used, listed and forgotten only while that host is the one in effect (`C11R_API_URL`, `C11R_AUTH_URL`), so a token never goes to another host. An entry that records no host is not used, and goes at the next write.
 - `.c11r.json` holds only `{ "org": "<slug>" }`: no secret, safe to commit. `sandbox create`, `organizations create` and `auth switch` write it, and `organizations connect` when the folder has no link; `reset` follows the new slug; `destroy` removes it when it names the destroyed organization.
 - The project folder is the one with `.c11r.json`, else the nearest with `store.yml` or `loops.yml`, else the current one. `loops.yml` goes there.
 

package/dist/argv.js

@@ -65,12 +65,18 @@ export function parseFields(noun, verb, rest) {
         const [flag, inline] = splitInline(a);
         const key = toKey(flag);
         if (key === 'data') {
-            Object.assign(values, readData(inline ?? rest[++i]));
+            const data = readData(inline ?? rest[++i]);
+            for (const k of Object.keys(data))
+                if (verb.flags[`${k}_file`]?.input?.kind === 'secret')
+                    secretAsValue(cmd, k);
+            Object.assign(values, data);
             continue;
         }
         // A key of its own (a filter operator: created_at.gte), else part of an object (checkout.url).
         const [top, ...sub] = verb.flags[key] ? [key] : key.split('.');
         const spec = verb.flags[top];
+        if (!spec && verb.flags[`${top}_file`]?.input?.kind === 'secret')
+            secretAsValue(cmd, top);
         if (!spec) {
             fail('unknown_field', `${cmd} has no flag ${toFlag(key)}.`, {
                 path: key,
@@ -98,7 +104,7 @@ export function parseFields(noun, verb, rest) {
             for (const k of sub.slice(0, -1))
                 target = (target[k] ??= {});
             const part = sub.join('.');
-            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, { type: spec.properties[part] }, raw) : raw;
+            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, spec.properties[part], raw) : raw;
             continue;
         }
         const value = coerce(key, spec, raw);
@@ -106,9 +112,20 @@ export function parseFields(noun, verb, rest) {
     }
     return { id, values };
 }
+/** A secret given as a value: refused before it goes anywhere, and the message does not repeat it. */
+function secretAsValue(cmd, key) {
+    fail('invalid_value', `${cmd} takes ${key} only from a file, ${toFlag(`${key}_file`)} <file> (mode 600), or typed in a terminal: never as a flag value or in --data, where it would stay in the shell history. It was not sent.`, {
+        path: key,
+        next_step: { action: 'human_step', command: null, url: null },
+    });
+}
 /** A value as its flag's type says, or invalid_value with the reason. */
 export function coerce(key, spec, raw) {
     const invalid = (why) => fail('invalid_value', `${toFlag(key)} ${JSON.stringify(raw)} ${why}.`, { path: key, ...(spec.values ? { details: { values: spec.values } } : {}) });
+    // The schema's fault, not the command's: said so before any value is checked against nothing.
+    if ((spec.type === 'enum' || (spec.type === 'array' && spec.items === 'enum')) && !spec.values?.length) {
+        fail('invalid_response', `The API's schema gives ${toFlag(key)} as an enum with no values, so c11r cannot check ${JSON.stringify(raw)}. It was not sent.`, { path: key, next_step: { action: 'none' } });
+    }
     switch (spec.type) {
         case 'string':
         case 'ref':
@@ -143,7 +160,7 @@ export function coerce(key, spec, raw) {
             const v = raw.trim().startsWith('{') ? json(raw, invalid) : pairs(key, raw, spec.properties ?? {}, invalid);
             if (!v || typeof v !== 'object' || Array.isArray(v))
                 invalid('is not a JSON object');
-            return v;
+            return enumParts(key, spec.properties, v);
         }
         case 'array': {
             const item = spec.items ?? 'string';
@@ -151,11 +168,15 @@ export function coerce(key, spec, raw) {
                 const list = json(raw, invalid);
                 if (!Array.isArray(list))
                     invalid('is not a list');
-                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : x));
+                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : item === 'object' ? enumParts(key, spec.properties, x) : x));
             }
             // One object per flag (--items sku=A,quantity=2, repeated), or scalars separated by commas.
             if (item === 'object')
                 return [coerce(key, { type: 'object', properties: spec.properties }, raw)];
+            // An in filter on names or text takes the value whole: a name may have a comma ("UK VAT, manual").
+            // Several are the flag repeated, or a JSON array. Enums, numbers and dates still split on commas.
+            if (spec.filter?.op === 'in' && (item === 'string' || item === 'ref'))
+                return [raw];
             return raw
                 .split(',')
                 .map((s) => s.trim())
@@ -164,6 +185,17 @@ export function coerce(key, spec, raw) {
         }
     }
 }
+/** In JSON too, an enum part of an object is one of its values. */
+function enumParts(key, props, v) {
+    if (!v || typeof v !== 'object')
+        return v;
+    for (const [name, p] of Object.entries(props ?? {})) {
+        const part = v[name];
+        if (p.type === 'enum' && typeof part === 'string')
+            coerce(`${key}.${name}`, p, part);
+    }
+    return v;
+}
 function json(raw, invalid) {
     try {
         return JSON.parse(raw);
@@ -184,7 +216,7 @@ function pairs(key, raw, props, invalid) {
             invalid('is not JSON nor key=value pairs separated by commas');
         const name = part.slice(0, eq).trim();
         const value = part.slice(eq + 1).trim();
-        out[name] = props[name] ? coerce(`${key}.${name}`, { type: props[name] }, value) : value;
+        out[name] = props[name] ? coerce(`${key}.${name}`, props[name], value) : value;
     }
     return out;
 }

package/dist/builtins/auth.js

@@ -96,7 +96,7 @@ async function login(run) {
     const minted = await mint(clientId, secret);
     const who = await request({ method: 'GET', path: '/auth', query: { limit: '100' } }, { live: false, token: minted.token });
     const orgs = who.data?.organizations;
-    const items = Array.isArray(orgs) ? orgs : Array.isArray(orgs?.items) ? orgs.items : [];
+    const items = Array.isArray(orgs?.items) ? orgs.items : [];
     const previous = storedLogin();
     if (!run.globals.dryRun) {
         storeLogin({
@@ -146,7 +146,7 @@ async function switchOrg(run) {
     if (!tokens[slug] && !reached.includes(slug) && storedLogin()) {
         // The list may be older than the organization: read it again.
         const who = await request({ method: 'GET', path: '/auth', query: { limit: '100' } }, { live: false, token: await loginToken() });
-        const items = who.data?.organizations?.items ?? who.data?.organizations ?? [];
+        const items = who.data?.organizations?.items ?? [];
         reached = items.map((o) => o.slug);
         const l = storedLogin();
         if (l)

package/dist/builtins/extensions.js

@@ -8,12 +8,11 @@
 // sales-calls book answers a cancel token once (section 20): stored the same way, by booking id,
 // and sent by sales-calls cancel <booking> without the agent ever holding it.
 import crypto from 'node:crypto';
-import { credentialsFile, hintOf, outWritten, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
+import { credentialsFile, hintOf, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
 import { confirm, terminal } from '../confirm.js';
 import { fail } from '../errors.js';
 import { apiUrl } from '../http.js';
 import { resourceRequest } from '../resources.js';
-import { OUT_NOT_TRACKED, removeCredentialFiles } from '../secrets.js';
 const NAME_MAX = 25;
 export const organizations = {
     async run(run) {
@@ -105,19 +104,4 @@ export const salesCalls = {
         return undefined;
     },
 };
-export const credentials = {
-    async run(run) {
-        if (run.verb.name !== 'delete')
-            return undefined;
-        const r = await run.send(resourceRequest('credentials', run.verb, run.parsed.id, run.parsed.values));
-        if (run.globals.dryRun || !run.org.org)
-            return r;
-        // The secret and token files c11r wrote for it go with it.
-        const id = String(r.data?.id ?? run.parsed.id);
-        const removed = removeCredentialFiles(run.org.org, id);
-        // The warning only when it may apply: nothing found here, or a file written with --out for this organization.
-        const warn = removed.length === 0 || outWritten(run.org.org);
-        return { ...r, data: { ...(r.data ?? {}), removed_files: removed }, warnings: [...r.warnings, ...(warn ? [OUT_NOT_TRACKED] : [])] };
-    },
-};
-export const extensions = { organizations, 'sales-calls': salesCalls, credentials };
+export const extensions = { organizations, 'sales-calls': salesCalls };

package/dist/config.js

@@ -10,10 +10,16 @@
 // The organization: --org, then C11R_ORG, then .c11r.json, then the stored one when exactly one
 // is stored. With several stored and nothing naming one, the command stops and names them.
 // C11R_TOKEN, for CI, is used as is, whatever is stored.
+//
+// Every stored token records the host that issued it: an organization token and a cancel token
+// the API base (api_url), the login the auth endpoint (auth_url). An entry is used, listed and
+// forgotten only while that base is the one in effect, so a token never goes to a host it was not
+// issued by. An entry that records no host is not used, and goes at the next write.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fail, fixWith } from './errors.js';
+import { apiUrl } from './http.js';
 export const LINK_FILE = '.c11r.json';
 export function credentialsFile() {
     const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
@@ -32,6 +38,12 @@ function readCredentials() {
 }
 function writeCredentials(c) {
     const file = credentialsFile();
+    // An entry that records no issuing host is never used: it is not kept either.
+    c.orgs = Object.fromEntries(Object.entries(c.orgs).filter(([, o]) => o?.api_url));
+    if (c.login && !c.login.auth_url)
+        delete c.login;
+    if (c.bookings)
+        c.bookings = Object.fromEntries(Object.entries(c.bookings).filter(([, b]) => b?.api_url));
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     // Written aside then renamed, so a crash never leaves half a file; 600 from the start.
     const tmp = `${file}.${process.pid}.tmp`;
@@ -39,19 +51,26 @@ function writeCredentials(c) {
     fs.chmodSync(tmp, 0o600);
     fs.renameSync(tmp, file);
 }
+export const DEFAULT_AUTH_URL = 'https://auth.commercelayer.io/oauth/token';
+export const authUrl = () => process.env.C11R_AUTH_URL || DEFAULT_AUTH_URL;
+const norm = (u) => u.replace(/\/+$/, '');
+/** True when an entry was issued by the API base in effect; one that records none never is. */
+const fromApi = (e) => !!e?.api_url && norm(e.api_url) === norm(apiUrl());
+const fromAuth = (e) => !!e?.auth_url && norm(e.auth_url) === norm(authUrl());
+/** The organization tokens issued by the API in effect. */
 export function storedOrgs() {
-    return readCredentials().orgs;
+    return Object.fromEntries(Object.entries(readCredentials().orgs).filter(([, o]) => fromApi(o)));
 }
 export function storeOrg(slug, org) {
     const c = readCredentials();
-    c.orgs[slug] = org;
+    c.orgs[slug] = { ...org, api_url: apiUrl() };
     writeCredentials(c);
 }
 /** After a reset: the same token, a new organization. */
 export function renameOrg(from, to, patch = {}) {
     const c = readCredentials();
     const entry = c.orgs[from];
-    if (!entry)
+    if (!fromApi(entry))
         return;
     delete c.orgs[from];
     c.orgs[to] = { ...entry, ...patch };
@@ -59,20 +78,25 @@ export function renameOrg(from, to, patch = {}) {
 }
 export function forgetOrg(slug) {
     const c = readCredentials();
-    if (!c.orgs[slug])
+    if (!fromApi(c.orgs[slug]))
         return;
     delete c.orgs[slug];
     writeCredentials(c);
 }
+/** The login minted by the auth endpoint in effect. */
 export function storedLogin() {
-    return readCredentials().login ?? null;
+    const l = readCredentials().login;
+    return l && fromAuth(l) ? l : null;
 }
+/** Stores the login for the auth endpoint in effect; null forgets it, only if it is that one's. */
 export function storeLogin(login) {
     const c = readCredentials();
     if (login)
-        c.login = login;
-    else
+        c.login = { ...login, auth_url: authUrl() };
+    else if (fromAuth(c.login))
         delete c.login;
+    else
+        return;
     writeCredentials(c);
 }
 export function defaultOrg() {
@@ -102,15 +126,18 @@ export function markOutWritten(org, written) {
     writeCredentials(c);
 }
 export function storedBooking(id) {
-    return readCredentials().bookings?.[id] ?? null;
+    const b = readCredentials().bookings?.[id];
+    return b && fromApi(b) ? b : null;
 }
 export function storeBooking(id, booking) {
     const c = readCredentials();
     const all = { ...(c.bookings ?? {}) };
     if (booking)
-        all[id] = booking;
-    else
+        all[id] = { ...booking, api_url: apiUrl() };
+    else if (fromApi(all[id]))
         delete all[id];
+    else
+        return;
     c.bookings = all;
     writeCredentials(c);
 }

package/dist/engine.js

@@ -4,14 +4,15 @@
 // 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 { raiseProblem, resolveOrg } from './config.js';
-import { confirm } from './confirm.js';
+import { outWritten, raiseProblem, resolveOrg } from './config.js';
+import { confirm, terminal } 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 { describePlan, planSecret, writeSecret } from './secrets.js';
+import { describePlan, OUT_NOT_TRACKED, planSecret, removeRecordFiles, writeSecret } from './secrets.js';
 import { verbOf } from './schema.js';
 import { apiNouns, apiSchema } from './schemas.js';
 import { VERSION } from './version.js';
@@ -40,7 +41,11 @@ export async function execute(argv, opts = {}) {
     const rest = positional && !verb.id && cmd.rest[0] !== undefined && !cmd.rest[0].startsWith('-') ? [`--${positional}`, ...cmd.rest] : 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
+    // the command is otherwise complete.
+    await readInputs(schema.noun, verb, parsed, null);
     check(schema, verb, parsed);
+    await readInputs(schema.noun, verb, parsed, opts.prompter ?? terminal);
     const line = ['c11r', ...argv.filter((a) => a !== '--yes' && a !== '-y')].map(quote).join(' ');
     const org = resolveOrg(cmd.globals.org);
     const login = hasLogin();
@@ -110,7 +115,22 @@ export async function execute(argv, opts = {}) {
     };
     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 secretOf(r, run, secretPlan);
+    return filesGone(secretOf(r, run, secretPlan), run);
+}
+/**
+ * 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.
+ */
+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;
+    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);
+    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. */
 function secretOf(r, run, plan) {
@@ -119,7 +139,7 @@ function secretOf(r, run, plan) {
     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 });
-        return writeSecret(r, p, { org: run.org.org, verb: run.verb.name, id: run.parsed.id });
+        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)
         return { ...r, data: { ...(data && typeof data === 'object' ? data : { result: data }), secret_file: describePlan(plan) } };
@@ -128,13 +148,25 @@ function secretOf(r, run, plan) {
 /** What the command needs before anything is sent: the id, the required flags, known --data keys. */
 function check(schema, verb, parsed) {
     const cmd = `c11r ${schema.noun} ${verb.name}`;
-    if (verb.id && parsed.id === undefined) {
+    const alt = verb.idAlternative;
+    const altGiven = alt.filter((k) => parsed.values[k] !== undefined);
+    if (alt.length && parsed.id !== undefined && altGiven.length) {
+        fail('invalid_value', `${cmd} takes the id or ${alt.map(toFlag).join(' with ')}, not both.`, { path: altGiven[0], next_step: fixWith(`${cmd} --help`) });
+    }
+    if (verb.id && parsed.id === undefined && altGiven.length < Math.max(alt.length, 1)) {
         const accepts = schema.id?.accepts.length ? ` (or its ${schema.id.accepts.filter((a) => a !== 'id').join(' or ')})` : '';
-        fail('missing_id', `${cmd} needs the id${accepts} of one of the ${schema.noun}.`, { path: 'id', next_step: fixWith(`c11r ${schema.noun} list`) });
+        const instead = alt.length ? `, or ${alt.map(toFlag).join(' with ')}` : '';
+        const missing = alt.filter((k) => parsed.values[k] === undefined);
+        fail('missing_id', `${cmd} needs the id${accepts} of one of the ${schema.noun}${instead}.`, {
+            path: altGiven.length ? missing[0] : 'id',
+            ...(alt.length ? { details: { id_alternative: alt.map(toFlag) } } : {}),
+            next_step: fixWith(`c11r ${schema.noun} list`),
+        });
     }
     const keys = Object.keys(verb.flags);
+    const fromFiles = new Set(Object.values(verb.flags).flatMap((f) => (f.input ? [f.input.target] : [])));
     for (const key of Object.keys(parsed.values)) {
-        if (!verb.flags[key])
+        if (!verb.flags[key] && !fromFiles.has(key))
             fail('unknown_field', `${cmd} has no field ${key}.`, { path: key, did_you_mean: closest(key, keys), details: { flags: keys.map(toFlag) } });
     }
     const missing = Object.entries(verb.flags)

package/dist/help.js

@@ -29,7 +29,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 values separated by commas). A dotted flag sets part of an object (--customer.email). An 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 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.',
         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.',
@@ -63,16 +63,19 @@ function flagHelp(key, f) {
     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.required ? { required: true } : {}),
+        ...(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.filter ? { filter: f.filter.op } : {}),
         ...(f.description ? { description: f.description } : {}),
     };
 }
 export function usageOf(noun, v) {
+    const needed = (f) => f.required || (f.input?.kind === 'secret' && f.input.required);
     const required = Object.entries(v.flags)
-        .filter(([, f]) => f.required)
-        .map(([k, f]) => `${toFlag(k)} <${f.type === 'enum' ? f.values?.join('|') : f.type}>`);
-    const optional = Object.values(v.flags).some((f) => !f.required);
-    return [`c11r ${noun} ${v.name}`, v.id ? '<id>' : '', ...required, optional ? '[--field value ...]' : ''].filter(Boolean).join(' ');
+        .filter(([, f]) => needed(f))
+        .map(([k, f]) => `${toFlag(k)} <${f.input ? 'file' : f.type === 'enum' && f.values?.length ? f.values.join('|') : f.type}>`);
+    const optional = Object.entries(v.flags).some(([k, f]) => !needed(f) && !v.idAlternative.includes(k));
+    const id = v.id ? (v.idAlternative.length ? `<id | ${v.idAlternative.map((k) => `${toFlag(k)} <${v.flags[k].type}>`).join(' ')}>` : '<id>') : '';
+    return [`c11r ${noun} ${v.name}`, id, ...required, optional ? '[--field value ...]' : ''].filter(Boolean).join(' ');
 }

package/dist/inputs.js

@@ -0,0 +1,112 @@
+// Values read from files before anything is sent (contract section 28.6 and 39).
+//
+// A secret field (secret_input: provider credentials) is taken only from --<name>-file, as JSON or
+// 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.
+import fs from 'node:fs';
+import { toFlag } from './argv.js';
+import { fail } from './errors.js';
+import { readPrivateFile } from './login.js';
+/** The flag a secret field is read from, if the key is one. */
+export function secretFileFlag(verb, key) {
+    const k = `${key}_file`;
+    return verb.flags[k]?.input?.kind === 'secret' ? k : null;
+}
+/** Reads the files given; with a prompter, also asks for a required secret not given (null: files only). */
+export async function readInputs(noun, verb, parsed, prompter) {
+    const cmd = `c11r ${noun} ${verb.name}`;
+    for (const [key, spec] of Object.entries(verb.flags)) {
+        const input = spec.input;
+        if (!input)
+            continue;
+        const file = parsed.values[key];
+        // The second pass only asks for a secret: the files were read in the first.
+        if (prompter !== null && (input.kind === 'document' || parsed.values[input.target] !== undefined))
+            continue;
+        if (input.kind === 'document') {
+            if (file === undefined)
+                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);
+            continue;
+        }
+        if (file !== undefined) {
+            parsed.values[input.target] = secretOf(readPrivateFile(file, key), file, key, input.target_type);
+            continue;
+        }
+        if (!input.required || prompter === null)
+            continue;
+        if (prompter.interactive && prompter.askSecret) {
+            const typed = (await prompter.askSecret(`${input.target} as JSON, or KEY=value pairs separated by spaces (not shown): `)).trim();
+            if (!typed)
+                fail('secret_required', `Nothing was typed: ${cmd} needs ${input.target}.`, { path: key });
+            parsed.values[input.target] = secretOf(typed.startsWith('{') ? typed : typed.split(/\s+/).join('\n'), null, key, input.target_type);
+            continue;
+        }
+        fail('secret_required', `${cmd} needs ${input.target}, and there is no terminal to type it in. Ask the human to save it in a file only they can read (mode 600), as JSON or KEY=value lines, then run the command with ${toFlag(key)} <file>. Do not open or print that file.`, {
+            path: key,
+            next_step: { action: 'human_step', command: null, url: null },
+        });
+    }
+}
+function documentOf(file, key, spec) {
+    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 });
+    }
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch (e) {
+        fail('invalid_value', `${file} is not valid JSON: ${e.message}.`, { path: key });
+    }
+    const want = spec.input.target_type;
+    if (want === 'object' && (!v || typeof v !== 'object' || Array.isArray(v)))
+        fail('invalid_value', `${file} is not a JSON object.`, { path: key });
+    if (want === 'array' && !Array.isArray(v))
+        fail('invalid_value', `${file} is not a JSON list.`, { path: key });
+    return v;
+}
+/** JSON, or KEY=value lines (keys lowercased: API_KEY is api_key). The value never goes in a message. */
+function secretOf(text, file, key, type) {
+    const where = file ?? 'What was typed';
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{')) {
+        let v;
+        try {
+            v = JSON.parse(trimmed);
+        }
+        catch {
+            fail('invalid_value', `${where} is not valid JSON.`, { path: key });
+        }
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            fail('invalid_value', `${where} is not a JSON object.`, { path: key });
+        return v;
+    }
+    const out = {};
+    for (const line of trimmed.split(/\r?\n/).map((l) => l.trim())) {
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq < 1)
+            fail('invalid_value', `${where} has a line that is not KEY=value.`, { path: key });
+        const value = line.slice(eq + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+        if (value)
+            out[line.slice(0, eq).trim().toLowerCase()] = value;
+    }
+    if (!Object.keys(out).length)
+        fail('secret_required', `${where} has no values.`, { path: key });
+    if (type !== 'object') {
+        const values = Object.values(out);
+        if (values.length !== 1)
+            fail('invalid_value', `${where} has to hold one value.`, { path: key });
+        return values[0];
+    }
+    return out;
+}

package/dist/login.js

@@ -9,13 +9,12 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { storedLogin, storeLogin } from './config.js';
+import { authUrl, storedLogin, storeLogin } from './config.js';
 import { CliError, errorBody, fail } from './errors.js';
 import { USER_AGENT } from './version.js';
 export const PROVISIONING_URL = 'https://dashboard.commercelayer.io/user/provisioning_api';
-const AUTH_URL = 'https://auth.commercelayer.io/oauth/token';
 const MARGIN_MS = 60_000;
-export const authUrl = () => process.env.C11R_AUTH_URL || AUTH_URL;
+export { authUrl };
 /** Where the human saves the client id and secret when there is no terminal to type them in. */
 export function secretFileDefault() {
     const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
@@ -78,25 +77,29 @@ export async function loginToken(opts = {}) {
     return minted.token;
 }
 export const hasLogin = () => Boolean(process.env.C11R_PROVISIONING_TOKEN) || storedLogin() !== null;
-/** The client id and secret, from a file the human saved: key=value lines, JSON, or the secret alone. */
-export function readSecretFile(file) {
+/** A secret file's text: a plain file only its owner can read, else insecure_file. */
+export function readPrivateFile(file, flagPath) {
     let st;
     try {
         st = fs.lstatSync(file);
     }
     catch {
-        fail('invalid_value', `${file} does not exist.`, { path: 'secret_file' });
+        fail('invalid_value', `${file} does not exist.`, { path: flagPath });
     }
     if (st.isSymbolicLink() || !st.isFile())
-        fail('insecure_file', `${file} is not a plain file. c11r reads a secret only from a plain file.`, { path: 'secret_file' });
+        fail('insecure_file', `${file} is not a plain file. c11r reads a secret only from a plain file.`, { path: flagPath });
     if (st.mode & 0o077) {
         fail('insecure_file', `${file} can be read by other users (mode ${(st.mode & 0o777).toString(8)}). c11r reads a secret only from a file that only its owner can read, mode 600.`, {
-            path: 'secret_file',
+            path: flagPath,
             next_step: { action: 'human_step', command: null, url: null },
             details: { file, mode: (st.mode & 0o777).toString(8) },
         });
     }
-    const text = fs.readFileSync(file, 'utf8');
+    return fs.readFileSync(file, 'utf8');
+}
+/** The client id and secret, from a file the human saved: key=value lines, JSON, or the secret alone. */
+export function readSecretFile(file) {
+    const text = readPrivateFile(file, 'secret_file');
     const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
     try {
         const json = JSON.parse(text);

package/dist/resources.js

@@ -21,13 +21,14 @@ export function resourceRequest(noun, verb, id, values) {
         else if (flag.to === 'local')
             continue;
         else if (flag.to === 'filter')
-            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = text(value);
+            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = flag.filter.op === 'in' ? inList(value) : text(value);
         else
             query[key] = text(value);
     }
     // The schema's own route when it gives one (/plans/current, /members/invite), else the grammar.
     const path = verb.path
-        ? verb.path.replace(/\{[^}]+\}/, id === undefined ? '' : encodeURIComponent(id))
+        ? // No id (one given by its id_alternative flags): the segment goes, /prices/{id}/tiers is /prices/tiers.
+            verb.path.replace(/\/\{[^}]+\}/, id === undefined ? '' : `/${encodeURIComponent(id)}`)
         : ['list', 'get', 'create', 'update', 'delete'].includes(verb.name)
             ? verb.name === 'list' || verb.name === 'create'
                 ? base
@@ -38,4 +39,7 @@ export function resourceRequest(noun, verb, id, values) {
         req.body = body;
     return req;
 }
+// An in list is joined by commas, or sent as a JSON array of strings when a value has a comma of its
+// own ("UK VAT, manual"), so the API keeps each value whole (contract 28.4).
+const inList = (v) => (Array.isArray(v) && v.some((x) => typeof x === 'string' && x.includes(',')) ? JSON.stringify(v.map(String)) : text(v));
 const text = (v) => (Array.isArray(v) ? v.join(',') : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v));

package/dist/schema.js

@@ -6,8 +6,7 @@
 import { closest, fail, fixWith } from './errors.js';
 const FIELD_TYPES = ['string', 'integer', 'number', 'money', 'boolean', 'date', 'datetime', 'enum', 'object', 'array', 'ref'];
 export const FILTER_OPS = ['eq', 'in', 'gt', 'gte', 'lt', 'lte', 'start', 'cont', 'null'];
-/** The contract's names; sandbox, the first proposal's name for an organization token, still reads. */
-const CREDENTIALS = { none: 'none', organization: 'organization', login: 'login', 'organization|login': 'organization|login', sandbox: 'organization', 'sandbox|login': 'organization|login' };
+const CREDENTIALS = { none: 'none', organization: 'organization', login: 'login', 'organization|login': 'organization|login' };
 const STANDARD = ['list', 'get', 'create', 'update', 'delete'];
 const METHOD = { list: 'GET', get: 'GET', create: 'POST', update: 'PATCH', delete: 'DELETE' };
 export function parseSchema(raw, expected) {
@@ -39,6 +38,7 @@ export function parseSchema(raw, expected) {
                 flags[f.name] = flag(f, method === 'GET' ? 'query' : 'body', Boolean(f.required || (name === 'create' && f.create === 'required')));
         for (const f of own(v.query))
             flags[f.name] = flag(f, 'query', Boolean(f.required));
+        fileInputs(flags, fields, own(v.body));
         if (v.secret) {
             flags.out = { type: 'string', to: 'local', description: 'The file the secret is written to, mode 600. By default one under ~/.config/c11r/secrets/<org>/.' };
             flags.format = { type: 'enum', to: 'local', values: ['env', 'json'], description: 'env: KEY=value lines, for a .env file; json: one JSON object. By default as the API answers it.' };
@@ -60,6 +60,7 @@ export function parseSchema(raw, expected) {
             plan: v.plan ?? null,
             credential: v.credential ? CREDENTIALS[v.credential] : state === 'none' ? 'none' : 'organization',
             secret: Boolean(v.secret),
+            idAlternative: Array.isArray(v.id_alternative) ? v.id_alternative.filter((x) => typeof x === 'string' && flags[x]) : [],
             confirmIf: Array.isArray(v.confirm_if) ? v.confirm_if.filter((x) => typeof x === 'string') : [],
             refused: v.served === false ? { by: v.refused_by ?? 'the API' } : null,
             path: v.path ? v.path.replace(/^\/v\d+(?=\/)/, '') : null,
@@ -77,6 +78,35 @@ export function parseSchema(raw, expected) {
         doc,
     };
 }
+/**
+ * A secret field gets --<name>-file in place of its own flag: the value never sits in a command
+ * line or a shell history. A document field keeps its flag (inline JSON) and gets --file, or
+ * --<name>-file when the verb has more than one.
+ */
+function fileInputs(flags, fields, body) {
+    const doc = (k) => fields.find((f) => f.name === k) ?? body.find((f) => f.name === k);
+    const keys = Object.keys(flags).filter((k) => flags[k].to === 'body' || flags[k].to === 'query');
+    for (const k of keys.filter((k) => doc(k)?.secret_input)) {
+        const f = flags[k];
+        delete flags[k];
+        flags[`${k}_file`] = {
+            type: 'string',
+            to: 'local',
+            input: { kind: 'secret', target: k, required: Boolean(f.required), target_type: f.type },
+            description: `${f.description ? `${f.description.replace(/\.?$/, '.')} ` : ''}A file with ${k}, as JSON or KEY=value lines, readable only by its owner (mode 600). Never given as a flag value; without the file, c11r asks in a terminal. Never printed.`,
+        };
+    }
+    const docs = keys.filter((k) => flags[k] && doc(k)?.file_input);
+    for (const k of docs) {
+        flags[docs.length === 1 ? 'file' : `${k}_file`] = {
+            type: 'string',
+            to: 'local',
+            input: { kind: 'document', target: k, required: Boolean(flags[k].required), target_type: flags[k].type },
+            description: `A JSON file with ${k}, in place of ${toFlag(k)}.`,
+        };
+    }
+}
+const toFlag = (key) => `--${key.replace(/_/g, '-')}`;
 function listFlags(flags, fields, doc) {
     for (const f of fields) {
         for (const op of f.filter ?? []) {
@@ -115,7 +145,7 @@ function flag(f, to, required) {
         to,
         ...(f.values ? { values: f.values } : {}),
         ...(f.items ? { items: f.items } : {}),
-        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, p.type])) } : {}),
+        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, { type: p.type, ...(p.values ? { values: p.values } : {}) }])) } : {}),
         ...(f.noun ? { noun: f.noun } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),

package/dist/secrets.js

@@ -63,11 +63,16 @@ function nearestExisting(dir) {
     }
     return d;
 }
+const RECORD_LINE = '# c11r-record: ';
 /** Writes data.secret to its file and answers the envelope without the value. */
 export function writeSecret(r, plan, ctx) {
     const data = (r.data ?? {});
     const secret = data.secret;
-    const credentialId = data.credential?.id ?? data.id ?? ctx.id;
+    // credentials answer { credential: {...}, secret }, other nouns the record itself and secret.
+    const rec = (data.credential && typeof data.credential === 'object' ? data.credential : data);
+    const str = (v) => (typeof v === 'string' || typeof v === 'number' ? String(v) : null);
+    const credentialId = str(rec.id) ?? ctx.id;
+    const record = { noun: ctx.noun, id: credentialId ?? null, name: str(rec.name), code: str(rec.code) };
     const format = plan.format ?? (secret.format === 'json' ? 'json' : 'env');
     const file = plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`;
     const env = secret.env && Object.keys(secret.env).length ? { ...secret.env } : { [`CL_${(secret.kind ?? 'secret').toUpperCase()}`]: String(secret.value ?? '') };
@@ -76,8 +81,14 @@ export function writeSecret(r, plan, ctx) {
         env.CL_BASE_ENDPOINT = data.base_endpoint;
     const written = new Date().toISOString();
     const content = format === 'json'
-        ? JSON.stringify({ org: ctx.org, credential_id: credentialId ?? null, kind: secret.kind ?? null, value: secret.value ?? null, expires_at: secret.expires_at ?? null, env, written_at: written }, null, 2) + '\n'
-        : [`# ${secret.kind ?? 'secret'} of credential ${credentialId ?? '?'} in ${ctx.org ?? '?'}, written by c11r at ${written}.`, '# Keep it out of git.', ...Object.entries(env).map(([k, v]) => `${k}=${v}`), ''].join('\n');
+        ? JSON.stringify({ org: ctx.org, record, kind: secret.kind ?? null, value: secret.value ?? null, expires_at: secret.expires_at ?? null, env, written_at: written }, null, 2) + '\n'
+        : [
+            `# ${secret.kind ?? 'secret'} of ${ctx.noun} ${credentialId ?? '?'} in ${ctx.org ?? '?'}, written by c11r at ${written}.`,
+            `${RECORD_LINE}${JSON.stringify({ org: ctx.org, ...record })}`,
+            '# Keep it out of git.',
+            ...Object.entries(env).map(([k, v]) => `${k}=${v}`),
+            '',
+        ].join('\n');
     try {
         atomicWrite(file, content, plan.overwrite);
     }
@@ -128,13 +139,25 @@ function ignoredByGit(file) {
 }
 /** The folder of an organization's secret files. */
 export const orgSecretsDir = (org) => path.join(secretsDir(), safe(org));
+/** The record a file in the secrets folder belongs to, or null when c11r did not write it. */
+function recordOf(text) {
+    const line = text.split('\n').find((l) => l.startsWith(RECORD_LINE));
+    try {
+        const v = line ? JSON.parse(line.slice(RECORD_LINE.length)) : JSON.parse(text).record;
+        return v && typeof v === 'object' && typeof v.noun === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * After credentials delete: the files c11r wrote in the organization's secrets folder for that
- * credential (its secret and its tokens), found by the credential id each file records. Files
- * written with --out elsewhere are not tracked.
+ * After a delete: the files c11r wrote in the organization's secrets folder for that record (a
+ * credential's secret and tokens, a webhook's shared secret), found by the noun and the id, name
+ * or code each file records. Files written with --out elsewhere are not tracked.
  */
-export function removeCredentialFiles(org, credentialId) {
+export function removeRecordFiles(org, noun, keys) {
     const dir = orgSecretsDir(org);
+    const wanted = new Set(keys.filter((k) => typeof k === 'string' && k !== ''));
     let names;
     try {
         names = fs.readdirSync(dir);
@@ -154,26 +177,18 @@ export function removeCredentialFiles(org, credentialId) {
         catch {
             continue;
         }
-        let mine = text.startsWith('#') && new RegExp(`^# \\S+ of credential ${credentialId.replace(/[^\w-]/g, '')} in `).test(text);
-        if (!mine) {
-            try {
-                mine = JSON.parse(text).credential_id === credentialId;
-            }
-            catch {
-                // Not JSON, not ours.
-            }
-        }
-        if (mine) {
-            fs.rmSync(file);
-            removed.push(file);
-        }
+        const rec = recordOf(text);
+        if (!rec || rec.noun !== noun || ![rec.id, rec.name, rec.code].some((k) => k !== null && wanted.has(k)))
+            continue;
+        fs.rmSync(file);
+        removed.push(file);
     }
     if (removed.length) {
         try {
             fs.rmdirSync(dir);
         }
         catch {
-            // Not empty: other credentials' files stay.
+            // Not empty: other records' files stay.
         }
     }
     return removed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.0",
+  "version": "1.0.0-dev.2",
   "description": "c11r: the Commerce Layer CLI for coding agents. One grammar, c11r <noun> <verb>, from a sandbox to a running organization.",
   "homepage": "https://commercelayer.ai",
   "keywords": [