datagrok-tools 6.5.7 → 6.5.9

package/bin/commands/server.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.HELP_SERVER = void 0;
 exports.buildInlineManifest = buildInlineManifest;
 exports.parseFuncCall = parseFuncCall;
 exports.resolveManifestSources = resolveManifestSources;
@@ -12,17 +13,29 @@ var path = _interopRequireWildcard(require("path"));
 var _nodeDapi = require("../utils/node-dapi");
 var _serverClient = require("../utils/server-client");
 var _serverOutput = require("../utils/server-output");
+var _serverMigrate = require("./server-migrate");
+var _serverDomains = require("./server-domains");
+var _registry = require("../utils/migrate/registry");
+var _walker = require("../utils/migrate/walker");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /// Docs: [Grok Dapi](/docs/plans/grok-dapi/)
 
+/** `queries|scripts get <nqName>` resolves through `/entities`, which needs the entity type. */
+const ENTITY_TYPES = {
+  queries: 'DataQuery',
+  scripts: 'Script',
+  reports: 'UserReport'
+};
 const ENTITIES = ['users', 'groups', 'functions', 'connections', 'queries', 'scripts', 'packages', 'reports', 'files', 'tables'];
-const VERBS = ['list', 'get', 'delete'];
+const COMMANDS = ['shares', 'domains', 'raw', 'batch', 'describe', 'healthcheck', 'sync', 'pull', 'push', 'migrate', 'diff', 'bundle'];
+const VERBS = ['list', 'count', 'get', 'delete'];
 async function server(argv) {
   const args = argv['_'].slice(1);
   const entity = args[0];
   const verb = args[1];
   const rest = args.slice(2);
   const output = argv.output ?? argv.o ?? 'table';
+  (0, _serverOutput.setOutputFormat)(output);
   const limit = Number(argv.limit ?? argv.l ?? 50);
   const offset = Number(argv.offset ?? 0);
   const filter = argv.filter ?? argv.f ?? '';
@@ -34,26 +47,40 @@ async function server(argv) {
   }
   let client;
   try {
-    client = await (0, _serverClient.createClient)(host);
+    client = await (0, _serverClient.createClient)(host, !!argv.admin);
   } catch (err) {
+    // a bad alias, URL or key is not a usage error: no help dump, just the reason
     (0, _serverOutput.printError)(err);
-    return false;
+    process.exitCode = 1;
+    return true;
   }
   const dapi = new _nodeDapi.NodeDapi(client);
   try {
     // await each handler so a rejection lands in the catch below instead of
     // escaping to grok.js as an unhandled rejection (stack trace + exit 255)
+    if (['pull', 'push', 'migrate', 'diff', 'bundle'].includes(entity)) return await (0, _serverMigrate.handleMigrate)(dapi, entity, [verb, ...rest].filter(Boolean), argv, output);
+    if (entity === 'domains') return await (0, _serverDomains.handleDomains)(dapi, verb, rest, argv, output);
     if (entity === 'batch') return await handleBatch(dapi, argv, verb, rest, output);
-    if (entity === 'raw') return await handleRaw(dapi, verb, rest, output);
+    if (entity === 'raw') return await handleRaw(dapi, verb, rest, argv, output);
     if (entity === 'describe') return await handleDescribe(dapi, verb ?? rest[0], output);
     if (entity === 'healthcheck') return await handleHealthcheck(dapi, argv, output);
     if (entity === 'sync') return await handleSync(dapi, verb, rest, argv, output);
     if (entity === 'functions' && verb === 'run') return await handleFuncRun(dapi, rest, argv, output);
     if (entity === 'functions' && verb === 'list') return await handleFunctionsList(dapi, argv, limit, offset, filter, output);
     if (entity === 'files' && verb === 'list') {
-      const path = rest[0] ?? '';
-      const result = await dapi.files.list(path, recursive);
-      (0, _serverOutput.printOutput)(result, output);
+      if (!rest[0]) {
+        (0, _serverOutput.printError)(new Error('Usage: grok s files list <connector>[/<path>] [-r]\n  e.g. grok s files list "System:AppData" -r'));
+        return false;
+      }
+      const files = await dapi.files.list(String(rest[0]), recursive);
+      if (output === 'json') (0, _serverOutput.printOutput)(files, output);else if (output === 'quiet') {
+        for (const f of files) console.log(f.path);
+      } else (0, _serverOutput.printOutput)(files.map(f => ({
+        path: f.path,
+        kind: f.isFile ? 'file' : 'dir',
+        size: f.isFile ? f.size ?? '' : '',
+        updatedOn: f.updatedOn ?? ''
+      })), output);
       return true;
     }
     if (entity === 'files' && verb === 'get') {
@@ -75,8 +102,7 @@ async function server(argv) {
     if (entity === 'connections' && verb === 'test') return await handleConnTest(dapi, rest, argv, output);
     if (entity === 'groups' && verb === 'add-members') return await handleGroupAddMembers(dapi, rest, argv, output);
     if (entity === 'groups' && verb === 'remove-members') return await handleGroupRemoveMembers(dapi, rest, argv, output);
-    if (entity === 'groups' && verb === 'list-members') return await handleGroupListMembers(dapi, rest, argv, output);
-    if (entity === 'groups' && verb === 'list-memberships') return await handleGroupListMemberships(dapi, rest, argv, output);
+    if (entity === 'groups' && (verb === 'list-members' || verb === 'list-memberships')) return await handleGroupListMembers(dapi, verb, rest, argv, output);
     if (entity === 'users' && verb === 'block') return await handleUserBlock(dapi, rest, output);
     if (entity === 'users' && verb === 'unblock') return await handleUserUnblock(dapi, rest, output);
     if (entity === 'tables' && verb === 'download') return await handleTablesDownload(dapi, rest, argv, output);
@@ -90,7 +116,7 @@ async function server(argv) {
     if (entity === 'packages' && verb === 'update') return await handlePackagesUpdate(dapi, rest, argv, output);
     const source = dapi[entity];
     if (!source || !ENTITIES.includes(entity)) {
-      (0, _serverOutput.printError)(new Error(`Unknown entity type: '${entity}'. Valid: ${ENTITIES.join(', ')}`));
+      (0, _serverOutput.printError)(new Error(`Unknown command '${entity}'. Entities: ${ENTITIES.join(', ')}. Other commands: ${COMMANDS.join(', ')}. See grok s --help`));
       return false;
     }
     if (!verb) {
@@ -98,17 +124,30 @@ async function server(argv) {
       return true;
     }
     if (verb === 'list') {
-      const page = Math.floor(offset / limit);
-      const results = await source.filter(filter).by(limit).page(page).list();
+      const results = source instanceof _nodeDapi.InternalDataSource ? await source.list({
+        text: filter || undefined,
+        limit,
+        page: Math.floor(offset / limit) + 1
+      }) : await source.filter(filter).by(limit).page(Math.floor(offset / limit)).list();
       (0, _serverOutput.printOutput)(results, output);
       return true;
     }
+    if (verb === 'count') {
+      if (entity === 'reports') throw new Error('The server has no count endpoint for reports; use `grok s reports list --output quiet | wc -l`');
+      const n = source instanceof _nodeDapi.InternalDataSource ? await source.count({
+        text: filter || undefined
+      }) : await source.filter(filter).count();
+      (0, _serverOutput.printOutput)(n, output);
+      return true;
+    }
     if (verb === 'get') {
       if (!rest[0]) {
         (0, _serverOutput.printError)(new Error('Usage: grok s <entity> get <id>'));
         return false;
       }
-      const result = await source.find(rest[0]);
+      // The internal routers find by id only; a name has to be resolved through /entities first.
+      const id = source instanceof _nodeDapi.InternalDataSource && !(0, _registry.isUuid)(rest[0]) ? (await (0, _walker.resolveEntity)(dapi, rest[0], ENTITY_TYPES[entity])).id : rest[0];
+      const result = await source.find(id);
       (0, _serverOutput.printOutput)(result, output);
       return true;
     }
@@ -125,8 +164,13 @@ async function server(argv) {
     (0, _serverOutput.printError)(new Error(`Unknown verb: '${verb}'. Valid: ${VERBS.join(', ')}${extraVerbs}`));
     return false;
   } catch (err) {
-    (0, _serverOutput.printError)(err);
-    return false;
+    // A runtime failure is not a usage error: report it and exit non-zero without
+    // making grok.js dump the help block (which it does for every `false` result).
+    (0, _serverOutput.printError)(err, {
+      verbose: !!argv.verbose
+    });
+    process.exitCode = 1;
+    return true;
   }
 }
 async function handleFilesPut(dapi, rest, output) {
@@ -438,13 +482,20 @@ async function handleFunctionsList(dapi, argv, limit, offset, userFilter, output
   (0, _serverOutput.printOutput)(results, output);
   return true;
 }
-async function handleRaw(dapi, method, rest, output) {
+async function handleRaw(dapi, method, rest, argv, output) {
   if (!method || !rest[0]) {
-    (0, _serverOutput.printError)(new Error('Usage: grok s raw <METHOD> <path>'));
+    (0, _serverOutput.printError)(new Error('Usage: grok s raw <METHOD> <path> [--json body.json | --data \'{"k": 1}\']\n  e.g. grok s raw GET /users/current   (paths are API-relative; a leading /api is accepted)'));
     return false;
   }
-  const path = rest[0];
-  const result = await dapi.raw(method, path);
+  let body;
+  if (argv.json) body = readJsonFile(argv.json);else if (argv.data !== undefined) {
+    try {
+      body = JSON.parse(String(argv.data));
+    } catch {
+      body = String(argv.data);
+    }
+  }
+  const result = await dapi.raw(method, String(rest[0]), body);
   (0, _serverOutput.printOutput)(result, output);
   return true;
 }
@@ -454,21 +505,15 @@ async function handleSync(dapi, subject, rest, argv, output) {
   // runs are read-only here; `run` triggers an actual push and prints
   // the per-item summary. Full reference in
   // core/docs/plans/instance-sync.md (Phase 7 / operational polish).
-  //
-  // `_callSync` does dual-path routing: tries `/api/sync/...` first
-  // (nginx-fronted deployments) and falls back to `/sync/...` (bare
-  // datlas on :8082). Same approach as the server-side handshake
-  // code so the CLI works against either layout.
   const verb = rest[0];
+  // a 1.27 server has no /sync routes at all: report that as "not found", not as a failure
   const callSync = async (method, path, body) => {
-    for (const prefix of ['/api', '']) {
-      const r = body !== undefined ? await dapi.raw(method, `${prefix}${path}`, body) : await dapi.raw(method, `${prefix}${path}`);
-      // raw() returns `null` for 404, but the server returns HTML for
-      // 404 too — treat anything that isn't a sync-shaped object/array
-      // as a miss and fall through to the alternate prefix.
-      if (r && (Array.isArray(r) || typeof r === 'object') && r['#type'] !== 'ApiError') return r;
+    try {
+      return await dapi.raw(method, path, body);
+    } catch (err) {
+      if (err?.apiError?.errorCode === 404) return null;
+      throw err;
     }
-    return null;
   };
   if (subject === 'pairs' && verb === 'list') {
     const status = argv.status ? `?status=${encodeURIComponent(argv.status)}` : '';
@@ -533,8 +578,9 @@ async function handleSync(dapi, subject, rest, argv, output) {
 }
 async function handleHealthcheck(dapi, argv, output) {
   const module = argv.module;
-  const path = module ? `/api/public/v1/healthcheck?module=${encodeURIComponent(module)}` : '/api/public/v1/healthcheck';
-  const result = await dapi.raw('GET', path);
+  const path = module ? `/public/v1/healthcheck?module=${encodeURIComponent(module)}` : '/public/v1/healthcheck';
+  const result = await dapi.client.get(path);
+  const services = Array.isArray(result?.services) ? result.services : [];
   if (output === 'json') {
     (0, _serverOutput.printOutput)(result, output);
     return true;
@@ -546,16 +592,25 @@ async function handleHealthcheck(dapi, argv, output) {
     console.log(`time:    ${result?.time ?? ''}`);
     console.log('');
   }
-  (0, _serverOutput.printOutput)(result?.services ?? [], output);
+  if (services.length) (0, _serverOutput.printOutput)(services, output);else if (module) throw new Error(`Module '${module}' is not reported by the server`);else if (output !== 'quiet') console.log('(no services reported)');
   return true;
 }
 async function handleDescribe(dapi, entityType, output) {
   if (!entityType) {
-    (0, _serverOutput.printError)(new Error('Usage: grok s describe <entity-type>'));
+    (0, _serverOutput.printError)(new Error('Usage: grok s describe <entity|type>   e.g. grok s describe connections, grok s describe Project'));
     return false;
   }
-  const result = await dapi.describe(entityType);
-  (0, _serverOutput.printOutput)(result, output);
+  const result = await dapi.describe(String(entityType));
+  if (output === 'json') {
+    (0, _serverOutput.printOutput)(result, output);
+    return true;
+  }
+  if (output !== 'quiet' && result.type) console.log(`${result.type.name}${result.type.friendlyName && result.type.friendlyName !== result.type.name ? ` (${result.type.friendlyName})` : ''}  id ${result.type.id}${result.type.isPackageEntity ? '  package entity' : ''}\n`);
+  if (!result.fields.length) {
+    if (output !== 'quiet') console.log('(no entity of this type exists on the server to derive the fields from)');
+    return true;
+  }
+  (0, _serverOutput.printOutput)(output === 'quiet' ? result.fields.map(f => f.field) : result.fields, output);
   return true;
 }
 async function handleFuncRun(dapi, rest, argv, output) {
@@ -577,6 +632,7 @@ async function handleFuncRun(dapi, rest, argv, output) {
     const parsed = parseFuncCall(funcName);
     funcName = parsed.name;
     params = parsed.params;
+    if (Object.keys(params).some(k => /^\d+$/.test(k))) params = (0, _nodeDapi.mapPositionalParams)(params, (await dapi.functions.find(funcName))?.parameterInfos, funcName);
   }
   const result = await dapi.functions.run(funcName, params);
   (0, _serverOutput.printOutput)(result, output);
@@ -611,18 +667,25 @@ async function handleSharesAdd(dapi, rest, argv, output) {
   return true;
 }
 async function handleSharesList(dapi, rest, output) {
-  const entityId = rest[0];
-  if (!entityId) {
-    (0, _serverOutput.printError)(new Error('Usage: grok s shares list <entity-id>   (entity id must be a UUID)'));
+  if (!rest[0]) {
+    (0, _serverOutput.printError)(new Error('Usage: grok s shares list <entity-id-or-name>   e.g. grok s shares list "Admin:MyConnection"'));
     return false;
   }
+  const entityId = (0, _registry.isUuid)(String(rest[0])) ? String(rest[0]) : (await (0, _walker.resolveEntity)(dapi, String(rest[0]))).id;
   const perms = await dapi.shares.list(entityId);
-  const flat = (Array.isArray(perms) ? perms : []).map(p => ({
-    group: p?.userGroup?.friendlyName ?? p?.userGroup?.name ?? p?.userGroup?.id ?? '',
-    groupId: p?.userGroup?.id ?? '',
-    access: p?.permission?.name ?? p?.permission?.friendlyName ?? '',
-    personal: p?.userGroup?.personal ?? false
-  }));
+  // the permissions route returns group ids only; a share touches a handful of groups
+  const groups = new Map();
+  for (const id of new Set(perms.map(p => p?.userGroup?.id).filter(Boolean))) groups.set(id, await dapi.groups.find(id));
+  const flat = perms.map(p => {
+    const g = groups.get(p?.userGroup?.id) ?? p?.userGroup ?? {};
+    return {
+      group: g.friendlyName ?? g.name ?? g.id ?? '',
+      groupId: g.id ?? '',
+      access: p?.permission?.name ?? p?.permission?.friendlyName ?? '',
+      personal: g.personal ?? false,
+      inherited: p?.inheritedByLink === true
+    };
+  });
   (0, _serverOutput.printOutput)(flat, output);
   return true;
 }
@@ -714,23 +777,14 @@ async function handleGroupRemoveMembers(dapi, rest, argv, output) {
   if (anyError) process.exitCode = 1;
   return true;
 }
-async function handleGroupListMembers(dapi, rest, argv, output) {
+async function handleGroupListMembers(dapi, verb, rest, argv, output) {
   if (!rest[0]) {
-    (0, _serverOutput.printError)(new Error('Usage: grok s groups list-members <group> [--admin | --no-admin]'));
+    (0, _serverOutput.printError)(new Error(`Usage: grok s groups ${verb} <group-or-login> [--admin | --no-admin] [--user]`));
     return false;
   }
   const admin = typeof argv.admin === 'boolean' ? argv.admin : undefined;
-  const result = await dapi.groups.getMembers(rest[0], admin);
-  (0, _serverOutput.printOutput)(result, output);
-  return true;
-}
-async function handleGroupListMemberships(dapi, rest, argv, output) {
-  if (!rest[0]) {
-    (0, _serverOutput.printError)(new Error('Usage: grok s groups list-memberships <group> [--admin | --no-admin]'));
-    return false;
-  }
-  const admin = typeof argv.admin === 'boolean' ? argv.admin : undefined;
-  const result = await dapi.groups.getMemberships(rest[0], admin);
+  const personalOnly = argv.user === true;
+  const result = verb === 'list-members' ? await dapi.groups.getMembers(String(rest[0]), admin, personalOnly) : await dapi.groups.getMemberships(String(rest[0]), admin, personalOnly);
   (0, _serverOutput.printOutput)(result, output);
   return true;
 }
@@ -867,7 +921,7 @@ function parseFuncCall(expr) {
     params: Object.fromEntries(positional.map((v, i) => [String(i), v]))
   };
 }
-const HELP_SERVER = `
+const HELP_SERVER = exports.HELP_SERVER = `
 Usage: grok server <entity> <verb> [args] [options]
        grok s <entity> <verb> [args] [options]
 
@@ -875,27 +929,29 @@ Manage a Datagrok server from the command line.
 
 Entities:
   users, groups, functions, connections, queries, scripts, packages, reports, files, tables
+  (plus domains, shares, batch, raw, describe, healthcheck, sync, pull/push/migrate/diff/bundle below)
 
 Verbs:
-  list      List entities
+  list      List entities (--filter, --limit, --offset)
+  count     Count entities (--filter)
   get       Get a single entity by ID or name
-  delete    Delete an entity by ID
+  delete    Delete an entity by ID or name (users cannot be deleted: block them; functions: scripts and queries only)
 
 Special commands:
-  grok s functions run <Name:func(args)>              Call a function
+  grok s functions run <Name:func(args)>              Call a function (positional args map onto its inputs)
   grok s functions list [--type <t>] [--language <l>] [--package <p>] [--filter <expr>]
                                                       Type: script|query|function|package
                                                       Language applies to scripts (python, r, julia, nodejs, octave, grok)
-  grok s files list <path> [-r]                       List files (recursive with -r)
+  grok s files list <connector>[/<path>] [-r]         List a share (recursive with -r): path, kind, size
   grok s files get <path>                             Download a file (returns bytes)
   grok s files delete <path>                          Delete a file
   grok s files put <local> <remote>                   Upload a local file
-  grok s raw <METHOD> <path>                          Hit any API endpoint
-  grok s describe <entity-type>                       Show entity JSON schema
+  grok s raw <METHOD> <path> [--json f | --data j]    Any API endpoint; path is API-relative (/users/current), /api prefix optional
+  grok s describe <entity|type>                       Fields of an entity type (registry record + a live sample)
   grok s healthcheck [--module <name>]                Check server + per-module health
   grok s shares add <entity> <group>[,<group>...] [--access View|Edit]
                                                       Share an entity with one or more groups
-  grok s shares list <entity-id>                      List who an entity (UUID) is shared with
+  grok s shares list <entity-id-or-name>              List who an entity is shared with
   grok s users save --json user.json                  Create or update a user from a JSON file
   grok s groups save --json group.json [--save-relations]
                                                       Create or update a group from a JSON file
@@ -905,12 +961,15 @@ Special commands:
   grok s connections test --json conn.json            Test connectivity of a connection defined in JSON
   grok s groups add-members <group> <m>... [--admin]  Add one or more users/groups as members
   grok s groups remove-members <group> <m>...         Remove members (no-op if not a member)
-  grok s groups list-members <group> [--admin]        List members (optionally filter by admin)
-  grok s groups list-memberships <group> [--admin]    List parent groups
+  grok s groups list-members <group> [--admin] [--user]
+                                                      List members (optionally filter by admin; --user: personal group)
+  grok s groups list-memberships <group> [--admin] [--user]
+                                                      List parent groups
   grok s users block <id-or-login>                    Block a user from the platform
   grok s users unblock <id-or-login>                  Unblock a previously blocked user
   grok s tables upload <name> <file.csv|file.d42>     Upload a CSV or d42 binary as a Datagrok table
-  grok s tables download <name-or-id> [-O <file>]     Download a table as CSV (stdout by default)
+  grok s tables download <name|Project:Table|id> [-O <file>]
+                                                      Download a table as CSV (stdout by default)
   grok s packages install <name>... [--version <v>]   Install latest (or pinned) versions from the registry
   grok s packages uninstall <name>                    Uninstall a package (repository entry is kept)
   grok s packages update <name>... | --all            Upgrade to the latest registry version
@@ -919,6 +978,30 @@ Special commands:
   grok s packages set-version <name> <version>        Activate a specific published version
   grok s packages share <name> <group>[,...] [--access View|Edit]
                                                       Share a package with one or more groups
+  grok s pull [<nqName|id>...] --out <dir>            Export entities into a bundle directory
+  grok s push <bundle-dir> [--dry-run]                Import a bundle into the target server
+  grok s migrate <selection> --from <a> --to <b>      Pull from one instance and push into another
+  grok s diff <bundle-dir>                            What a push would change (read-only, plans with skip)
+  grok s bundle ls <bundle-dir>                       List what a bundle contains
+  grok s domains list [<schema>] [--filter <text>]    Domain schemas, or the tables of one schema
+  grok s domains get <schema>|<schema.table> [<id>]   Manifest, a table's columns, or one row
+  grok s domains query <schema.table> [--filter <expr>] [--columns a,b] [--sort 'a,!b'] [--expand x] [--limit n] [--offset n]
+  grok s domains count <schema.table> [--filter <expr>]
+  grok s domains insert <schema.table> --json rows.json | col=value ... [--error-on-duplicate]
+  grok s domains update <schema.table> <id> --json values.json | col=value ... [--version n]
+  grok s domains delete <schema.table> <id> | --filter <expr> [--limit n]
+  grok s domains delete <schema> --force              Purge a user-managed schema with its data
+  grok s domains upload <schema.table> <file.csv|.d42|.json> [--upsert] [--no-all-or-nothing] [--error-on-duplicate]
+  grok s domains download <schema.table> [-O out.csv|out.d42] [--filter <expr>] [--columns a,b] [--sort s]
+  grok s domains aggregate <schema.table> --measures 'count,sum(x) as t' [--group-by a,b] [--filter <expr>]
+  grok s domains transaction <schema> --json ops.json  Ordered insert/update/delete ops, atomically
+  grok s domains audit <schema>|<schema.table> [<id>] [--limit n]
+  grok s domains capabilities <schema.table>          What the current user may do on the table
+  grok s domains grants <schema>|<schema.table>       Direct permission grants on a schema or table
+  grok s domains grant <schema>|<schema.table> <group>[,...] [--access View|Edit|Delete|Share|Extend]
+  grok s domains revoke <schema>|<schema.table> <group>[,...] [--access <permission>]
+  grok s domains create <name> [--friendly-name <t>] [--description <t>]
+  grok s domains apply <schema> --json manifest.json [--dry-run] [--confirm-destructive] [--if-version <v>]
   grok s batch <entity> <verb> arg1 [arg2 ...]        Batch operation (one round-trip)
   grok s batch <entity> <verb> --json params.json     Batch from JSON array
   grok s batch manifest.json                          Run a workflow manifest
@@ -927,14 +1010,47 @@ Special commands:
   grok s sync setup get <setup-id>                    Inspect a setup (selections, direction, last run)
   grok s sync run <setup-id>                          Trigger a push run; prints per-item outcome
 
+Pull / push / migrate options:
+  --out <dir>           Bundle directory to write (pull; merges into an existing bundle)
+  --type <t,t>          conn, query, script, project, dashboard, space, view, layout, table,
+                        file, group, job, notebook, model
+  --name <glob>         Entity name glob: 'Cereal*' matches by prefix, '*demo*' anywhere
+  --namespace <ns>      Everything under a namespace, recursively
+  --space <nqName>      The space itself plus everything under it
+  --author <login>      Entities authored by a login
+  --tag <tag>           Entities carrying a tag
+  --since <2w|date>     Entities updated since ('2w' means '-2w'; also --since=-2w)
+  --filter <expr>       Smart-filter expression ANDed with the other flags
+  --no-deps             Do not follow dependencies (never-travels rules still apply)
+  --no-include-data     Do not pull table data (.d42) for pulled tables
+  --include-files       Also pull the bytes of pulled files
+  --replace             Clear the bundle directory before writing
+  --dry-run             Push: print the plan and stop
+  --on-conflict <p>     Push: what to do when the name is taken on the target by another id —
+                        fail (default) aborts before any write, skip leaves the target alone
+                        (and fails whatever depends on it), adopt writes into the twin and
+                        records idmap.json, duplicate creates the bundle entity under its own
+                        id next to the twin (a UserGroup cannot be duplicated — group names
+                        are unique, so that row fails)
+  --creds <file.yaml>   Push: target-side connection secrets, 'Ns:Conn:' then '  password: \${VAR}'
+                        (a covered connection is always written, so a push rotates the secret)
+  --from <alias|url>    Migrate: source instance (pulled from, never written to)
+  --to <alias|url>      Migrate: target instance
+  --keep                Migrate: keep the temporary bundle and print its path on stderr
+
 Options:
   --host <alias|url>    Server alias from config or full URL
+  --admin               Ask the server for an admin session, so the run sees entities the key's
+                        own account cannot (other people's spaces). Refused unless the account
+                        may start one; lasts for this command only
   --output <format>     Output format: table (default), json, csv, quiet
   --filter <text>       Smart filter expression
   --limit <n>           Page size (default: 50)
   --offset <n>          Start offset (default: 0)
   -r, --recursive       Recursive (for files list)
-  --json <file>         Read function parameters or batch params from JSON file
+  --verbose             Print the stack of a runtime failure, not just its message
+  --json <file>         Read a JSON body from a file (save, functions run, batch, raw)
+  --data '<json>'       Inline JSON body for raw
   -O, --output-file     Write table download to a file instead of stdout
   --type <t>            Function discriminator: script | query | function | package
   --language <lang>     Script language: python, r, julia, nodejs, octave, grok
@@ -950,6 +1066,7 @@ Batch manifest options (in manifest.json):
 Examples:
   grok s users list
   grok s users list --output json --limit 10
+  grok s users count --filter 'status = "active"'
   grok s users save --json user.json
   grok s groups save --json group.json --save-relations
   grok s shares add "JohnDoe:MyConnection" Chemists,Admins --access Edit
@@ -972,14 +1089,33 @@ Examples:
   grok s packages update --all
   grok s packages versions Chem
   grok s packages share Chem Chemists --access View
-  grok s raw GET /api/users/current
+  grok s raw GET /users/current
+  grok s raw POST /public/v1/functions/Sin/call --data '{"x": 1}'
   grok s describe connections
+  grok s tables download MyTable -O ./my-table.csv
   grok s users list --host dev
   grok s users list --host "https://mygrok.com/api"
   grok s groups add-members Admins alice bob --admin
   grok s groups remove-members Admins alice
   grok s groups list-members Admins --admin
   grok s groups list-memberships alice
+  grok s pull Admin:CerealDemog --out ./bundle --host dev
+  grok s pull Chemists --out ./bundle --host dev
+  grok s pull --type script --author alice --no-deps --out ./bundle
+  grok s bundle ls ./bundle
+  grok s push ./bundle --host local --dry-run
+  grok s push ./bundle --host local --on-conflict adopt
+  grok s pull --type space --namespace MySpace --include-files --out ./bundle
+  grok s push ./bundle --host prod --creds ./creds.yaml
+  grok s migrate Chem:TargetDashboard --from dev --to prod --dry-run
+  grok s diff ./bundle --host local
+  grok s domains list
+  grok s domains get grit.issue
+  grok s domains query grit.issue --filter 'status = "open"' --sort '!created_on' --limit 20
+  grok s domains insert grit.issue title="Crash on save" status=open
+  grok s domains upload grit.issue ./issues.csv --upsert
+  grok s domains download grit.issue -O ./issues.csv
+  grok s domains grant grit.issue Chemists --access Edit
   grok s batch files delete "System:AppData/old.txt" "System:DemoFiles/tmp.txt"
   grok s batch users create --json users.json
   grok s batch manifest.json

package/bin/grok.js

@@ -36,6 +36,14 @@ const commands = {
 
 const onPackageCommandNames = ['api', 'check', 'link', 'publish', 'test'];
 
+// A machine-readable run prints its error as JSON on stderr (server.ts) and nothing else:
+// a usage dump on stdout would corrupt the output the caller parses.
+const outputFormat = argv.output ?? argv.o;
+function printUsage(command) {
+  if (outputFormat !== 'json')
+    process.stderr.write(`${help[command]}\n`);
+}
+
 const command = argv['_'][0];
 if (command !== 'test' && command !== 'stresstest')
   delete argv.dartium;
@@ -52,23 +60,23 @@ if (command in commands) {
       if (result && typeof result.then === 'function') {
         result.then((ok) => {
           if (!ok) {
-            console.log(help[command]);
+            printUsage(command);
             exitWithCode(1);
           }
         }).catch((err) => {
           console.error(err);
-          console.log(help[command]);
+          printUsage(command);
           exitWithCode(255);
         });
       }
       else if (!result) {
-        console.log(help[command]);
+        printUsage(command);
         exitWithCode(1);
       }
     }
   } catch (err) {
     console.error(err);
-    console.log(help[command]);
+    printUsage(command);
     exitWithCode(255);
   }
 } else
@@ -76,6 +84,7 @@ if (command in commands) {
 
 
 function exitWithCode(code) {
-  console.log(`Exiting with code ${code}`);
+  if (outputFormat !== 'json')
+    console.log(`Exiting with code ${code}`);
   process.exit(code);
 }