@geolonia/geonicdb-cli 0.6.1 → 0.6.3

package/dist/index.js

@@ -303,9 +303,13 @@ function entityToFeature(entity) {
 // src/commands/help.ts
 import chalk2 from "chalk";
 var examplesMap = /* @__PURE__ */ new WeakMap();
+var notesMap = /* @__PURE__ */ new WeakMap();
 function addExamples(cmd, examples) {
   examplesMap.set(cmd, examples);
 }
+function addNotes(cmd, notes) {
+  notesMap.set(cmd, notes);
+}
 function header(title) {
   return chalk2.yellow.bold(title);
 }
@@ -451,6 +455,15 @@ function formatCommandDetails(program2, cmd, path) {
       lines.push("");
     }
   }
+  const notes = notesMap.get(cmd);
+  if (notes && notes.length > 0) {
+    lines.push("");
+    lines.push(header("NOTES"));
+    lines.push("");
+    for (const note of notes) {
+      lines.push(`  ${note}`);
+    }
+  }
   lines.push("");
   lines.push(formatGlobalParameters(program2));
   return lines.join("\n");
@@ -924,6 +937,16 @@ var GdbClientError = class extends Error {
 };
 
 // src/helpers.ts
+var SCOPES_HELP_NOTES = [
+  "Valid scopes:",
+  "  read:entities, write:entities, read:subscriptions, write:subscriptions,",
+  "  read:registrations, write:registrations, read:rules, write:rules,",
+  "  read:custom-data-models, write:custom-data-models,",
+  "  admin:users, admin:tenants, admin:policies, admin:oauth-clients,",
+  "  admin:api-keys, admin:metrics",
+  "",
+  "write:X implies read:X. admin:X implies both read:X and write:X."
+];
 function resolveOptions(cmd) {
   const opts = cmd.optsWithGlobals();
   const config = loadConfig(opts.profile);
@@ -1348,6 +1371,7 @@ function addMeOAuthClientsSubcommand(me) {
       printSuccess("OAuth client created.");
     })
   );
