@jacebenson/jsn 4.3.11-dev.69 → 4.3.12-dev.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.11-dev.69",
+  "version": "4.3.12-dev.70",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/cli-adapter.js

@@ -3,6 +3,14 @@ import process from 'node:process';
 
 const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 const names = (x) => typeof x === 'string' ? [x] : (x || []);
+
+/**
+ * A repeatable option may be declared either way: `type: 'array'` (this
+ * adapter's historic spelling) or `array: true` (the yargs spelling most
+ * contributors reach for). Both must accumulate; honoring only the first
+ * silently kept the LAST value of `-f a=1 -f b=2` and dropped the rest.
+ */
+const isArrayOption = (spec) => spec?.type === 'array' || spec?.array === true;
 const commandName = (command) => command.trim().split(/\s+/)[0];
 const positionSpec = (command) => [...command.matchAll(/([<[])([^>\]]+)[>\]]/g)].map((m) => ({ name: m[2], required: m[1] === '<' }));
 
@@ -189,7 +197,7 @@ export class LocalCLI {
   _assign(argv, key, value, spec, opts = {}) {
     const validate = opts.validate !== false;
     const actual = spec?.name || key;
-    const values = spec?.type === 'array' ? (Array.isArray(value) ? value : [value]) : [value];
+    const values = isArrayOption(spec) ? (Array.isArray(value) ? value : [value]) : [value];
     if (validate && spec?.choices && values.some((item) => !spec.choices.includes(item))) {
       this._fail(`Invalid value for --${actual}: ${value}. Choose from: ${spec.choices.join(', ')}`);
       return false;
@@ -201,7 +209,7 @@ export class LocalCLI {
     const converted = spec?.type === 'boolean'
       ? (value === 'true' ? true : value === 'false' ? false : value)
       : spec?.type === 'number' ? Number(value) : value;
-    if (spec?.type === 'array') argv[actual] = [...(argv[actual] || []), ...values];
+    if (isArrayOption(spec)) argv[actual] = [...(argv[actual] || []), ...values];
     else argv[actual] = converted;
     argv[camel(actual)] = argv[actual];
     for (const alias of names(spec?.alias)) argv[alias] = argv[actual];
@@ -210,8 +218,8 @@ export class LocalCLI {
     const options = this._optionConfig(path);
     const defs = {};
     for (const [key, spec] of options) defs[key] = {
-      type: spec.type === 'number' || spec.type === 'array' ? 'string' : (spec.type || 'boolean'),
-      multiple: spec.type === 'array',
+      type: spec.type === 'number' || isArrayOption(spec) ? 'string' : (spec.type || 'boolean'),
+      multiple: isArrayOption(spec),
     };
     args = args.map((arg) => {
       if (/^-[^-]=/.test(arg)) return `--${arg.slice(1)}`;

package/src/commands/_generic.js

@@ -1,6 +1,6 @@
 // Generic table-based CRUD command builder
 
-import { formatRecordForDisplay, getStringField, parseDataArg, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildRecordPayload, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { getCurrentUser, getCurrentApplication } from '../context.js';
 import { FormatAuto } from '../output.js';
@@ -108,7 +108,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
     if (!readOnly) {
       crumbs.unshift(
         { action: 'delete', cmd: `jsn ${name} delete ${id}`, description: `Delete this ${singular}` },
-        { action: 'update', cmd: `jsn ${name} update ${id} --data '{...}'`, description: `Update this ${singular}` }
+        { action: 'update', cmd: `jsn ${name} update ${id} -f name=value`, description: `Update this ${singular}` }
       );
     }
     return crumbs;
@@ -152,7 +152,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             app.ok(record, {
               summary: `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${recordName}`,
               breadcrumbs: [
-                ...(readOnly ? [] : [{ action: 'update', cmd: `jsn ${name} update ${recordName} --data '{...}'`, description: `Update this ${singular}` }]),
+                ...(readOnly ? [] : [{ action: 'update', cmd: `jsn ${name} update ${recordName} -f name=value`, description: `Update this ${singular}` }]),
                 { action: 'list', cmd: `jsn ${name} list`, description: `Back to all ${name}` },
               ],
             });
@@ -215,10 +215,12 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           command: 'create',
           describe: `Create a new ${singular}`,
           builder: (y) => y
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const record = await app.sdk.create(table, recordData);
             app.ok(record, {
               summary: `Created ${singular}`,
@@ -232,8 +234,10 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           command: 'update <identifier>',
           describe: `Update ${vowelArticle(singular)} ${singular}`,
           builder: (y) => y
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
             const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular });
@@ -242,7 +246,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             }
 
             const sysID = unwrapSysId(record);
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const updated = await app.sdk.update(table, sysID, recordData);
             app.ok(updated, { summary: `Updated ${singular} ${id}` });
           }),

package/src/commands/_ticket.js

@@ -1,7 +1,7 @@
 // Generic command builder for CRUD operations on a ServiceNow table
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
-import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
@@ -73,7 +73,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
               app.ok(record, {
                 summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
                 breadcrumbs: [
-                  { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                  { action: 'update', cmd: `jsn ${alias} update ${number} -f state=2`, description: `Update this ${displayName}` },
                   { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
                 ],
               });
@@ -139,7 +139,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             app.ok(record, {
               summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
               breadcrumbs: [
-                { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                { action: 'update', cmd: `jsn ${alias} update ${number} -f state=2`, description: `Update this ${displayName}` },
                 { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
               ],
             });
@@ -151,16 +151,16 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           builder: (y) => y
             .option('description', { alias: 'd', type: 'string', describe: 'Short description' })
             .option('priority', { type: 'string', describe: 'Priority (1-5)' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.description) recordData.short_description = argv.description;
             if (argv.priority) recordData.priority = argv.priority;
             if (!recordData.short_description) {
-              throw new Error('short_description is required (use --description or --data)');
+              throw new Error('short_description is required (use --description, -f short_description=..., or --data)');
             }
             const record = await app.sdk.create(table, recordData);
             app.ok(record, {
@@ -175,10 +175,13 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           command: 'update <number>',
           describe: `Update a ${displayName}`,
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
             const updated = await app.sdk.update(table, sysID, recordData);
             app.ok(updated, {

package/src/commands/groups.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch, buildRecordPayload } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('groups', { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -94,12 +94,12 @@ export function groupsCmd(wrap) {
           builder: (y) => y
             .option('name', { alias: 'n', type: 'string', describe: 'Group name' })
             .option('manager', { type: 'string', describe: 'Manager name or sys_id' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.name) recordData.name = argv.name;
             if (argv.manager) recordData.manager = argv.manager;
             if (!recordData.name) {
@@ -118,11 +118,14 @@ export function groupsCmd(wrap) {
           command: 'update <name>',
           describe: 'Update a group by name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.name;
             assertSafeExactMatch(id);
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
             const params = new URLSearchParams();
             params.set('sysparm_query', isSysID ? `sys_id=${id}` : `name=${id}`);

package/src/commands/records.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -142,7 +142,7 @@ export function recordsCmd(wrap) {
             }
 
             const breadcrumbs = [
-              { action: 'create', cmd: `jsn records create --table ${table} --data '{...}'`, description: 'Create a new record' },
+              { action: 'create', cmd: `jsn records create --table ${table} -f name=value`, description: 'Create a new record' },
               { action: 'filter', cmd: `jsn records list --table ${table} --query "priority=1"`, description: 'Filter: priority 1 only' },
               { action: 'columns', cmd: `jsn columns --table ${table}`, description: 'View available columns' },
             ];
@@ -221,12 +221,13 @@ export function recordsCmd(wrap) {
           describe: 'Create a new record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
@@ -249,12 +250,13 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
@@ -401,22 +403,15 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('query', { type: 'string', demandOption: true, describe: 'Encoded query selecting the records to update (e.g. "priority=1^state=1")' })
-            .option('set', { type: 'string', demandOption: true, describe: 'JSON object of fields to set (e.g. \'{"state":"3"}\')' })
+            .option('set', { type: 'string', describe: 'JSON object of fields to set' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('dry-run', { type: 'boolean', default: true, describe: 'Preview the count + a sample without mutating (default)' })
             .option('execute', { type: 'boolean', default: false, describe: 'Perform the update after confirmation' })
             .option('limit', { type: 'number', default: 200, describe: 'Max records to update when executing' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation (with --execute)' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
-            let set;
-            try {
-              set = JSON.parse(argv.set);
-            } catch (e) {
-              throw new Error(`Invalid --set JSON: ${e.message}`, { cause: e });
-            }
-            if (!set || typeof set !== 'object' || Array.isArray(set)) {
-              throw new Error('--set must be a JSON object of field=value pairs');
-            }
+            const set = buildRecordPayload({ ...argv, data: argv.set }, { required: true });
             if (!argv['dry-run'] && !argv.execute) {
               argv.execute = true; // explicit --no-dry-run implies execute intent
             }

package/src/commands/requests.js

@@ -53,7 +53,7 @@ async function enrichedShowHandler(argv, app) {
   app.ok(record, {
     summary: `Request ${number}`,
     breadcrumbs: [
-      { action: 'update', cmd: `jsn req update ${number} --data '{...}'`, description: 'Update this request' },
+      { action: 'update', cmd: `jsn req update ${number} -f state=2`, description: 'Update this request' },
       { action: 'list', cmd: `jsn req list`, description: 'Back to all requests' },
     ],
   });

package/src/commands/tickets.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -33,7 +33,7 @@ export function ticketsCmd(wrap) {
             const records = await app.sdk.list('task', params);
             const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
             const breadcrumbs = [
-              { action: 'create', cmd: 'jsn tickets create --data \'{...}\'', description: 'Create a new ticket' },
+              { action: 'create', cmd: 'jsn tickets create -f short_description=New ticket', description: 'Create a new ticket' },
             ];
             if (records.length === argv.limit) {
               breadcrumbs.push({
@@ -71,9 +71,13 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const record = await app.sdk.create('task', recordData);
             app.ok(record, { summary: `Created ticket ${getStringField(record, 'number')}` });
           }),
@@ -81,9 +85,13 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
             const updated = await app.sdk.update('task', sysID, recordData);
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });

package/src/commands/users.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -72,12 +72,12 @@ export function usersCmd(wrap) {
             .option('username', { alias: 'u', type: 'string', describe: 'Username (e.g. john.doe)' })
             .option('name', { alias: 'n', type: 'string', describe: 'Full name (e.g. John Doe)' })
             .option('email', { alias: 'e', type: 'string', describe: 'Email address' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.username) recordData.user_name = argv.username;
             if (argv.name) recordData.name = argv.name;
             if (argv.email) recordData.email = argv.email;
@@ -97,10 +97,13 @@ export function usersCmd(wrap) {
           command: 'update <identifier>',
           describe: 'Update a user by user_name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table: 'sys_user', identifier: id, matchField: 'user_name', resource: 'User' });
             const updated = await app.sdk.update('sys_user', sysID, recordData);
             app.ok(updated, {

package/src/helpers.js

@@ -522,6 +522,50 @@ export function parseDataArg(argv) {
   }
 }
 
+/**
+ * Parse repeatable -f/--field name=value options.
+ * Values remain strings, including empty values and values containing '='.
+ */
+export function parseFieldPairs(argv = {}) {
+  const raw = argv.field == null ? [] : (Array.isArray(argv.field) ? argv.field : [argv.field]);
+  const result = {};
+  for (const token of raw) {
+    const text = String(token);
+    const equals = text.indexOf('=');
+    if (equals < 0) throw new Error(`-f expects field=value, got "${text}"`);
+    const name = text.slice(0, equals);
+    let value = text.slice(equals + 1);
+    if (!name || /\\s/.test(name) || !/^[A-Za-z0-9_.]+$/.test(name)) {
+      throw new Error(`-f expects a valid field name, got "${name}"`);
+    }
+    if (value.startsWith('@@')) {
+      value = value.slice(1);
+    } else if (value.startsWith('@')) {
+      value = fs.readFileSync(value.slice(1), 'utf-8');
+      if (value.charCodeAt(0) === 0xFEFF) value = value.slice(1);
+    }
+    result[name] = value;
+  }
+  return result;
+}
+
+/**
+ * Build a record mutation payload from JSON input and/or field pairs.
+ */
+export function buildRecordPayload(argv = {}, { required = true } = {}) {
+  const hasData = Boolean(argv.data || argv['data-file'] || argv['data-stdin']);
+  const hasFields = argv.field != null && (Array.isArray(argv.field) ? argv.field.length > 0 : true);
+  if (!hasData && !hasFields) {
+    if (required) throw new Error('Provide fields with -f name=value, or a JSON payload with --data/--data-file/--data-stdin');
+    return {};
+  }
+  const payload = hasData ? parseDataArg(argv) : {};
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Record payload must be a JSON object');
+  }
+  return { ...payload, ...parseFieldPairs(argv) };
+}
+
 /**
  * Translate human-readable type names to ServiceNow item_option_new type IDs.
  * Maps common names like "date", "select", "multilinetext" to their integer IDs.