@geolonia/geonicdb-cli 0.6.0 → 0.6.2

package/dist/index.js

@@ -848,6 +848,9 @@ var GdbClient = class _GdbClient {
   async executeRawRequest(method, path, options) {
     const url = this.buildUrl(path, options?.params);
     const headers = this.buildHeaders(options?.headers);
+    if (options?.skipTenantHeader) {
+      delete headers["NGSILD-Tenant"];
+    }
     const body = options?.body ? JSON.stringify(options.body) : void 0;
     this.logRequest(method, url, headers, body);
     this.handleDryRun(method, url, headers, body);
@@ -985,7 +988,7 @@ function withErrorHandler(fn) {
         return;
       }
       if (err instanceof GdbClientError && err.status === 401) {
-        printError("Authentication failed. Please run `geonic login` to re-authenticate.");
+        printError("Authentication failed. Please re-authenticate (e.g., `geonic auth login` or check your API key).");
       } else if (err instanceof GdbClientError && err.status === 403) {
         const detail = (err.ngsiError?.detail ?? err.ngsiError?.description ?? "").toLowerCase();
         if (detail.includes("entity type") || detail.includes("allowedentitytypes")) {
@@ -1097,6 +1100,30 @@ async function promptPassword() {
     stdin.on("error", onError);
   });
 }
+async function promptTenantSelection(tenants, currentTenantId) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log("\nAvailable tenants:");
+    for (let i = 0; i < tenants.length; i++) {
+      const t = tenants[i];
+      const current = t.tenantId === currentTenantId ? " \u2190 current" : "";
+      const marker = t.tenantId === currentTenantId ? "  *" : "   ";
+      console.log(`${marker} ${i + 1}) ${t.tenantId} (${t.role})${current}`);
+    }
+    for (; ; ) {
+      const answer = await rl.question("\nSelect tenant number (Enter to keep current): ");
+      const trimmed = answer.trim();
+      if (!trimmed) return void 0;
+      const index = parseInt(trimmed, 10) - 1;
+      if (index >= 0 && index < tenants.length) {
+        return tenants[index].tenantId;
+      }
+      console.log(`Invalid selection. Please enter a number between 1 and ${tenants.length}.`);
+    }
+  } finally {
+    rl.close();
+  }
+}
 
 // src/token.ts
 function decodeJwtPayload(token) {
@@ -1511,32 +1538,59 @@ function createLoginCommand() {
         printSuccess("Login successful (OAuth Client Credentials). Token saved to config.");
         return;
       }
-      let email = process.env.GDB_EMAIL;
-      let password = process.env.GDB_PASSWORD;
-      if (!email || !password) {
-        if (isInteractive()) {
-          if (!email) email = await promptEmail();
-          if (!password) password = await promptPassword();
-        } else {
-          printError(
-            "Set GDB_EMAIL and GDB_PASSWORD environment variables, or run in a terminal for interactive login."
-          );
-          process.exit(1);
-        }
+      if (!globalOpts.url) {
+        printError("No URL configured. Use `geonic config set url <url>` or pass --url.");
+        process.exit(1);
       }
+      try {
+        validateUrl(globalOpts.url);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+      if (!isInteractive()) {
+        printError(
+          "Interactive terminal required. Run `geonic auth login` in a terminal with TTY."
+        );
+        process.exit(1);
+      }
+      const email = await promptEmail();
+      const password = await promptPassword();
       const client = createClient(cmd);
       const body = { email, password };
       if (loginOpts.tenantId) {
         body.tenantId = loginOpts.tenantId;
       }
-      const response = await client.rawRequest("POST", "/auth/login", { body });
+      const response = await client.rawRequest("POST", "/auth/login", {
+        body,
+        skipTenantHeader: true
+      });
       const data = response.data;
-      const token = data.accessToken ?? data.token;
-      const refreshToken = data.refreshToken;
+      let token = data.accessToken ?? data.token;
+      let refreshToken = data.refreshToken;
       if (!token) {
         printError("No token received from server.");
         process.exit(1);
       }
+      const availableTenants = data.availableTenants;
+      const currentTenantId = data.tenantId;
+      if (availableTenants && availableTenants.length > 1 && !loginOpts.tenantId) {
+        const selectedTenantId = await promptTenantSelection(availableTenants, currentTenantId);
+        if (selectedTenantId && selectedTenantId !== currentTenantId) {
+          const reloginResponse = await client.rawRequest("POST", "/auth/login", {
+            body: { email, password, tenantId: selectedTenantId },
+            skipTenantHeader: true
+          });
+          const reloginData = reloginResponse.data;
+          const newToken = reloginData.accessToken ?? reloginData.token;
+          if (!newToken) {
+            printError("Re-login failed: no token received for selected tenant.");
+            process.exit(1);
+          }
+          token = newToken;
+          refreshToken = reloginData.refreshToken;
+        }
+      }
       const config = loadConfig(globalOpts.profile);
       config.token = token;
       if (refreshToken) {
@@ -1728,10 +1782,6 @@ function registerAuthCommands(program2) {
       description: "Login with OAuth client credentials",
       command: "geonic auth login --client-credentials --client-id MY_ID --client-secret MY_SECRET"
     },
-    {
-      description: "Login with environment variables",
-      command: "GDB_EMAIL=user@example.com GDB_PASSWORD=pass geonic auth login"
-    },
     {
       description: "Login to a specific tenant",
       command: "geonic auth login --tenant-id my-tenant"
@@ -1919,7 +1969,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);
@@ -1933,12 +1985,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);
@@ -1953,8 +2015,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(
@@ -2097,7 +2163,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);
@@ -2107,9 +2175,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"
@@ -2117,9 +2189,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);
@@ -2134,15 +2212,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);
@@ -2157,8 +2241,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(
@@ -2198,7 +2290,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);
@@ -2208,16 +2302,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);
@@ -2227,16 +2327,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);
@@ -2255,7 +2361,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);
@@ -2265,16 +2373,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);
@@ -2285,15 +2399,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);
@@ -2360,7 +2480,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);
@@ -2371,16 +2493,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);
@@ -2397,8 +2529,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(
@@ -2460,7 +2600,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);
@@ -2472,8 +2614,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(
@@ -2493,8 +2643,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(
@@ -2672,11 +2830,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());
@@ -2691,6 +2859,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"
@@ -2838,7 +3010,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);
@@ -2852,11 +3026,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);
@@ -2874,8 +3066,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(
@@ -2962,7 +3170,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);
@@ -2976,11 +3186,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);
@@ -2998,8 +3218,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(
@@ -3102,7 +3330,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);
@@ -3116,11 +3346,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);
@@ -3138,8 +3378,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(
@@ -3226,7 +3474,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);
@@ -3240,11 +3490,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);
@@ -3262,8 +3522,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(
@@ -3299,7 +3567,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);
@@ -3313,8 +3583,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(
@@ -3574,7 +3852,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);
@@ -3586,11 +3866,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);
@@ -3608,8 +3898,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(
@@ -3696,7 +3994,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);
@@ -3708,11 +4008,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);
@@ -3730,8 +4040,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(