+  addNotes(create, SCOPES_HELP_NOTES);
   addExamples(create, [
     {
       description: "Create an OAuth client with flags",
@@ -1465,6 +1489,7 @@ function addMeApiKeysSubcommand(me) {
       console.error("API key created.");
     })
   );
+  addNotes(create, SCOPES_HELP_NOTES);
   addExamples(create, [
     {
       description: "Create an API key with flags",
@@ -1969,7 +1994,9 @@ function addAttrsSubcommands(attrs) {
       command: "geonic entities attrs get urn:ngsi-ld:Sensor:001 temperature"
     }
   ]);
-  const add = attrs.command("add").description("Add attributes to an entity").argument("<entityId>", "Entity ID").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
+  const add = attrs.command("add").description(
+    'Add attributes to an entity\n\nJSON payload example:\n  {"humidity": {"type": "Property", "value": 60}}'
+  ).argument("<entityId>", "Entity ID").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
     withErrorHandler(
       async (entityId, json, _opts, cmd) => {
         const client = createClient(cmd);
@@ -1983,12 +2010,22 @@ function addAttrsSubcommands(attrs) {
     )
   );
   addExamples(add, [
+    {
+      description: "Add an attribute with inline JSON",
+      command: `geonic entities attrs add urn:ngsi-ld:Sensor:001 '{"humidity":{"type":"Property","value":60}}'`
+    },
     {
       description: "Add attributes from a file",
       command: "geonic entities attrs add urn:ngsi-ld:Sensor:001 @attrs.json"
+    },
+    {
+      description: "Add from stdin pipe",
+      command: "cat attrs.json | geonic entities attrs add urn:ngsi-ld:Sensor:001"
     }
   ]);
-  const attrUpdate = attrs.command("update").description("Update a specific attribute of an entity").argument("<entityId>", "Entity ID").argument("<attrName>", "Attribute name").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
+  const attrUpdate = attrs.command("update").description(
+    'Update a specific attribute of an entity\n\nJSON payload example:\n  {"type": "Property", "value": 25}'
+  ).argument("<entityId>", "Entity ID").argument("<attrName>", "Attribute name").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
     withErrorHandler(
       async (entityId, attrName, json, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2003,8 +2040,12 @@ function addAttrsSubcommands(attrs) {
   );
   addExamples(attrUpdate, [
     {
-      description: "Update a specific attribute",
-      command: `geonic entities attrs update urn:ngsi-ld:Sensor:001 temperature '{"value":25}'`
+      description: "Update a Property value",
+      command: `geonic entities attrs update urn:ngsi-ld:Sensor:001 temperature '{"type":"Property","value":25}'`
+    },
+    {
+      description: "Update from a file",
+      command: "geonic entities attrs update urn:ngsi-ld:Sensor:001 temperature @attr.json"
     }
   ]);
   const del = attrs.command("delete").description("Delete a specific attribute from an entity").argument("<entityId>", "Entity ID").argument("<attrName>", "Attribute name").action(
@@ -2147,7 +2188,9 @@ function registerEntitiesCommand(program2) {
       command: "geonic entities get urn:ngsi-ld:Sensor:001 --key-values"
     }
   ]);
-  const create = entities.command("create").description("Create a new entity").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
+  const create = entities.command("create").description(
+    'Create a new entity\n\nJSON payload example:\n  {\n    "id": "urn:ngsi-ld:Sensor:001",\n    "type": "Sensor",\n    "temperature": {"type": "Property", "value": 25}\n  }'
+  ).argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const data = await parseJsonInput(json);
@@ -2157,9 +2200,13 @@ function registerEntitiesCommand(program2) {
   );
   addExamples(create, [
     {
-      description: "Create from inline JSON",
+      description: "Create from inline JSON (minimal)",
       command: `geonic entities create '{"id":"urn:ngsi-ld:Sensor:001","type":"Sensor"}'`
     },
+    {
+      description: "Create with attributes",
+      command: `geonic entities create '{"id":"urn:ngsi-ld:Sensor:001","type":"Sensor","temperature":{"type":"Property","value":25},"location":{"type":"GeoProperty","value":{"type":"Point","coordinates":[139.77,35.68]}}}'`
+    },
     {
       description: "Create from a file",
       command: "geonic entities create @entity.json"
@@ -2167,9 +2214,15 @@ function registerEntitiesCommand(program2) {
     {
       description: "Create from stdin pipe",
       command: "cat entity.json | geonic entities create"
+    },
+    {
+      description: "Interactive mode (omit JSON argument)",
+      command: "geonic entities create"
     }
   ]);
-  const update = entities.command("update").description("Update attributes of an entity (PATCH)").argument("<id>", "Entity ID").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
+  const update = entities.command("update").description(
+    'Update attributes of an entity (PATCH)\n\nJSON payload: only specified attributes are modified.\n  e.g. {"temperature": {"type": "Property", "value": 30}}'
+  ).argument("<id>", "Entity ID").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2184,15 +2237,21 @@ function registerEntitiesCommand(program2) {
   );
   addExamples(update, [
     {
-      description: "Update entity attributes from inline JSON",
-      command: `geonic entities update urn:ngsi-ld:Sensor:001 '{"temperature":{"value":25}}'`
+      description: "Update a Property attribute",
+      command: `geonic entities update urn:ngsi-ld:Sensor:001 '{"temperature":{"type":"Property","value":30}}'`
     },
     {
-      description: "Update entity attributes from a file",
+      description: "Update from a file",
       command: "geonic entities update urn:ngsi-ld:Sensor:001 @attrs.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat attrs.json | geonic entities update urn:ngsi-ld:Sensor:001"
     }
   ]);
-  const replace = entities.command("replace").description("Replace all attributes of an entity (PUT)").argument("<id>", "Entity ID").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
+  const replace = entities.command("replace").description(
+    'Replace all attributes of an entity (PUT)\n\nJSON payload: all existing attributes are replaced.\n  e.g. {"temperature": {"type": "Property", "value": 20}}'
+  ).argument("<id>", "Entity ID").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2207,8 +2266,16 @@ function registerEntitiesCommand(program2) {
   );
   addExamples(replace, [
     {
-      description: "Replace all attributes from a file",
+      description: "Replace all attributes with inline JSON",
+      command: `geonic entities replace urn:ngsi-ld:Sensor:001 '{"temperature":{"type":"Property","value":20}}'`
+    },
+    {
+      description: "Replace from a file",
       command: "geonic entities replace urn:ngsi-ld:Sensor:001 @attrs.json"
+    },
+    {
+      description: "Replace from stdin pipe",
+      command: "cat attrs.json | geonic entities replace urn:ngsi-ld:Sensor:001"
     }
   ]);
   const upsert = entities.command("upsert").description("Create or update entities").argument("[json]", "JSON payload (inline, @file, - for stdin, or omit for interactive/pipe)").action(
@@ -2248,7 +2315,9 @@ function registerEntitiesCommand(program2) {
 // src/commands/batch.ts
 function registerBatchCommand(program2) {
   const batch = program2.command("entityOperations").alias("batch").description("Perform batch operations on entities");
-  const create = batch.command("create [json]").description("Batch create entities").action(
+  const create = batch.command("create [json]").description(
+    'Batch create entities\n\nJSON payload: an array of NGSI-LD entities.\n  e.g. [{"id": "urn:ngsi-ld:Sensor:001", "type": "Sensor"}, ...]'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2258,16 +2327,22 @@ function registerBatchCommand(program2) {
     })
   );
   addExamples(create, [
+    {
+      description: "Batch create with inline JSON",
+      command: `geonic batch create '[{"id":"urn:ngsi-ld:Sensor:001","type":"Sensor"},{"id":"urn:ngsi-ld:Sensor:002","type":"Sensor"}]'`
+    },
     {
       description: "Batch create from a file",
       command: "geonic batch create @entities.json"
     },
     {
-      description: "Batch create from stdin",
+      description: "Batch create from stdin pipe",
       command: "cat entities.json | geonic batch create"
     }
   ]);
-  const upsert = batch.command("upsert [json]").description("Batch upsert entities").action(
+  const upsert = batch.command("upsert [json]").description(
+    "Batch upsert entities\n\nJSON payload: an array of NGSI-LD entities.\nCreates entities that don't exist, updates those that do."
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2277,16 +2352,22 @@ function registerBatchCommand(program2) {
     })
   );
   addExamples(upsert, [
+    {
+      description: "Batch upsert with inline JSON",
+      command: `geonic batch upsert '[{"id":"urn:ngsi-ld:Sensor:001","type":"Sensor","temperature":{"type":"Property","value":25}}]'`
+    },
     {
       description: "Batch upsert from a file",
       command: "geonic batch upsert @entities.json"
     },
     {
-      description: "Batch upsert from stdin",
+      description: "Batch upsert from stdin pipe",
       command: "cat entities.json | geonic batch upsert"
     }
   ]);
-  const update = batch.command("update [json]").description("Batch update entity attributes").action(
+  const update = batch.command("update [json]").description(
+    "Batch update entity attributes\n\nJSON payload: an array of NGSI-LD entities with attributes to update.\nEach entity must include id and type; only specified attributes are modified."
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2305,7 +2386,9 @@ function registerBatchCommand(program2) {
       command: "cat updates.json | geonic batch update"
     }
   ]);
-  const del = batch.command("delete [json]").description("Batch delete entities by ID").action(
+  const del = batch.command("delete [json]").description(
+    'Batch delete entities by ID\n\nJSON payload: an array of entity ID strings.\n  e.g. ["urn:ngsi-ld:Sensor:001","urn:ngsi-ld:Sensor:002"]'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2315,16 +2398,22 @@ function registerBatchCommand(program2) {
     })
   );
   addExamples(del, [
+    {
+      description: "Batch delete with inline JSON",
+      command: `geonic batch delete '["urn:ngsi-ld:Sensor:001","urn:ngsi-ld:Sensor:002"]'`
+    },
     {
       description: "Batch delete from a file",
       command: "geonic batch delete @entity-ids.json"
     },
     {
-      description: "Batch delete from stdin",
+      description: "Batch delete from stdin pipe",
       command: "cat entity-ids.json | geonic batch delete"
     }
   ]);
-  const query = batch.command("query [json]").description("Query entities by posting a query payload").action(
+  const query = batch.command("query [json]").description(
+    'Query entities by posting a query payload\n\nJSON payload example:\n  {\n    "entities": [{"type": "Sensor"}],\n    "attrs": ["temperature"],\n    "q": "temperature>30"\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2335,15 +2424,21 @@ function registerBatchCommand(program2) {
   );
   addExamples(query, [
     {
-      description: "Query entities from a file",
+      description: "Query with inline JSON",
+      command: `geonic batch query '{"entities":[{"type":"Sensor"}],"attrs":["temperature"]}'`
+    },
+    {
+      description: "Query from a file",
       command: "geonic batch query @query.json"
     },
     {
-      description: "Query entities from stdin",
+      description: "Query from stdin pipe",
       command: "cat query.json | geonic batch query"
     }
   ]);
-  const merge = batch.command("merge [json]").description("Batch merge-patch entities").action(
+  const merge = batch.command("merge [json]").description(
+    "Batch merge-patch entities\n\nJSON payload: an array of NGSI-LD entities.\nEach entity must include id and type; attributes are merge-patched."
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2410,7 +2505,9 @@ function registerSubscriptionsCommand(program2) {
       command: "geonic subscriptions get urn:ngsi-ld:Subscription:001"
     }
   ]);
-  const create = subscriptions.command("create [json]").description("Create a subscription").action(
+  const create = subscriptions.command("create [json]").description(
+    'Create a subscription\n\nJSON payload example:\n  {\n    "type": "Subscription",\n    "entities": [{"type": "Sensor"}],\n    "watchedAttributes": ["temperature"],\n    "notification": {"endpoint": {"uri": "http://localhost:3000/notify"}}\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2421,16 +2518,26 @@ function registerSubscriptionsCommand(program2) {
     })
   );
   addExamples(create, [
+    {
+      description: "Create with inline JSON",
+      command: `geonic subscriptions create '{"type":"Subscription","entities":[{"type":"Sensor"}],"watchedAttributes":["temperature"],"notification":{"endpoint":{"uri":"http://localhost:3000/notify"}}}'`
+    },
     {
       description: "Create from a JSON file",
       command: "geonic subscriptions create @subscription.json"
     },
     {
-      description: "Create from stdin",
+      description: "Create from stdin pipe",
       command: "cat subscription.json | geonic subscriptions create"
+    },
+    {
+      description: "Interactive mode",
+      command: "geonic subscriptions create"
     }
   ]);
-  const update = subscriptions.command("update <id> [json]").description("Update a subscription").action(
+  const update = subscriptions.command("update <id> [json]").description(
+    'Update a subscription\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated subscription"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2447,8 +2554,16 @@ function registerSubscriptionsCommand(program2) {
   );
   addExamples(update, [
     {
-      description: "Update a subscription from a file",
+      description: "Update description",
+      command: `geonic subscriptions update urn:ngsi-ld:Subscription:001 '{"description":"Updated subscription"}'`
+    },
+    {
+      description: "Update from a file",
       command: "geonic subscriptions update urn:ngsi-ld:Subscription:001 @sub.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat sub.json | geonic subscriptions update urn:ngsi-ld:Subscription:001"
     }
   ]);
   const del = subscriptions.command("delete <id>").description("Delete a subscription").action(
@@ -2510,7 +2625,9 @@ function registerRegistrationsCommand(program2) {
       command: "geonic registrations get urn:ngsi-ld:ContextSourceRegistration:001"
     }
   ]);
-  const create = registrations.command("create [json]").description("Create a registration").action(
+  const create = registrations.command("create [json]").description(
+    'Create a registration\n\nJSON payload example:\n  {\n    "type": "ContextSourceRegistration",\n    "information": [{"entities": [{"type": "Room"}]}],\n    "endpoint": "http://localhost:4000/source"\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2522,8 +2639,16 @@ function registerRegistrationsCommand(program2) {
   );
   addExamples(create, [
     {
-      description: "Create a registration from a file",
+      description: "Create with inline JSON",
+      command: `geonic registrations create '{"type":"ContextSourceRegistration","information":[{"entities":[{"type":"Room"}]}],"endpoint":"http://localhost:4000/source"}'`
+    },
+    {
+      description: "Create from a file",
       command: "geonic registrations create @registration.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat registration.json | geonic registrations create"
     }
   ]);
   const regUpdate = registrations.command("update <id> [json]").description("Update a registration").action(
@@ -2543,8 +2668,16 @@ function registerRegistrationsCommand(program2) {
   );
   addExamples(regUpdate, [
     {
-      description: "Update a registration from a file",
+      description: "Update endpoint",
+      command: `geonic registrations update urn:ngsi-ld:ContextSourceRegistration:001 '{"endpoint":"http://localhost:5000/source"}'`
+    },
+    {
+      description: "Update from a file",
       command: "geonic registrations update urn:ngsi-ld:ContextSourceRegistration:001 @registration.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat registration.json | geonic registrations update urn:ngsi-ld:ContextSourceRegistration:001"
     }
   ]);
   const del = registrations.command("delete <id>").description("Delete a registration").action(
@@ -2722,11 +2855,21 @@ function registerTemporalCommand(program2) {
       command: "geonic temporal entities get urn:ngsi-ld:Sensor:001 --last-n 10"
     }
   ]);
-  const create = entities.command("create [json]").description("Create a temporal entity").action(createCreateAction());
+  const create = entities.command("create [json]").description(
+    "Create a temporal entity\n\nJSON payload: an NGSI-LD entity with temporal attribute instances.\nEach attribute value is an array of {value, observedAt} objects."
+  ).action(createCreateAction());
   addExamples(create, [
     {
-      description: "Create temporal entity from a file",
+      description: "Create from a file",
       command: "geonic temporal entities create @temporal-entity.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat temporal-entity.json | geonic temporal entities create"
+    },
+    {
+      description: "Interactive mode",
+      command: "geonic temporal entities create"
     }
   ]);
   const del = entities.command("delete <id>").description("Delete a temporal entity by ID").action(createDeleteAction());
@@ -2741,6 +2884,10 @@ function registerTemporalCommand(program2) {
   );
   opsQuery.action(createQueryAction());
   addExamples(opsQuery, [
+    {
+      description: "Query with inline JSON",
+      command: `geonic temporal entityOperations query '{"entities":[{"type":"Sensor"}],"attrs":["temperature"]}'`
+    },
     {
       description: "Query with aggregation (hourly count)",
       command: "geonic temporal entityOperations query @query.json --aggr-methods totalCount --aggr-period PT1H"
@@ -2888,7 +3035,9 @@ function registerTenantsCommand(parent) {
       command: "geonic admin tenants get <tenant-id>"
     }
   ]);
-  const create = tenants.command("create [json]").description("Create a new tenant").action(
+  const create = tenants.command("create [json]").description(
+    'Create a new tenant\n\nJSON payload example:\n  {\n    "name": "production",\n    "description": "Production environment tenant"\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -2902,11 +3051,29 @@ function registerTenantsCommand(parent) {
   );
   addExamples(create, [
     {
-      description: "Create a tenant from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin tenants create '{"name":"my-tenant","description":"My first tenant"}'`
+    },
+    {
+      description: "Minimal (name only)",
+      command: `geonic admin tenants create '{"name":"production"}'`
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin tenants create @tenant.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat tenant.json | geonic admin tenants create"
+    },
+    {
+      description: "Interactive mode (omit JSON argument)",
+      command: "geonic admin tenants create"
     }
   ]);
-  const update = tenants.command("update <id> [json]").description("Update a tenant").action(
+  const update = tenants.command("update <id> [json]").description(
+    'Update a tenant\n\nJSON payload: only specified fields are updated.\n  e.g. {"name": "new-name", "description": "Updated description"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const body = await parseJsonInput(json);
@@ -2924,8 +3091,24 @@ function registerTenantsCommand(parent) {
   );
   addExamples(update, [
     {
-      description: "Update a tenant from a JSON file",
-      command: "geonic admin tenants update <tenant-id> @tenant.json"
+      description: "Update description with inline JSON",
+      command: `geonic admin tenants update <tenant-id> '{"description":"Updated description"}'`
+    },
+    {
+      description: "Rename a tenant",
+      command: `geonic admin tenants update <tenant-id> '{"name":"new-name"}'`
+    },
+    {
+      description: "Update from a JSON file",
+      command: "geonic admin tenants update <tenant-id> @patch.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat patch.json | geonic admin tenants update <tenant-id>"
+    },
+    {
+      description: "Interactive mode",
+      command: "geonic admin tenants update <tenant-id>"
     }
   ]);
   const del = tenants.command("delete <id>").description("Delete a tenant").action(
@@ -3012,7 +3195,9 @@ function registerUsersCommand(parent) {
       command: "geonic admin users get <user-id>"
     }
   ]);
-  const create = users.command("create [json]").description("Create a new user").action(
+  const create = users.command("create [json]").description(
+    'Create a new user\n\nJSON payload example:\n  {\n    "email": "user@example.com",\n    "password": "SecurePassword123!",\n    "role": "super_admin"\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -3026,11 +3211,21 @@ function registerUsersCommand(parent) {
   );
   addExamples(create, [
     {
-      description: "Create a user from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin users create '{"email":"user@example.com","password":"SecurePassword123!","role":"super_admin"}'`
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin users create @user.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat user.json | geonic admin users create"
     }
   ]);
-  const update = users.command("update <id> [json]").description("Update a user").action(
+  const update = users.command("update <id> [json]").description(
+    'Update a user\n\nJSON payload: only specified fields are updated.\n  e.g. {"role": "admin"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const body = await parseJsonInput(json);
@@ -3048,8 +3243,16 @@ function registerUsersCommand(parent) {
   );
   addExamples(update, [
     {
-      description: "Update a user from a JSON file",
+      description: "Update role with inline JSON",
+      command: `geonic admin users update <user-id> '{"role":"admin"}'`
+    },
+    {
+      description: "Update from a JSON file",
       command: "geonic admin users update <user-id> @user.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat user.json | geonic admin users update <user-id>"
     }
   ]);
   const del = users.command("delete <id>").description("Delete a user").action(
@@ -3152,7 +3355,9 @@ function registerPoliciesCommand(parent) {
       command: "geonic admin policies get <policy-id>"
     }
   ]);
-  const create = policies.command("create [json]").description("Create a new policy").action(
+  const create = policies.command("create [json]").description(
+    'Create a new policy\n\nJSON payload example:\n  {\n    "description": "Allow all entities",\n    "rules": [{"ruleId": "allow-all", "effect": "Permit"}]\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -3166,11 +3371,21 @@ function registerPoliciesCommand(parent) {
   );
   addExamples(create, [
     {
-      description: "Create a policy from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin policies create '{"description":"Allow all entities","rules":[{"ruleId":"allow-all","effect":"Permit"}]}'`
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin policies create @policy.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat policy.json | geonic admin policies create"
     }
   ]);
-  const update = policies.command("update <id> [json]").description("Update a policy").action(
+  const update = policies.command("update <id> [json]").description(
+    'Update a policy\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated policy"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const body = await parseJsonInput(json);
@@ -3188,8 +3403,16 @@ function registerPoliciesCommand(parent) {
   );
   addExamples(update, [
     {
-      description: "Update a policy from a JSON file",
+      description: "Update description",
+      command: `geonic admin policies update <policy-id> '{"description":"Updated policy"}'`
+    },
+    {
+      description: "Update from a JSON file",
       command: "geonic admin policies update <policy-id> @policy.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat policy.json | geonic admin policies update <policy-id>"
     }
   ]);
   const del = policies.command("delete <id>").description("Delete a policy").action(
@@ -3276,7 +3499,9 @@ function registerOAuthClientsCommand(parent) {
       command: "geonic admin oauth-clients get <client-id>"
     }
   ]);
-  const create = oauthClients.command("create [json]").description("Create a new OAuth client").action(
+  const create = oauthClients.command("create [json]").description(
+    'Create a new OAuth client\n\nJSON payload example:\n  {\n    "clientName": "my-app",\n    "allowedScopes": ["read:entities", "write:entities"]\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -3290,11 +3515,21 @@ function registerOAuthClientsCommand(parent) {
   );
   addExamples(create, [
     {
-      description: "Create an OAuth client from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin oauth-clients create '{"clientName":"my-app","allowedScopes":["read:entities","write:entities"]}'`
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin oauth-clients create @client.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat client.json | geonic admin oauth-clients create"
     }
   ]);
-  const update = oauthClients.command("update <id> [json]").description("Update an OAuth client").action(
+  const update = oauthClients.command("update <id> [json]").description(
+    'Update an OAuth client\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated client"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const body = await parseJsonInput(json);
@@ -3312,8 +3547,16 @@ function registerOAuthClientsCommand(parent) {
   );
   addExamples(update, [
     {
-      description: "Update an OAuth client from a JSON file",
+      description: "Update description",
+      command: `geonic admin oauth-clients update <client-id> '{"description":"Updated client"}'`
+    },
+    {
+      description: "Update from a JSON file",
       command: "geonic admin oauth-clients update <client-id> @client.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat client.json | geonic admin oauth-clients update <client-id>"
     }
   ]);
   const del = oauthClients.command("delete <id>").description("Delete an OAuth client").action(
@@ -3349,7 +3592,9 @@ function registerCaddeCommand(parent) {
       command: "geonic admin cadde get"
     }
   ]);
-  const caddeSet = cadde.command("set [json]").description("Set CADDE configuration").action(
+  const caddeSet = cadde.command("set [json]").description(
+    'Set CADDE configuration\n\nJSON payload example:\n  {\n    "provider": "my-provider",\n    "endpoint": "http://localhost:6000"\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -3363,8 +3608,16 @@ function registerCaddeCommand(parent) {
   );
   addExamples(caddeSet, [
     {
-      description: "Set CADDE configuration from a JSON file",
+      description: "Set with inline JSON",
+      command: `geonic admin cadde set '{"provider":"my-provider","endpoint":"http://localhost:6000"}'`
+    },
+    {
+      description: "Set from a JSON file",
       command: "geonic admin cadde set @cadde-config.json"
+    },
+    {
+      description: "Set from stdin pipe",
+      command: "cat cadde-config.json | geonic admin cadde set"
     }
   ]);
   const caddeDelete = cadde.command("delete").description("Delete CADDE configuration").action(
@@ -3503,10 +3756,11 @@ function registerApiKeysCommand(parent) {
       console.error("API key created.");
     })
   );
+  addNotes(create, SCOPES_HELP_NOTES);
   addExamples(create, [
     {
       description: "Create an API key with flags",
-      command: "geonic admin api-keys create --name my-key --scopes entities:read,entities:write --origins '*'"
+      command: "geonic admin api-keys create --name my-key --scopes read:entities,write:entities --origins '*'"
     },
     {
       description: "Create an API key with DPoP required",
@@ -3543,6 +3797,7 @@ function registerApiKeysCommand(parent) {
       }
     )
   );
+  addNotes(update, SCOPES_HELP_NOTES);
   addExamples(update, [
     {
       description: "Update an API key name",
@@ -3624,7 +3879,9 @@ function registerRulesCommand(program2) {
       command: "geonic rules get <rule-id>"
     }
   ]);
-  const create = rules.command("create [json]").description("Create a new rule").action(
+  const create = rules.command("create [json]").description(
+    'Create a new rule\n\nJSON payload example:\n  {\n    "name": "high-temp-alert",\n    "description": "Alert on high temperature",\n    "conditions": [{"type": "celExpression", "expression": "entity.temperature > 30"}],\n    "actions": [{"type": "webhook", "url": "http://localhost:5000/alert", "method": "POST"}]\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -3636,11 +3893,21 @@ function registerRulesCommand(program2) {
   );
   addExamples(create, [
     {
-      description: "Create a rule from a file",
+      description: "Create with inline JSON",
+      command: `geonic rules create '{"name":"high-temp-alert","conditions":[{"type":"celExpression","expression":"entity.temperature > 30"}],"actions":[{"type":"webhook","url":"http://localhost:5000/alert","method":"POST"}]}'`
+    },
+    {
+      description: "Create from a file",
       command: "geonic rules create @rule.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat rule.json | geonic rules create"
     }
   ]);
-  const update = rules.command("update <id> [json]").description("Update a rule").action(
+  const update = rules.command("update <id> [json]").description(
+    'Update a rule\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated rule"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const body = await parseJsonInput(json);
@@ -3658,8 +3925,16 @@ function registerRulesCommand(program2) {
   );
   addExamples(update, [
     {
-      description: "Update a rule from a file",
+      description: "Update description",
+      command: `geonic rules update <rule-id> '{"description":"Updated rule"}'`
+    },
+    {
+      description: "Update from a file",
       command: "geonic rules update <rule-id> @rule.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat rule.json | geonic rules update <rule-id>"
     }
   ]);
   const del = rules.command("delete <id>").description("Delete a rule").action(
@@ -3746,7 +4021,9 @@ function registerModelsCommand(program2) {
       command: "geonic models get <model-id>"
     }
   ]);
-  const create = models.command("create [json]").description("Create a new model").action(
+  const create = models.command("create [json]").description(
+    'Create a new model\n\nJSON payload example:\n  {\n    "type": "Sensor",\n    "domain": "iot",\n    "description": "IoT Sensor",\n    "propertyDetails": {\n      "temperature": {"ngsiType": "Property", "valueType": "Number", "example": 25}\n    }\n  }'
+  ).action(
     withErrorHandler(async (json, _opts, cmd) => {
       const body = await parseJsonInput(json);
       const client = createClient(cmd);
@@ -3758,11 +4035,21 @@ function registerModelsCommand(program2) {
   );
   addExamples(create, [
     {
-      description: "Create a model from a file",
+      description: "Create with inline JSON",
+      command: `geonic models create '{"type":"Sensor","domain":"iot","description":"IoT Sensor","propertyDetails":{"temperature":{"ngsiType":"Property","valueType":"Number","example":25}}}'`
+    },
+    {
+      description: "Create from a file",
       command: "geonic models create @model.json"
+    },
+    {
+      description: "Create from stdin pipe",
+      command: "cat model.json | geonic models create"
     }
   ]);
-  const update = models.command("update <id> [json]").description("Update a model").action(
+  const update = models.command("update <id> [json]").description(
+    'Update a model\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated model"}'
+  ).action(
     withErrorHandler(
       async (id, json, _opts, cmd) => {
         const body = await parseJsonInput(json);
@@ -3780,8 +4067,16 @@ function registerModelsCommand(program2) {
   );
   addExamples(update, [
     {
-      description: "Update a model from a file",
+      description: "Update description",
+      command: `geonic models update <model-id> '{"description":"Updated description"}'`
+    },
+    {
+      description: "Update from a file",
       command: "geonic models update <model-id> @model.json"
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat model.json | geonic models update <model-id>"
     }
   ]);
   const del = models.command("delete <id>").description("Delete a model").action(