@geolonia/geonicdb-cli 0.8.0 → 0.10.0

package/dist/index.js

@@ -25,6 +25,7 @@ function migrateV1ToV2(data) {
   const knownKeys = [
     "url",
     "service",
+    "tenantId",
     "token",
     "refreshToken",
     "format",
@@ -186,6 +187,15 @@ function printInfo(message) {
 function printWarning(message) {
   console.error(chalk.yellow(message));
 }
+function printApiKeyBox(key) {
+  const border = "\u2500".repeat(key.length + 4);
+  console.error("");
+  console.error(chalk.green(`  \u250C${border}\u2510`));
+  console.error(chalk.green(`  \u2502  ${chalk.bold(key)}  \u2502`));
+  console.error(chalk.green(`  \u2514${border}\u2518`));
+  console.error("");
+  console.error(chalk.yellow("\u26A0 \u3053\u306E API \u30AD\u30FC\u5024\u3092\u5B89\u5168\u306B\u4FDD\u5B58\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u4E8C\u5EA6\u3068\u8868\u793A\u3055\u308C\u307E\u305B\u3093\u3002"));
+}
 function printCount(count) {
   console.log(chalk.dim(`Count: ${count}`));
 }
@@ -583,7 +593,7 @@ function registerConfigCommand(program2) {
       command: "geonic config get url --profile staging"
     }
   ]);
-  const list = config.command("list").description("List all config values").action((...args) => {
+  const list = config.command("list").description("List all config values for the active (or specified) profile").action((...args) => {
     const cmd = args[args.length - 1];
     const profile = cmd.optsWithGlobals().profile;
     const all = loadConfig(profile);
@@ -597,9 +607,13 @@ function registerConfigCommand(program2) {
     {
       description: "List all configuration values",
       command: "geonic config list"
+    },
+    {
+      description: "List config for a specific profile",
+      command: "geonic config list --profile staging"
     }
   ]);
-  const del = config.command("delete").description("Delete a config value").argument("<key>", "Configuration key").action((...args) => {
+  const del = config.command("delete").description("Remove a config key from the active (or specified) profile").argument("<key>", "Configuration key").action((...args) => {
     const cmd = args[args.length - 1];
     const key = args[0];
     const profile = cmd.optsWithGlobals().profile;
@@ -608,8 +622,16 @@ function registerConfigCommand(program2) {
   });
   addExamples(del, [
     {
-      description: "Delete a config value",
+      description: "Remove the saved server URL",
       command: "geonic config delete url"
+    },
+    {
+      description: "Clear the saved authentication token",
+      command: "geonic config delete token"
+    },
+    {
+      description: "Remove API key from a specific profile",
+      command: "geonic config delete apiKey --profile staging"
     }
   ]);
 }
@@ -664,6 +686,7 @@ var GdbClient = class _GdbClient {
   clientId;
   clientSecret;
   onTokenRefresh;
+  onBeforeRefresh;
   verbose;
   dryRun;
   refreshPromise;
@@ -676,6 +699,7 @@ var GdbClient = class _GdbClient {
     this.clientId = options.clientId;
     this.clientSecret = options.clientSecret;
     this.onTokenRefresh = options.onTokenRefresh;
+    this.onBeforeRefresh = options.onBeforeRefresh;
     this.verbose = options.verbose ?? false;
     this.dryRun = options.dryRun ?? false;
   }
@@ -804,6 +828,17 @@ var GdbClient = class _GdbClient {
     }
   }
   async doRefresh() {
+    if (this.onBeforeRefresh) {
+      const latest = this.onBeforeRefresh();
+      if (latest.token && latest.token !== this.token) {
+        this.token = latest.token;
+        if (latest.refreshToken) this.refreshToken = latest.refreshToken;
+        return true;
+      }
+      if (latest.refreshToken) {
+        this.refreshToken = latest.refreshToken;
+      }
+    }
     if (this.refreshToken) {
       try {
         const url = this.buildUrl("/auth/refresh");
@@ -985,6 +1020,10 @@ function createClient(cmd) {
       if (refreshToken) cfg.refreshToken = refreshToken;
       saveConfig(cfg, opts.profile);
     },
+    onBeforeRefresh: usingCliToken ? void 0 : () => {
+      const cfg = loadConfig(opts.profile);
+      return { token: cfg.token, refreshToken: cfg.refreshToken };
+    },
     verbose: opts.verbose,
     dryRun: opts.dryRun
   });
@@ -1132,7 +1171,8 @@ async function promptTenantSelection(tenants, currentTenantId) {
       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}`);
+      const label = t.name ? `${t.name} (${t.tenantId})` : t.tenantId;
+      console.log(`${marker} ${i + 1}) ${label} [${t.role}]${current}`);
     }
     for (; ; ) {
       const answer = await rl.question("\nSelect tenant number (Enter to keep current): ");
@@ -1319,6 +1359,10 @@ function addMeOAuthClientsSubcommand(me) {
     {
       description: "List your OAuth clients",
       command: "geonic me oauth-clients list"
+    },
+    {
+      description: "List in table format for a quick overview",
+      command: "geonic me oauth-clients list --format table"
     }
   ]);
   const create = oauthClients.command("create [json]").description("Create a new OAuth client").option("--name <name>", "Client name").option("--policy <policyId>", "Policy ID to attach").option("--save", "Save credentials to config for automatic re-authentication").action(
@@ -1439,7 +1483,7 @@ function addMeOAuthClientsSubcommand(me) {
       command: "geonic me oauth-clients update <client-id> --inactive"
     }
   ]);
-  const del = oauthClients.command("delete <id>").description("Delete an OAuth client").action(
+  const del = oauthClients.command("delete <id>").description("Delete an OAuth client and revoke its credentials").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -1451,11 +1495,15 @@ function addMeOAuthClientsSubcommand(me) {
   );
   addExamples(del, [
     {
-      description: "Delete an OAuth client",
+      description: "Delete an OAuth client by ID",
       command: "geonic me oauth-clients delete <client-id>"
+    },
+    {
+      description: "Revoke a compromised client",
+      command: "geonic me oauth-clients delete abc123-def456"
     }
   ]);
-  const regenerateSecret = oauthClients.command("regenerate-secret <clientId>").description("Regenerate the client secret of an OAuth client").action(
+  const regenerateSecret = oauthClients.command("regenerate-secret <clientId>").description("Regenerate the client secret \u2014 the old secret is immediately invalidated").action(
     withErrorHandler(async (clientId, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -1472,11 +1520,54 @@ function addMeOAuthClientsSubcommand(me) {
     {
       description: "Regenerate client secret",
       command: "geonic me oauth-clients regenerate-secret <client-id>"
+    },
+    {
+      description: "Rotate secret after a security incident",
+      command: "geonic me oauth-clients regenerate-secret abc123-def456"
     }
   ]);
 }
 
 // src/commands/me-api-keys.ts
+function cleanApiKeyData(data) {
+  if (Array.isArray(data)) return data.map(cleanApiKeyData);
+  if (typeof data !== "object" || data === null) return data;
+  const obj = { ...data };
+  if (obj.key === "******") delete obj.key;
+  return obj;
+}
+function handleSaveKey(data, cmd) {
+  const globalOpts = resolveOptions(cmd);
+  const key = data.key;
+  if (!key) {
+    printError("Response missing key. API key was created, but it could not be saved.");
+    process.exitCode = 1;
+    return false;
+  }
+  try {
+    const config = loadConfig(globalOpts.profile);
+    config.apiKey = key;
+    saveConfig(config, globalOpts.profile);
+    console.error("API key saved to config. X-Api-Key header will be sent automatically.");
+    return true;
+  } catch (err) {
+    printError(`Failed to save API key to config: ${err instanceof Error ? err.message : String(err)}`);
+    printApiKeyBox(key);
+    process.exitCode = 1;
+    return false;
+  }
+}
+function showKeyResult(data, save, cmd) {
+  const key = data.key;
+  if (!key) {
+    printError("Response missing key. The new API key value was not returned.");
+    process.exitCode = 1;
+    return false;
+  }
+  if (save) return handleSaveKey(data, cmd);
+  printApiKeyBox(key);
+  return true;
+}
 function addMeApiKeysSubcommand(me) {
   const apiKeys = me.command("api-keys").description("Manage your API keys");
   const list = apiKeys.command("list").description("List your API keys").action(
@@ -1484,13 +1575,19 @@ function addMeApiKeysSubcommand(me) {
       const client = createClient(cmd);
       const format = getFormat(cmd);
       const response = await client.rawRequest("GET", "/me/api-keys");
+      response.data = cleanApiKeyData(response.data);
       outputResponse(response, format);
+      console.error("\u203B API \u30AD\u30FC\u5024\u306F\u4F5C\u6210\u6642 (create) \u307E\u305F\u306F\u30EA\u30D5\u30EC\u30C3\u30B7\u30E5\u6642 (refresh) \u306B\u306E\u307F\u8868\u793A\u3055\u308C\u307E\u3059\u3002");
     })
   );
   addExamples(list, [
     {
       description: "List your API keys",
       command: "geonic me api-keys list"
+    },
+    {
+      description: "List in table format for a quick overview",
+      command: "geonic me api-keys list --format table"
     }
   ]);
   const create = apiKeys.command("create [json]").description("Create a new API key").option("--name <name>", "Key name").option("--policy <policyId>", "Policy ID to attach").option("--origins <origins>", "Allowed origins (comma-separated)").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--save", "Save the API key to config for automatic use").action(
@@ -1540,24 +1637,9 @@ function addMeApiKeysSubcommand(me) {
       const format = getFormat(cmd);
       const response = await client.rawRequest("POST", "/me/api-keys", { body });
       const data = response.data;
-      if (opts.save) {
-        const globalOpts = resolveOptions(cmd);
-        const key = data.key;
-        if (!key) {
-          printError("Response missing key. API key was created, but it could not be saved.");
-          outputResponse(response, format);
-          process.exitCode = 1;
-          return;
-        }
-        const config = loadConfig(globalOpts.profile);
-        config.apiKey = key;
-        saveConfig(config, globalOpts.profile);
-        console.error("API key saved to config. X-Api-Key header will be sent automatically.");
-      } else {
-        printWarning("Save the API key now \u2014 it will not be shown again. Use --save to store it automatically.");
-      }
+      const ok = showKeyResult(data, !!opts.save, cmd);
       outputResponse(response, format);
-      console.error("API key created.");
+      if (ok) console.error("API key created.");
     })
   );
   addNotes(create, [
@@ -1586,6 +1668,35 @@ function addMeApiKeysSubcommand(me) {
       command: "geonic me api-keys create --name my-app --dpop-required"
     }
   ]);
+  const refresh = apiKeys.command("refresh <keyId>").description("Refresh (rotate) an API key \u2014 generates a new key value").option("--save", "Save the new API key to config for automatic use").action(
+    withErrorHandler(async (keyId, _opts, cmd) => {
+      const opts = cmd.opts();
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "POST",
+        `/me/api-keys/${encodeURIComponent(String(keyId))}/refresh`
+      );
+      const data = response.data;
+      const ok = showKeyResult(data, !!opts.save, cmd);
+      outputResponse(response, format);
+      if (ok) console.error("API key refreshed.");
+    })
+  );
+  addNotes(refresh, [
+    "Refreshing generates a new key value while keeping keyId, name, and policy settings.",
+    "The previous key value is immediately invalidated."
+  ]);
+  addExamples(refresh, [
+    {
+      description: "Refresh an API key",
+      command: "geonic me api-keys refresh <key-id>"
+    },
+    {
+      description: "Refresh and save new key to config",
+      command: "geonic me api-keys refresh <key-id> --save"
+    }
+  ]);
   const update = apiKeys.command("update <keyId> [json]").description("Update an API key").option("--name <name>", "Key name").option("--policy-id <policyId>", "Policy ID to attach (use 'null' to unbind)").option("--origins <origins>", "Allowed origins (comma-separated)").option("--rate-limit <n>", "Rate limit (requests per minute)").option("--dpop-required", "Require DPoP token binding").option("--no-dpop-required", "Disable DPoP requirement").option("--active", "Activate the API key").option("--inactive", "Deactivate the API key").action(
     withErrorHandler(async (keyId, json, _opts, cmd) => {
       const opts = cmd.opts();
@@ -1657,7 +1768,7 @@ function addMeApiKeysSubcommand(me) {
       command: `geonic me api-keys update <key-id> '{"name":"new-name","rateLimit":{"perMinute":60}}'`
     }
   ]);
-  const del = apiKeys.command("delete <keyId>").description("Delete an API key").action(
+  const del = apiKeys.command("delete <keyId>").description("Delete an API key \u2014 immediately revokes access for any client using it").action(
     withErrorHandler(async (keyId, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -1669,8 +1780,12 @@ function addMeApiKeysSubcommand(me) {
   );
   addExamples(del, [
     {
-      description: "Delete an API key",
+      description: "Delete an API key by ID",
       command: "geonic me api-keys delete <key-id>"
+    },
+    {
+      description: "Revoke a leaked or unused key",
+      command: "geonic me api-keys delete abc123-def456"
     }
   ]);
 }
@@ -1690,9 +1805,13 @@ function addMePoliciesSubcommand(me) {
     {
       description: "List your personal policies",
       command: "geonic me policies list"
+    },
+    {
+      description: "List in table format for a quick overview",
+      command: "geonic me policies list --format table"
     }
   ]);
-  const get = policies.command("get <policyId>").description("Get a personal policy by ID").action(
+  const get = policies.command("get <policyId>").description("Get a personal policy by ID to inspect its XACML rules and target resources").action(
     withErrorHandler(async (policyId, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -1707,9 +1826,13 @@ function addMePoliciesSubcommand(me) {
     {
       description: "Get a personal policy by ID",
       command: "geonic me policies get <policy-id>"
+    },
+    {
+      description: "Inspect policy rules and permitted actions",
+      command: "geonic me policies get my-readonly --format table"
     }
   ]);
-  const create = policies.command("create [json]").description(
+  const create = policies.command("create [json]").summary("Create a personal XACML policy").description(
     `Create a personal XACML policy
 
 Constraints (enforced server-side):
@@ -1800,7 +1923,7 @@ Example \u2014 GET-only policy for /v2/**:
       command: "geonic me policies update <policy-id> @patch.json"
     }
   ]);
-  const del = policies.command("delete <policyId>").description("Delete a personal policy").action(
+  const del = policies.command("delete <policyId>").description("Delete a personal policy \u2014 any API key or OAuth client bound to it loses access granted by this policy").action(
     withErrorHandler(async (policyId, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -1812,8 +1935,12 @@ Example \u2014 GET-only policy for /v2/**:
   );
   addExamples(del, [
     {
-      description: "Delete a personal policy",
+      description: "Delete a personal policy by ID",
       command: "geonic me policies delete <policy-id>"
+    },
+    {
+      description: "Remove a policy (unbind from API keys/OAuth clients first)",
+      command: "geonic me policies delete my-readonly"
     }
   ]);
 }
@@ -1871,8 +1998,10 @@ function createLoginCommand() {
       const password = await promptPassword();
       const client = createClient(cmd);
       const body = { email, password };
-      if (loginOpts.tenantId) {
-        body.tenantId = loginOpts.tenantId;
+      const requestTenantId = loginOpts.tenantId;
+      const serviceFlag = globalOpts.service;
+      if (requestTenantId) {
+        body.tenantId = requestTenantId;
       }
       const response = await client.rawRequest("POST", "/auth/login", {
         body,
@@ -1886,12 +2015,28 @@ function createLoginCommand() {
         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) {
+      let finalTenantId = data.tenantId;
+      if (availableTenants && availableTenants.length > 1 && !requestTenantId) {
+        let resolvedTenantId;
+        if (serviceFlag) {
+          const match = availableTenants.find(
+            (t) => t.name === serviceFlag || t.tenantId === serviceFlag
+          );
+          if (match) {
+            resolvedTenantId = match.tenantId;
+          } else {
+            printError(
+              `Tenant "${serviceFlag}" not found. Available: ${availableTenants.map((t) => t.name ?? t.tenantId).join(", ")}`
+            );
+            process.exit(1);
+          }
+        }
+        if (!resolvedTenantId) {
+          resolvedTenantId = await promptTenantSelection(availableTenants, finalTenantId);
+        }
+        if (resolvedTenantId && resolvedTenantId !== finalTenantId) {
           const reloginResponse = await client.rawRequest("POST", "/auth/login", {
-            body: { email, password, tenantId: selectedTenantId },
+            body: { email, password, tenantId: resolvedTenantId },
             skipTenantHeader: true
           });
           const reloginData = reloginResponse.data;
@@ -1902,6 +2047,7 @@ function createLoginCommand() {
           }
           token = newToken;
           refreshToken = reloginData.refreshToken;
+          finalTenantId = resolvedTenantId;
         }
       }
       const config = loadConfig(globalOpts.profile);
@@ -1911,13 +2057,30 @@ function createLoginCommand() {
       } else {
         delete config.refreshToken;
       }
+      if (finalTenantId) {
+        config.service = finalTenantId;
+        config.tenantId = finalTenantId;
+      } else {
+        delete config.service;
+        delete config.tenantId;
+      }
+      if (availableTenants && availableTenants.length > 0) {
+        config.availableTenants = availableTenants.map((t) => ({
+          tenantId: t.tenantId,
+          ...t.name ? { name: t.name } : {},
+          role: t.role
+        }));
+      } else {
+        delete config.availableTenants;
+      }
       saveConfig(config, globalOpts.profile);
-      printSuccess("Login successful. Token saved to config.");
+      const tenantLabel = finalTenantId ? ` (tenant: ${availableTenants?.find((t) => t.tenantId === finalTenantId)?.name ?? finalTenantId})` : "";
+      printSuccess(`Login successful${tenantLabel}. Token saved to config.`);
     })
   );
 }
 function createLogoutCommand() {
-  return new Command("logout").description("Clear saved authentication token").action(
+  return new Command("logout").description("Clear saved authentication token and notify the server").action(
     withErrorHandler(async (...args) => {
       const cmd = args[args.length - 1];
       const globalOpts = resolveOptions(cmd);
@@ -1990,7 +2153,7 @@ async function fetchNonce(baseUrl, apiKey) {
   return await response.json();
 }
 function createNonceCommand() {
-  return new Command("nonce").description("Get a nonce and PoW challenge for API key authentication").option("--api-key <key>", "API key to get nonce for").action(
+  return new Command("nonce").description("Request a nonce and Proof-of-Work challenge (step 1 of API key to JWT exchange)").option("--api-key <key>", "API key to get nonce for").action(
     withErrorHandler(async (...args) => {
       const cmd = args[args.length - 1];
       const nonceOpts = cmd.opts();
@@ -2032,7 +2195,7 @@ function solvePoW(challenge, difficulty) {
   throw new Error(`PoW could not be solved within ${MAX_POW_ITERATIONS} iterations`);
 }
 function createTokenExchangeCommand() {
-  return new Command("token-exchange").description("Exchange API key for a session JWT via nonce + PoW").option("--api-key <key>", "API key to exchange").option("--save", "Save the obtained token to profile config").action(
+  return new Command("token-exchange").description("Exchange an API key for a session JWT (fetches nonce, solves PoW, returns token)").option("--api-key <key>", "API key to exchange").option("--save", "Save the obtained token to profile config").action(
     withErrorHandler(async (...args) => {
       const cmd = args[args.length - 1];
       const exchangeOpts = cmd.opts();
@@ -2096,8 +2259,12 @@ function registerAuthCommands(program2) {
       command: "geonic auth login --client-credentials --client-id MY_ID --client-secret MY_SECRET"
     },
     {
-      description: "Login to a specific tenant",
+      description: "Login to a specific tenant by ID",
       command: "geonic auth login --tenant-id my-tenant"
+    },
+    {
+      description: "Login to a tenant by name",
+      command: "geonic auth login -s demo_smartcity"
     }
   ]);
   auth.addCommand(login);
@@ -2106,6 +2273,10 @@ function registerAuthCommands(program2) {
     {
       description: "Clear saved authentication token",
       command: "geonic auth logout"
+    },
+    {
+      description: "Logout from a specific profile",
+      command: "geonic auth logout --profile staging"
     }
   ]);
   auth.addCommand(logout);
@@ -2114,14 +2285,26 @@ function registerAuthCommands(program2) {
     {
       description: "Get a nonce for API key authentication",
       command: "geonic auth nonce --api-key gdb_abcdef..."
+    },
+    {
+      description: "Use a pre-configured API key",
+      command: "geonic auth nonce"
     }
   ]);
   auth.addCommand(nonce);
   const tokenExchange = createTokenExchangeCommand();
   addExamples(tokenExchange, [
     {
-      description: "Exchange API key for a JWT and save it",
+      description: "Exchange API key for a JWT and save it to the active profile",
       command: "geonic auth token-exchange --api-key gdb_abcdef... --save"
+    },
+    {
+      description: "Exchange and print the JWT without saving",
+      command: "geonic auth token-exchange --api-key gdb_abcdef..."
+    },
+    {
+      description: "Use a pre-configured API key and save the resulting token",
+      command: "geonic auth token-exchange --save"
     }
   ]);
   auth.addCommand(tokenExchange);
@@ -2158,8 +2341,8 @@ function registerAuthCommands(program2) {
 
 // src/commands/profile.ts
 function registerProfileCommands(program2) {
-  const profile = program2.command("profile").description("Manage connection profiles");
-  const list = profile.command("list").description("List all profiles").action(() => {
+  const profile = program2.command("profile").description("Manage connection profiles (each profile stores its own URL, token, and tenant)");
+  const list = profile.command("list").description("List all profiles (active profile marked with *)").action(() => {
     const profiles = listProfiles();
     for (const p of profiles) {
       const marker = p.active ? " *" : "";
@@ -2172,22 +2355,57 @@ function registerProfileCommands(program2) {
       command: "geonic profile list"
     }
   ]);
-  const use = profile.command("use <name>").description("Switch active profile").action((name) => {
+  const use = profile.command("use <name>").description("Switch active profile (auto-refreshes expired tokens)").action(async (name) => {
     try {
       setCurrentProfile(name);
-      printSuccess(`Switched to profile "${name}".`);
     } catch (err) {
       printError(err.message);
       process.exit(1);
     }
+    const config = loadConfig(name);
+    const tenantLabel = config.tenantId ? ` (tenant: ${config.availableTenants?.find((t) => t.tenantId === config.tenantId)?.name ?? config.tenantId})` : "";
+    if (config.token && config.refreshToken && config.url) {
+      const status = getTokenStatus(config.token);
+      if (status.isExpired || status.isExpiringSoon) {
+        try {
+          const baseUrl = validateUrl(config.url);
+          const url = new URL("/auth/refresh", baseUrl).toString();
+          const response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ refreshToken: config.refreshToken })
+          });
+          if (response.ok) {
+            const data = await response.json();
+            const newToken = data.accessToken ?? data.token;
+            const newRefreshToken = data.refreshToken;
+            if (newToken) {
+              config.token = newToken;
+              if (newRefreshToken) config.refreshToken = newRefreshToken;
+              saveConfig(config, name);
+              printSuccess(`Switched to profile "${name}"${tenantLabel}. Token refreshed.`);
+              return;
+            }
+          }
+          printWarning("Token refresh failed. You may need to re-login.");
+        } catch {
+          printWarning("Token refresh failed. You may need to re-login.");
+        }
+      }
+    }
+    printSuccess(`Switched to profile "${name}"${tenantLabel}.`);
   });
   addExamples(use, [
     {
       description: "Switch to staging profile",
       command: "geonic profile use staging"
+    },
+    {
+      description: "Switch to production profile",
+      command: "geonic profile use production"
     }
   ]);
-  const profileCreate = profile.command("create <name>").description("Create a new profile").action((name) => {
+  const profileCreate = profile.command("create <name>").description("Create a new named profile for a separate environment or tenant").action((name) => {
     try {
       createProfile(name);
       printSuccess(`Profile "${name}" created.`);
@@ -2200,9 +2418,13 @@ function registerProfileCommands(program2) {
     {
       description: "Create a new profile for staging",
       command: "geonic profile create staging"
+    },
+    {
+      description: "Create a profile for a different tenant",
+      command: "geonic profile create tenant-b"
     }
   ]);
-  const del = profile.command("delete <name>").description("Delete a profile").action((name) => {
+  const del = profile.command("delete <name>").description("Delete a profile and its stored configuration").action((name) => {
     try {
       deleteProfile(name);
       printSuccess(`Profile "${name}" deleted.`);
@@ -2213,11 +2435,11 @@ function registerProfileCommands(program2) {
   });
   addExamples(del, [
     {
-      description: "Delete a profile",
+      description: "Delete the staging profile",
       command: "geonic profile delete staging"
     }
   ]);
-  const show = profile.command("show [name]").description("Show profile settings").action((name) => {
+  const show = profile.command("show [name]").description("Show profile settings (URL, tenant, token status, etc.)").action((name) => {
     const profileName = name ?? getCurrentProfile();
     const config = loadConfig(profileName);
     const entries = Object.entries(config).filter(([, v]) => v !== void 0);
@@ -2228,6 +2450,13 @@ function registerProfileCommands(program2) {
     for (const [key, value] of entries) {
       if ((key === "token" || key === "refreshToken" || key === "apiKey") && typeof value === "string") {
         console.log(`${key}: ***`);
+      } else if (key === "availableTenants" && Array.isArray(value)) {
+        console.log(`${key}:`);
+        for (const t of value) {
+          const label = t.name ? `${t.name} (${t.tenantId})` : t.tenantId;
+          const current = t.tenantId === config.tenantId ? " \u2190 current" : "";
+          console.log(`  - ${label} [${t.role}]${current}`);
+        }
       } else {
         console.log(`${key}: ${value}`);
       }
@@ -2247,7 +2476,7 @@ function registerProfileCommands(program2) {
 
 // src/commands/attrs.ts
 function addAttrsSubcommands(attrs) {
-  const list = attrs.command("list").description("List all attributes of an entity").argument("<entityId>", "Entity ID").action(
+  const list = attrs.command("list").description("List all attributes of an entity, returning each attribute's type, value, and metadata").argument("<entityId>", "Entity ID").action(
     withErrorHandler(
       async (entityId, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2263,9 +2492,17 @@ function addAttrsSubcommands(attrs) {
     {
       description: "List all attributes of an entity",
       command: "geonic entities attrs list urn:ngsi-ld:Sensor:001"
+    },
+    {
+      description: "List attributes in table format",
+      command: "geonic entities attrs list urn:ngsi-ld:Sensor:001 --format table"
+    },
+    {
+      description: "List attributes with keyValues output",
+      command: "geonic entities attrs list urn:ngsi-ld:Building:store01 --format json"
     }
   ]);
-  const get = attrs.command("get").description("Get a specific attribute of an entity").argument("<entityId>", "Entity ID").argument("<attrName>", "Attribute name").action(
+  const get = attrs.command("get").description("Get the value and metadata of a single attribute on an entity").argument("<entityId>", "Entity ID").argument("<attrName>", "Attribute name").action(
     withErrorHandler(
       async (entityId, attrName, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2279,11 +2516,19 @@ function addAttrsSubcommands(attrs) {
   );
   addExamples(get, [
     {
-      description: "Get a specific attribute",
+      description: "Get the temperature attribute of a sensor",
       command: "geonic entities attrs get urn:ngsi-ld:Sensor:001 temperature"
+    },
+    {
+      description: "Get a Relationship attribute to see what it links to",
+      command: "geonic entities attrs get urn:ngsi-ld:Building:store01 owner"
+    },
+    {
+      description: "Get an attribute in table format",
+      command: "geonic entities attrs get urn:ngsi-ld:Sensor:001 location --format table"
     }
   ]);
-  const add = attrs.command("add").description(
+  const add = attrs.command("add").summary("Add attributes to an entity").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(
@@ -2312,7 +2557,7 @@ function addAttrsSubcommands(attrs) {
       command: "cat attrs.json | geonic entities attrs add urn:ngsi-ld:Sensor:001"
     }
   ]);
-  const attrUpdate = attrs.command("update").description(
+  const attrUpdate = attrs.command("update").summary("Update a specific attribute of an entity").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(
@@ -2337,7 +2582,7 @@ function addAttrsSubcommands(attrs) {
       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(
+  const del = attrs.command("delete").description("Remove an attribute from an entity permanently").argument("<entityId>", "Entity ID").argument("<attrName>", "Attribute name").action(
     withErrorHandler(
       async (entityId, attrName, _opts, cmd) => {
         const client = createClient(cmd);
@@ -2350,8 +2595,12 @@ function addAttrsSubcommands(attrs) {
   );
   addExamples(del, [
     {
-      description: "Delete a specific attribute",
+      description: "Remove the temperature attribute from a sensor",
       command: "geonic entities attrs delete urn:ngsi-ld:Sensor:001 temperature"
+    },
+    {
+      description: "Remove a deprecated attribute from a building entity",
+      command: "geonic entities attrs delete urn:ngsi-ld:Building:store01 legacyCode"
     }
   ]);
 }
@@ -2477,7 +2726,7 @@ function registerEntitiesCommand(program2) {
       command: "geonic entities get urn:ngsi-ld:Sensor:001 --key-values"
     }
   ]);
-  const create = entities.command("create").description(
+  const create = entities.command("create").summary("Create a new entity").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) => {
@@ -2509,7 +2758,7 @@ function registerEntitiesCommand(program2) {
       command: "geonic entities create"
     }
   ]);
-  const update = entities.command("update").description(
+  const update = entities.command("update").summary("Update attributes of an entity (PATCH)").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(
@@ -2538,7 +2787,7 @@ function registerEntitiesCommand(program2) {
       command: "cat attrs.json | geonic entities update urn:ngsi-ld:Sensor:001"
     }
   ]);
-  const replace = entities.command("replace").description(
+  const replace = entities.command("replace").summary("Replace all attributes of an entity (PUT)").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(
@@ -2585,7 +2834,7 @@ function registerEntitiesCommand(program2) {
       command: "cat entities.json | geonic entities upsert"
     }
   ]);
-  const del = entities.command("delete").description("Delete an entity by ID").argument("<id>", "Entity ID").action(
+  const del = entities.command("delete").description("Permanently delete an entity and all its attributes").argument("<id>", "Entity ID").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.delete(`/entities/${encodeURIComponent(id)}`);
@@ -2596,6 +2845,10 @@ function registerEntitiesCommand(program2) {
     {
       description: "Delete an entity by ID",
       command: "geonic entities delete urn:ngsi-ld:Sensor:001"
+    },
+    {
+      description: "Delete with explicit service tenant",
+      command: "geonic entities delete urn:ngsi-ld:Sensor:001 --service my-tenant"
     }
   ]);
   registerAttrsSubcommand(entities);
@@ -2604,7 +2857,7 @@ 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(
+  const create = batch.command("create [json]").summary("Batch create entities").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) => {
@@ -2629,7 +2882,7 @@ function registerBatchCommand(program2) {
       command: "cat entities.json | geonic batch create"
     }
   ]);
-  const upsert = batch.command("upsert [json]").description(
+  const upsert = batch.command("upsert [json]").summary("Batch upsert entities").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) => {
@@ -2654,7 +2907,7 @@ function registerBatchCommand(program2) {
       command: "cat entities.json | geonic batch upsert"
     }
   ]);
-  const update = batch.command("update [json]").description(
+  const update = batch.command("update [json]").summary("Batch update entity attributes").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) => {
@@ -2675,7 +2928,7 @@ function registerBatchCommand(program2) {
       command: "cat updates.json | geonic batch update"
     }
   ]);
-  const del = batch.command("delete [json]").description(
+  const del = batch.command("delete [json]").summary("Batch delete entities by ID").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) => {
@@ -2700,7 +2953,7 @@ function registerBatchCommand(program2) {
       command: "cat entity-ids.json | geonic batch delete"
     }
   ]);
-  const query = batch.command("query [json]").description(
+  const query = batch.command("query [json]").summary("Query entities by posting a query payload").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) => {
@@ -2725,7 +2978,7 @@ function registerBatchCommand(program2) {
       command: "cat query.json | geonic batch query"
     }
   ]);
-  const merge = batch.command("merge [json]").description(
+  const merge = batch.command("merge [json]").summary("Batch merge-patch entities").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) => {
@@ -2778,7 +3031,7 @@ function registerSubscriptionsCommand(program2) {
       command: "geonic subscriptions list --count"
     }
   ]);
-  const get = subscriptions.command("get <id>").description("Get a subscription by ID").action(
+  const get = subscriptions.command("get <id>").description("Get a subscription by ID to inspect its notification config, watched attributes, and status").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2790,11 +3043,15 @@ function registerSubscriptionsCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get subscription by ID",
+      description: "Get subscription details by ID",
       command: "geonic subscriptions get urn:ngsi-ld:Subscription:001"
+    },
+    {
+      description: "Inspect notification endpoint and status in table format",
+      command: "geonic subscriptions get urn:ngsi-ld:Subscription:001 --format table"
     }
   ]);
-  const create = subscriptions.command("create [json]").description(
+  const create = subscriptions.command("create [json]").summary("Create a subscription").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) => {
@@ -2824,7 +3081,7 @@ function registerSubscriptionsCommand(program2) {
       command: "geonic subscriptions create"
     }
   ]);
-  const update = subscriptions.command("update <id> [json]").description(
+  const update = subscriptions.command("update <id> [json]").summary("Update a subscription").description(
     'Update a subscription\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated subscription"}'
   ).action(
     withErrorHandler(
@@ -2855,7 +3112,7 @@ function registerSubscriptionsCommand(program2) {
       command: "cat sub.json | geonic subscriptions update urn:ngsi-ld:Subscription:001"
     }
   ]);
-  const del = subscriptions.command("delete <id>").description("Delete a subscription").action(
+  const del = subscriptions.command("delete <id>").description("Delete a subscription and stop its notifications").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.delete(
@@ -2866,8 +3123,12 @@ function registerSubscriptionsCommand(program2) {
   );
   addExamples(del, [
     {
-      description: "Delete a subscription",
+      description: "Delete a subscription by ID",
       command: "geonic subscriptions delete urn:ngsi-ld:Subscription:001"
+    },
+    {
+      description: "Stop notifications by removing the subscription (using alias)",
+      command: "geonic sub delete urn:ngsi-ld:Subscription:001"
     }
   ]);
 }
@@ -2898,7 +3159,7 @@ function registerRegistrationsCommand(program2) {
       command: "geonic registrations list --limit 10"
     }
   ]);
-  const get = registrations.command("get <id>").description("Get a registration by ID").action(
+  const get = registrations.command("get <id>").description("Get a registration by ID to inspect its federation endpoint and entity routing").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2910,11 +3171,15 @@ function registerRegistrationsCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get registration by ID",
+      description: "Get registration details by ID",
       command: "geonic registrations get urn:ngsi-ld:ContextSourceRegistration:001"
+    },
+    {
+      description: "Inspect federation config in table format",
+      command: "geonic registrations get urn:ngsi-ld:ContextSourceRegistration:001 --format table"
     }
   ]);
-  const create = registrations.command("create [json]").description(
+  const create = registrations.command("create [json]").summary("Create a registration").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) => {
@@ -2969,7 +3234,7 @@ function registerRegistrationsCommand(program2) {
       command: "cat registration.json | geonic registrations update urn:ngsi-ld:ContextSourceRegistration:001"
     }
   ]);
-  const del = registrations.command("delete <id>").description("Delete a registration").action(
+  const del = registrations.command("delete <id>").description("Delete a registration and remove its forwarding rule").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.delete(
@@ -2980,16 +3245,20 @@ function registerRegistrationsCommand(program2) {
   );
   addExamples(del, [
     {
-      description: "Delete a registration",
+      description: "Delete a registration by ID",
       command: "geonic registrations delete urn:ngsi-ld:ContextSourceRegistration:001"
+    },
+    {
+      description: "Remove forwarding rule (using alias)",
+      command: "geonic reg delete urn:ngsi-ld:ContextSourceRegistration:001"
     }
   ]);
 }
 
 // src/commands/types.ts
 function registerTypesCommand(program2) {
-  const types = program2.command("types").description("Browse entity types");
-  const list = types.command("list").description("List available entity types").action(
+  const types = program2.command("types").description("Discover what entity types exist in the broker and inspect their structure");
+  const list = types.command("list").description("List all entity types currently stored in the broker").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -2999,11 +3268,15 @@ function registerTypesCommand(program2) {
   );
   addExamples(list, [
     {
-      description: "List all entity types",
+      description: "List all entity types in the broker",
       command: "geonic types list"
+    },
+    {
+      description: "List entity types in table format for a quick overview",
+      command: "geonic types list --format table"
     }
   ]);
-  const get = types.command("get <typeName>").description("Get details for an entity type").action(
+  const get = types.command("get <typeName>").description("Show attribute names and types for a given entity type").action(
     withErrorHandler(
       async (typeName, _opts, cmd) => {
         const client = createClient(cmd);
@@ -3017,8 +3290,16 @@ function registerTypesCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get details for a specific type",
+      description: "Inspect the Sensor type to see its attributes",
       command: "geonic types get Sensor"
+    },
+    {
+      description: "Inspect a Building type in table format",
+      command: "geonic types get Building --format table"
+    },
+    {
+      description: "Inspect a fully-qualified NGSI-LD type",
+      command: "geonic types get https://uri.fiware.org/ns/data-models#AirQualityObserved"
     }
   ]);
 }
@@ -3144,7 +3425,7 @@ function registerTemporalCommand(program2) {
       command: "geonic temporal entities get urn:ngsi-ld:Sensor:001 --last-n 10"
     }
   ]);
-  const create = entities.command("create [json]").description(
+  const create = entities.command("create [json]").summary("Create a temporal entity").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, [
@@ -3161,11 +3442,15 @@ function registerTemporalCommand(program2) {
       command: "geonic temporal entities create"
     }
   ]);
-  const del = entities.command("delete <id>").description("Delete a temporal entity by ID").action(createDeleteAction());
+  const del = entities.command("delete <id>").description("Delete a temporal entity and all its historical attribute data").action(createDeleteAction());
   addExamples(del, [
     {
       description: "Delete temporal data for an entity",
       command: "geonic temporal entities delete urn:ngsi-ld:Sensor:001"
+    },
+    {
+      description: "Remove all historical records for a specific entity",
+      command: "geonic temporal entities delete urn:ngsi-ld:WeatherStation:tokyo-01"
     }
   ]);
   const opsQuery = addQueryOptions(
@@ -3201,8 +3486,8 @@ function registerTemporalCommand(program2) {
 
 // src/commands/snapshots.ts
 function registerSnapshotsCommand(program2) {
-  const snapshots = program2.command("snapshots").description("Manage snapshots");
-  const list = snapshots.command("list").description("List snapshots").option("--limit <n>", "Maximum number of snapshots to return", parseInt).option("--offset <n>", "Skip first N snapshots", parseInt).action(
+  const snapshots = program2.command("snapshots").description("Manage point-in-time snapshots of entity data for backup and cloning");
+  const list = snapshots.command("list").description("List all available snapshots with their IDs, timestamps, and status").option("--limit <n>", "Maximum number of snapshots to return", parseInt).option("--offset <n>", "Skip first N snapshots", parseInt).action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3220,11 +3505,19 @@ function registerSnapshotsCommand(program2) {
       command: "geonic snapshots list"
     },
     {
-      description: "List with a limit",
+      description: "List the 10 most recent snapshots",
       command: "geonic snapshots list --limit 10"
+    },
+    {
+      description: "Paginate through snapshots",
+      command: "geonic snapshots list --limit 5 --offset 10"
+    },
+    {
+      description: "List snapshots in table format",
+      command: "geonic snapshots list --format table"
     }
   ]);
-  const get = snapshots.command("get <id>").description("Get a snapshot by ID").action(
+  const get = snapshots.command("get <id>").description("Retrieve details of a specific snapshot including its status and metadata").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3236,11 +3529,15 @@ function registerSnapshotsCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get a specific snapshot",
-      command: "geonic snapshots get <snapshot-id>"
+      description: "Get details of a snapshot by its ID",
+      command: "geonic snapshots get abc123"
+    },
+    {
+      description: "Get snapshot details in table format",
+      command: "geonic snapshots get abc123 --format table"
     }
   ]);
-  const create = snapshots.command("create").description("Create a new snapshot").action(
+  const create = snapshots.command("create").description("Create a point-in-time snapshot of all current entity data").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       await client.post("/snapshots");
@@ -3249,11 +3546,15 @@ function registerSnapshotsCommand(program2) {
   );
   addExamples(create, [
     {
-      description: "Create a new snapshot",
+      description: "Create a snapshot of the current entity data",
       command: "geonic snapshots create"
+    },
+    {
+      description: "Create a snapshot before performing a bulk update",
+      command: "geonic snapshots create && geonic batch upsert @bulk-update.json"
     }
   ]);
-  const del = snapshots.command("delete <id>").description("Delete a snapshot by ID").action(
+  const del = snapshots.command("delete <id>").description("Permanently delete a snapshot to free storage").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.delete(
@@ -3264,11 +3565,15 @@ function registerSnapshotsCommand(program2) {
   );
   addExamples(del, [
     {
-      description: "Delete a snapshot",
-      command: "geonic snapshots delete <snapshot-id>"
+      description: "Delete a snapshot by its ID",
+      command: "geonic snapshots delete abc123"
+    },
+    {
+      description: "Delete an old snapshot to reclaim storage",
+      command: "geonic snapshots delete old-backup-id"
     }
   ]);
-  const clone = snapshots.command("clone <id>").description("Clone a snapshot by ID").action(
+  const clone = snapshots.command("clone <id>").description("Clone a snapshot to create a duplicate for testing or migration").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3284,8 +3589,12 @@ function registerSnapshotsCommand(program2) {
   );
   addExamples(clone, [
     {
-      description: "Clone a snapshot",
-      command: "geonic snapshots clone <snapshot-id>"
+      description: "Clone a snapshot for use in a test environment",
+      command: "geonic snapshots clone abc123"
+    },
+    {
+      description: "Clone a production snapshot to a staging profile",
+      command: "geonic snapshots clone abc123 --profile staging"
     }
   ]);
 }
@@ -3293,7 +3602,7 @@ function registerSnapshotsCommand(program2) {
 // src/commands/admin/tenants.ts
 function registerTenantsCommand(parent) {
   const tenants = parent.command("tenants").description("Manage tenants");
-  const list = tenants.command("list").description("List all tenants").action(
+  const list = tenants.command("list").description("List all tenants in the system, including their status and configuration").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3305,9 +3614,13 @@ function registerTenantsCommand(parent) {
     {
       description: "List all tenants",
       command: "geonic admin tenants list"
+    },
+    {
+      description: "List tenants in table format",
+      command: "geonic admin tenants list --format table"
     }
   ]);
-  const get = tenants.command("get <id>").description("Get a tenant by ID").action(
+  const get = tenants.command("get <id>").description("Get a tenant's details \u2014 name, description, status, and creation date").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3320,11 +3633,15 @@ function registerTenantsCommand(parent) {
   );
   addExamples(get, [
     {
-      description: "Get a tenant by ID",
+      description: "Get tenant details by ID",
       command: "geonic admin tenants get <tenant-id>"
+    },
+    {
+      description: "Get tenant details in table format",
+      command: "geonic admin tenants get <tenant-id> --format table"
     }
   ]);
-  const create = tenants.command("create [json]").description(
+  const create = tenants.command("create [json]").summary("Create a new tenant").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) => {
@@ -3360,7 +3677,7 @@ function registerTenantsCommand(parent) {
       command: "geonic admin tenants create"
     }
   ]);
-  const update = tenants.command("update <id> [json]").description(
+  const update = tenants.command("update <id> [json]").summary("Update a tenant").description(
     'Update a tenant\n\nJSON payload: only specified fields are updated.\n  e.g. {"name": "new-name", "description": "Updated description"}'
   ).action(
     withErrorHandler(
@@ -3400,7 +3717,7 @@ function registerTenantsCommand(parent) {
       command: "geonic admin tenants update <tenant-id>"
     }
   ]);
-  const del = tenants.command("delete <id>").description("Delete a tenant").action(
+  const del = tenants.command("delete <id>").description("Permanently delete a tenant and all its associated data. This action cannot be undone").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3412,11 +3729,15 @@ function registerTenantsCommand(parent) {
   );
   addExamples(del, [
     {
-      description: "Delete a tenant",
+      description: "Delete a tenant by ID",
       command: "geonic admin tenants delete <tenant-id>"
+    },
+    {
+      description: "Delete with verbose output to confirm",
+      command: "geonic admin tenants delete <tenant-id> --verbose"
     }
   ]);
-  const activate = tenants.command("activate <id>").description("Activate a tenant").action(
+  const activate = tenants.command("activate <id>").description("Activate a tenant, restoring API access for all its users").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3428,11 +3749,11 @@ function registerTenantsCommand(parent) {
   );
   addExamples(activate, [
     {
-      description: "Activate a tenant",
+      description: "Activate a deactivated tenant",
       command: "geonic admin tenants activate <tenant-id>"
     }
   ]);
-  const deactivate = tenants.command("deactivate <id>").description("Deactivate a tenant").action(
+  const deactivate = tenants.command("deactivate <id>").description("Deactivate a tenant, blocking API access for all its users until reactivated").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3444,7 +3765,7 @@ function registerTenantsCommand(parent) {
   );
   addExamples(deactivate, [
     {
-      description: "Deactivate a tenant",
+      description: "Deactivate a tenant to temporarily suspend access",
       command: "geonic admin tenants deactivate <tenant-id>"
     }
   ]);
@@ -3453,7 +3774,7 @@ function registerTenantsCommand(parent) {
 // src/commands/admin/users.ts
 function registerUsersCommand(parent) {
   const users = parent.command("users").description("Manage users");
-  const list = users.command("list").description("List all users").action(
+  const list = users.command("list").description("List all users across tenants, showing email, role, and status").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3465,9 +3786,17 @@ function registerUsersCommand(parent) {
     {
       description: "List all users",
       command: "geonic admin users list"
+    },
+    {
+      description: "List users in table format",
+      command: "geonic admin users list --format table"
+    },
+    {
+      description: "List users for a specific tenant",
+      command: "geonic admin users list --service <tenant-id>"
     }
   ]);
-  const get = users.command("get <id>").description("Get a user by ID").action(
+  const get = users.command("get <id>").description("Get a user's details \u2014 email, role, tenant, status, and login history").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3480,11 +3809,15 @@ function registerUsersCommand(parent) {
   );
   addExamples(get, [
     {
-      description: "Get a user by ID",
+      description: "Inspect a user's account details",
       command: "geonic admin users get <user-id>"
+    },
+    {
+      description: "Get user details in table format",
+      command: "geonic admin users get <user-id> --format table"
     }
   ]);
-  const create = users.command("create [json]").description(
+  const create = users.command("create [json]").summary("Create a new user").description(
     'Create a new user\n\nJSON payload example:\n  {\n    "email": "user@example.com",\n    "password": "SecurePassword123!",\n    "role": "tenant_admin",\n    "tenantId": "<tenant-id>"\n  }\n\nRoles: super_admin, tenant_admin, user\ntenantId is required for tenant_admin and user roles.'
   ).action(
     withErrorHandler(async (json, _opts, cmd) => {
@@ -3516,7 +3849,7 @@ function registerUsersCommand(parent) {
       command: "cat user.json | geonic admin users create"
     }
   ]);
-  const update = users.command("update <id> [json]").description(
+  const update = users.command("update <id> [json]").summary("Update a user").description(
     'Update a user\n\nJSON payload: only specified fields are updated.\n  e.g. {"role": "admin"}'
   ).action(
     withErrorHandler(
@@ -3548,7 +3881,7 @@ function registerUsersCommand(parent) {
       command: "cat user.json | geonic admin users update <user-id>"
     }
   ]);
-  const del = users.command("delete <id>").description("Delete a user").action(
+  const del = users.command("delete <id>").description("Permanently delete a user account. This revokes all access and cannot be undone").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3560,11 +3893,15 @@ function registerUsersCommand(parent) {
   );
   addExamples(del, [
     {
-      description: "Delete a user",
+      description: "Delete a user by ID",
       command: "geonic admin users delete <user-id>"
+    },
+    {
+      description: "Delete with verbose output",
+      command: "geonic admin users delete <user-id> --verbose"
     }
   ]);
-  const activate = users.command("activate <id>").description("Activate a user").action(
+  const activate = users.command("activate <id>").description("Activate a user account, allowing them to log in and access the API").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3576,11 +3913,11 @@ function registerUsersCommand(parent) {
   );
   addExamples(activate, [
     {
-      description: "Activate a user",
+      description: "Activate a deactivated user",
       command: "geonic admin users activate <user-id>"
     }
   ]);
-  const deactivate = users.command("deactivate <id>").description("Deactivate a user").action(
+  const deactivate = users.command("deactivate <id>").description("Deactivate a user account, preventing login until reactivated").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3592,11 +3929,11 @@ function registerUsersCommand(parent) {
   );
   addExamples(deactivate, [
     {
-      description: "Deactivate a user",
+      description: "Deactivate a user to suspend their access",
       command: "geonic admin users deactivate <user-id>"
     }
   ]);
-  const unlock = users.command("unlock <id>").description("Unlock a user").action(
+  const unlock = users.command("unlock <id>").description("Unlock a user account that was locked due to repeated failed login attempts").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3616,8 +3953,8 @@ function registerUsersCommand(parent) {
 
 // src/commands/admin/policies.ts
 function registerPoliciesCommand(parent) {
-  const policies = parent.command("policies").description("Manage policies");
-  const list = policies.command("list").description("List all policies").action(
+  const policies = parent.command("policies").description("Manage XACML access control policies");
+  const list = policies.command("list").description("List all access control policies, showing their status and priority").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3629,9 +3966,13 @@ function registerPoliciesCommand(parent) {
     {
       description: "List all policies",
       command: "geonic admin policies list"
+    },
+    {
+      description: "List policies in table format for an overview",
+      command: "geonic admin policies list --format table"
     }
   ]);
-  const get = policies.command("get <id>").description("Get a policy by ID").action(
+  const get = policies.command("get <id>").description("Get a policy's full details \u2014 target rules, effect, priority, and status").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3644,11 +3985,11 @@ function registerPoliciesCommand(parent) {
   );
   addExamples(get, [
     {
-      description: "Get a policy by ID",
+      description: "Inspect a policy's rules and target configuration",
       command: "geonic admin policies get <policy-id>"
     }
   ]);
-  const create = policies.command("create [json]").description(
+  const create = policies.command("create [json]").summary("Create a new policy").description(
     'Create a new policy\n\nJSON payload examples:\n\n  Allow all entities:\n  {\n    "description": "Allow all entities",\n    "rules": [{"ruleId": "allow-all", "effect": "Permit"}]\n  }\n\n  Allow GET access to a specific entity type:\n  {\n    "description": "Allow GET access to Landmark entities",\n    "target": {\n      "resources": [{"attributeId": "entityType", "matchValue": "Landmark"}],\n      "actions": [{"attributeId": "method", "matchValue": "GET"}]\n    },\n    "rules": [{"ruleId": "permit-get", "effect": "Permit"}]\n  }\n\nTarget fields:\n  subjects   \u2014 attributeId: role, userId, email, tenantId\n  resources  \u2014 attributeId: path, entityType, entityId, entityOwner, tenantService, servicePath\n  actions    \u2014 attributeId: method (GET, POST, PATCH, DELETE)\n\nEach element: {attributeId, matchValue, matchFunction?}\n  matchFunction: "string-equal" (default) | "string-regexp" | "glob"\n\nPriority: smaller value = higher precedence (e.g. priority 10 overrides user default at 100).\n  tenant_admin: minimum priority 10. user self-service (/me/policies): fixed at 100.\n\nDefault role policies (priority 100):\n  user \u2192 /v2/** and /ngsi-ld/** all methods Permit; other data APIs GET only\n  api_key \u2192 all Deny, anonymous \u2192 all Deny'
   ).action(
     withErrorHandler(async (json, _opts, cmd) => {
@@ -3688,7 +4029,7 @@ function registerPoliciesCommand(parent) {
       command: "cat policy.json | geonic admin policies create"
     }
   ]);
-  const update = policies.command("update <id> [json]").description(
+  const update = policies.command("update <id> [json]").summary("Update a policy").description(
     'Update a policy\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated policy"}'
   ).action(
     withErrorHandler(
@@ -3720,7 +4061,7 @@ function registerPoliciesCommand(parent) {
       command: "cat policy.json | geonic admin policies update <policy-id>"
     }
   ]);
-  const del = policies.command("delete <id>").description("Delete a policy").action(
+  const del = policies.command("delete <id>").description("Delete a policy. Users or API keys referencing this policy will lose the access it granted").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3732,11 +4073,11 @@ function registerPoliciesCommand(parent) {
   );
   addExamples(del, [
     {
-      description: "Delete a policy",
+      description: "Delete a policy by ID",
       command: "geonic admin policies delete <policy-id>"
     }
   ]);
-  const activate = policies.command("activate <id>").description("Activate a policy").action(
+  const activate = policies.command("activate <id>").description("Activate a policy so its access control rules are enforced").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3748,11 +4089,11 @@ function registerPoliciesCommand(parent) {
   );
   addExamples(activate, [
     {
-      description: "Activate a policy",
+      description: "Enable a policy to start enforcing its rules",
       command: "geonic admin policies activate <policy-id>"
     }
   ]);
-  const deactivate = policies.command("deactivate <id>").description("Deactivate a policy").action(
+  const deactivate = policies.command("deactivate <id>").description("Deactivate a policy, suspending its rules without deleting it").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3764,7 +4105,7 @@ function registerPoliciesCommand(parent) {
   );
   addExamples(deactivate, [
     {
-      description: "Deactivate a policy",
+      description: "Temporarily disable a policy without deleting it",
       command: "geonic admin policies deactivate <policy-id>"
     }
   ]);
@@ -3773,7 +4114,7 @@ function registerPoliciesCommand(parent) {
 // src/commands/admin/oauth-clients.ts
 function registerOAuthClientsCommand(parent) {
   const oauthClients = parent.command("oauth-clients").description("Manage OAuth clients");
-  const list = oauthClients.command("list").description("List all OAuth clients").action(
+  const list = oauthClients.command("list").description("List all registered OAuth clients and their configurations").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3785,9 +4126,13 @@ function registerOAuthClientsCommand(parent) {
     {
       description: "List all OAuth clients",
       command: "geonic admin oauth-clients list"
+    },
+    {
+      description: "List OAuth clients in table format",
+      command: "geonic admin oauth-clients list --format table"
     }
   ]);
-  const get = oauthClients.command("get <id>").description("Get an OAuth client by ID").action(
+  const get = oauthClients.command("get <id>").description("Get an OAuth client's details \u2014 name, client ID, policy, and redirect URIs").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3800,11 +4145,11 @@ function registerOAuthClientsCommand(parent) {
   );
   addExamples(get, [
     {
-      description: "Get an OAuth client by ID",
+      description: "Inspect an OAuth client's configuration",
       command: "geonic admin oauth-clients get <client-id>"
     }
   ]);
-  const create = oauthClients.command("create [json]").description(
+  const create = oauthClients.command("create [json]").summary("Create a new OAuth client").description(
     'Create a new OAuth client\n\nJSON payload example:\n  {\n    "name": "my-app",\n    "policyId": "<policy-id>"\n  }'
   ).action(
     withErrorHandler(async (json, _opts, cmd) => {
@@ -3832,7 +4177,7 @@ function registerOAuthClientsCommand(parent) {
       command: "cat client.json | geonic admin oauth-clients create"
     }
   ]);
-  const update = oauthClients.command("update <id> [json]").description(
+  const update = oauthClients.command("update <id> [json]").summary("Update an OAuth client").description(
     'Update an OAuth client\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated client"}'
   ).action(
     withErrorHandler(
@@ -3864,7 +4209,7 @@ function registerOAuthClientsCommand(parent) {
       command: "cat client.json | geonic admin oauth-clients update <client-id>"
     }
   ]);
-  const del = oauthClients.command("delete <id>").description("Delete an OAuth client").action(
+  const del = oauthClients.command("delete <id>").description("Delete an OAuth client. Existing tokens issued by this client will be invalidated").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -3876,14 +4221,14 @@ function registerOAuthClientsCommand(parent) {
   );
   addExamples(del, [
     {
-      description: "Delete an OAuth client",
+      description: "Delete an OAuth client by ID",
       command: "geonic admin oauth-clients delete <client-id>"
     }
   ]);
 }
 function registerCaddeCommand(parent) {
-  const cadde = parent.command("cadde").description("Manage CADDE configuration");
-  const caddeGet = cadde.command("get").description("Get CADDE configuration").action(
+  const cadde = parent.command("cadde").description("Manage CADDE (data exchange) configuration for cross-platform data sharing");
+  const caddeGet = cadde.command("get").description("Get the current CADDE data exchange configuration (provider, endpoint, etc.)").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -3893,11 +4238,15 @@ function registerCaddeCommand(parent) {
   );
   addExamples(caddeGet, [
     {
-      description: "Get CADDE configuration",
+      description: "View current CADDE configuration",
       command: "geonic admin cadde get"
+    },
+    {
+      description: "View CADDE configuration in table format",
+      command: "geonic admin cadde get --format table"
     }
   ]);
-  const caddeSet = cadde.command("set [json]").description(
+  const caddeSet = cadde.command("set [json]").summary("Set CADDE configuration").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) => {
@@ -3925,7 +4274,7 @@ function registerCaddeCommand(parent) {
       command: "cat cadde-config.json | geonic admin cadde set"
     }
   ]);
-  const caddeDelete = cadde.command("delete").description("Delete CADDE configuration").action(
+  const caddeDelete = cadde.command("delete").description("Remove the CADDE data exchange configuration, disabling cross-platform data sharing").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest("DELETE", "/admin/cadde");
@@ -3934,13 +4283,20 @@ function registerCaddeCommand(parent) {
   );
   addExamples(caddeDelete, [
     {
-      description: "Delete CADDE configuration",
+      description: "Remove CADDE configuration",
       command: "geonic admin cadde delete"
     }
   ]);
 }
 
 // src/commands/admin/api-keys.ts
+function cleanApiKeyData2(data) {
+  if (Array.isArray(data)) return data.map(cleanApiKeyData2);
+  if (typeof data !== "object" || data === null) return data;
+  const obj = { ...data };
+  if (obj.key === "******") delete obj.key;
+  return obj;
+}
 function validateOrigins(body, opts) {
   if (opts.origins !== void 0) {
     const origins = String(opts.origins).split(",").map((s) => s.trim()).filter(Boolean);
@@ -3979,9 +4335,41 @@ function buildBodyFromFlags(opts) {
   if (opts.tenantId) payload.tenantId = opts.tenantId;
   return payload;
 }
+function handleSaveKey2(data, cmd) {
+  const globalOpts = resolveOptions(cmd);
+  const key = data.key;
+  if (!key) {
+    printError("Response missing key. API key was created, but it could not be saved.");
+    process.exitCode = 1;
+    return false;
+  }
+  try {
+    const config = loadConfig(globalOpts.profile);
+    config.apiKey = key;
+    saveConfig(config, globalOpts.profile);
+    console.error("API key saved to config. X-Api-Key header will be sent automatically.");
+    return true;
+  } catch (err) {
+    printError(`Failed to save API key to config: ${err instanceof Error ? err.message : String(err)}`);
+    printApiKeyBox(key);
+    process.exitCode = 1;
+    return false;
+  }
+}
+function showKeyResult2(data, save, cmd) {
+  const key = data.key;
+  if (!key) {
+    printError("Response missing key. The new API key value was not returned.");
+    process.exitCode = 1;
+    return false;
+  }
+  if (save) return handleSaveKey2(data, cmd);
+  printApiKeyBox(key);
+  return true;
+}
 function registerApiKeysCommand(parent) {
   const apiKeys = parent.command("api-keys").description("Manage API keys");
-  const list = apiKeys.command("list").description("List all API keys").option("--tenant-id <id>", "Filter by tenant ID").action(
+  const list = apiKeys.command("list").description("List all API keys, showing name, tenant, policy, and status (key values are masked)").option("--tenant-id <id>", "Filter by tenant ID").action(
     withErrorHandler(async (_opts, cmd) => {
       const opts = cmd.opts();
       const client = createClient(cmd);
@@ -3991,7 +4379,9 @@ function registerApiKeysCommand(parent) {
       const response = await client.rawRequest("GET", "/admin/api-keys", {
         params
       });
+      response.data = cleanApiKeyData2(response.data);
       outputResponse(response, format);
+      console.error("\u203B API \u30AD\u30FC\u5024\u306F\u4F5C\u6210\u6642 (create) \u307E\u305F\u306F\u30EA\u30D5\u30EC\u30C3\u30B7\u30E5\u6642 (refresh) \u306B\u306E\u307F\u8868\u793A\u3055\u308C\u307E\u3059\u3002");
     })
   );
   addExamples(list, [
@@ -3999,12 +4389,16 @@ function registerApiKeysCommand(parent) {
       description: "List all API keys",
       command: "geonic admin api-keys list"
     },
+    {
+      description: "List API keys in table format",
+      command: "geonic admin api-keys list --format table"
+    },
     {
       description: "List API keys for a specific tenant",
       command: "geonic admin api-keys list --tenant-id <tenant-id>"
     }
   ]);
-  const get = apiKeys.command("get <keyId>").description("Get an API key by ID").action(
+  const get = apiKeys.command("get <keyId>").description("Get an API key's metadata \u2014 name, policy, allowed origins, and rate limit (key value is masked)").action(
     withErrorHandler(async (keyId, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4012,12 +4406,13 @@ function registerApiKeysCommand(parent) {
         "GET",
         `/admin/api-keys/${encodeURIComponent(String(keyId))}`
       );
+      response.data = cleanApiKeyData2(response.data);
       outputResponse(response, format);
     })
   );
   addExamples(get, [
     {
-      description: "Get an API key by ID",
+      description: "Inspect an API key's configuration",
       command: "geonic admin api-keys get <key-id>"
     }
   ]);
@@ -4040,24 +4435,9 @@ function registerApiKeysCommand(parent) {
         body
       });
       const data = response.data;
-      if (opts.save) {
-        const globalOpts = resolveOptions(cmd);
-        const key = data.key;
-        if (!key) {
-          printError("Response missing key. API key was created, but it could not be saved.");
-          outputResponse(response, format);
-          process.exitCode = 1;
-          return;
-        }
-        const config = loadConfig(globalOpts.profile);
-        config.apiKey = key;
-        saveConfig(config, globalOpts.profile);
-        console.error("API key saved to config. X-Api-Key header will be sent automatically.");
-      } else {
-        printWarning("Save the API key now \u2014 it will not be shown again. Use --save to store it automatically.");
-      }
+      const ok = showKeyResult2(data, !!opts.save, cmd);
       outputResponse(response, format);
-      console.error("API key created.");
+      if (ok) console.error("API key created.");
     })
   );
   addNotes(create, [
@@ -4078,6 +4458,35 @@ function registerApiKeysCommand(parent) {
       command: "geonic admin api-keys create @key.json --save"
     }
   ]);
+  const refresh = apiKeys.command("refresh <keyId>").description("Refresh (rotate) an API key \u2014 generates a new key value").option("--save", "Save the new API key to profile config").action(
+    withErrorHandler(async (keyId, _opts, cmd) => {
+      const opts = cmd.opts();
+      const client = createClient(cmd);
+      const format = getFormat(cmd);
+      const response = await client.rawRequest(
+        "POST",
+        `/admin/api-keys/${encodeURIComponent(String(keyId))}/refresh`
+      );
+      const data = response.data;
+      const ok = showKeyResult2(data, !!opts.save, cmd);
+      outputResponse(response, format);
+      if (ok) console.error("API key refreshed.");
+    })
+  );
+  addNotes(refresh, [
+    "Refreshing generates a new key value while keeping keyId, name, and policy settings.",
+    "The previous key value is immediately invalidated."
+  ]);
+  addExamples(refresh, [
+    {
+      description: "Refresh an API key",
+      command: "geonic admin api-keys refresh <key-id>"
+    },
+    {
+      description: "Refresh and save new key to config",
+      command: "geonic admin api-keys refresh <key-id> --save"
+    }
+  ]);
   const update = apiKeys.command("update <keyId> [json]").description("Update an API key").option("--name <name>", "Key name").option("--policy <policyId>", "Policy ID to attach").option("--origins <origins>", "Comma-separated origins").option("--rate-limit <n>", "Rate limit per minute").option("--dpop-required", "Require DPoP token binding").option("--no-dpop-required", "Disable DPoP token binding").action(
     withErrorHandler(
       async (keyId, json, _opts, cmd) => {
@@ -4130,7 +4539,7 @@ function registerApiKeysCommand(parent) {
       command: "geonic admin api-keys update <key-id> @key.json"
     }
   ]);
-  const del = apiKeys.command("delete <keyId>").description("Delete an API key").action(
+  const del = apiKeys.command("delete <keyId>").description("Delete an API key. Any requests using this key will be immediately rejected").action(
     withErrorHandler(async (keyId, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -4142,7 +4551,7 @@ function registerApiKeysCommand(parent) {
   );
   addExamples(del, [
     {
-      description: "Delete an API key",
+      description: "Delete an API key by ID",
       command: "geonic admin api-keys delete <key-id>"
     }
   ]);
@@ -4161,8 +4570,8 @@ function registerAdminCommand(program2) {
 
 // src/commands/rules.ts
 function registerRulesCommand(program2) {
-  const rules = program2.command("rules").description("Manage rule engine");
-  const list = rules.command("list").description("List all rules").action(
+  const rules = program2.command("rules").description("Manage ReactiveCore rules that trigger actions based on entity changes");
+  const list = rules.command("list").description("List all configured rules and their current status").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4172,11 +4581,15 @@ function registerRulesCommand(program2) {
   );
   addExamples(list, [
     {
-      description: "List all rules",
+      description: "List all rules as JSON",
       command: "geonic rules list"
+    },
+    {
+      description: "List rules in table format to review status at a glance",
+      command: "geonic rules list --format table"
     }
   ]);
-  const get = rules.command("get <id>").description("Get a rule by ID").action(
+  const get = rules.command("get <id>").description("Get a rule's full definition including conditions, actions, and status").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4189,11 +4602,15 @@ function registerRulesCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get a specific rule",
+      description: "Inspect a rule's conditions and actions",
       command: "geonic rules get <rule-id>"
+    },
+    {
+      description: "Get a rule and check if it is active",
+      command: "geonic rules get urn:ngsi-ld:Rule:high-temp-alert"
     }
   ]);
-  const create = rules.command("create [json]").description(
+  const create = rules.command("create [json]").summary("Create a new rule").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) => {
@@ -4219,7 +4636,7 @@ function registerRulesCommand(program2) {
       command: "cat rule.json | geonic rules create"
     }
   ]);
-  const update = rules.command("update <id> [json]").description(
+  const update = rules.command("update <id> [json]").summary("Update a rule").description(
     'Update a rule\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated rule"}'
   ).action(
     withErrorHandler(
@@ -4251,7 +4668,7 @@ function registerRulesCommand(program2) {
       command: "cat rule.json | geonic rules update <rule-id>"
     }
   ]);
-  const del = rules.command("delete <id>").description("Delete a rule").action(
+  const del = rules.command("delete <id>").description("Permanently delete a rule and stop its processing").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -4263,11 +4680,15 @@ function registerRulesCommand(program2) {
   );
   addExamples(del, [
     {
-      description: "Delete a rule",
+      description: "Delete a rule by ID",
       command: "geonic rules delete <rule-id>"
+    },
+    {
+      description: "Remove an obsolete alert rule",
+      command: "geonic rules delete urn:ngsi-ld:Rule:old-alert"
     }
   ]);
-  const activate = rules.command("activate <id>").description("Activate a rule").action(
+  const activate = rules.command("activate <id>").description("Enable a rule so it begins evaluating conditions and firing actions").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -4279,11 +4700,15 @@ function registerRulesCommand(program2) {
   );
   addExamples(activate, [
     {
-      description: "Activate a rule",
+      description: "Start processing a rule",
       command: "geonic rules activate <rule-id>"
+    },
+    {
+      description: "Re-enable a previously deactivated rule",
+      command: "geonic rules activate urn:ngsi-ld:Rule:high-temp-alert"
     }
   ]);
-  const deactivate = rules.command("deactivate <id>").description("Deactivate a rule").action(
+  const deactivate = rules.command("deactivate <id>").description("Disable a rule without deleting it, pausing condition evaluation and actions").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -4295,16 +4720,20 @@ function registerRulesCommand(program2) {
   );
   addExamples(deactivate, [
     {
-      description: "Deactivate a rule",
+      description: "Temporarily pause a rule during maintenance",
       command: "geonic rules deactivate <rule-id>"
+    },
+    {
+      description: "Disable a noisy alert rule without removing it",
+      command: "geonic rules deactivate urn:ngsi-ld:Rule:high-temp-alert"
     }
   ]);
 }
 
 // src/commands/models.ts
 function registerModelsCommand(program2) {
-  const models = program2.command("custom-data-models").alias("models").description("Manage custom data models");
-  const list = models.command("list").description("List all models").action(
+  const models = program2.command("custom-data-models").alias("models").description("Manage custom data models that define entity type schemas and property constraints");
+  const list = models.command("list").description("List all registered data models for the current tenant").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4314,11 +4743,15 @@ function registerModelsCommand(program2) {
   );
   addExamples(list, [
     {
-      description: "List all models",
+      description: "List all data models as JSON",
       command: "geonic models list"
+    },
+    {
+      description: "Browse available data models in table format",
+      command: "geonic models list --format table"
     }
   ]);
-  const get = models.command("get <id>").description("Get a model by ID").action(
+  const get = models.command("get <id>").description("Get a data model's full schema including property definitions and constraints").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4331,11 +4764,15 @@ function registerModelsCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get a specific model",
+      description: "Inspect a model's property definitions",
       command: "geonic models get <model-id>"
+    },
+    {
+      description: "View the schema for a Sensor data model",
+      command: "geonic models get urn:ngsi-ld:DataModel:Sensor"
     }
   ]);
-  const create = models.command("create [json]").description(
+  const create = models.command("create [json]").summary("Create a new model").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) => {
@@ -4361,7 +4798,7 @@ function registerModelsCommand(program2) {
       command: "cat model.json | geonic models create"
     }
   ]);
-  const update = models.command("update <id> [json]").description(
+  const update = models.command("update <id> [json]").summary("Update a model").description(
     'Update a model\n\nJSON payload: only specified fields are updated.\n  e.g. {"description": "Updated model"}'
   ).action(
     withErrorHandler(
@@ -4393,7 +4830,7 @@ function registerModelsCommand(program2) {
       command: "cat model.json | geonic models update <model-id>"
     }
   ]);
-  const del = models.command("delete <id>").description("Delete a model").action(
+  const del = models.command("delete <id>").description("Delete a data model definition (does not affect existing entities)").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       await client.rawRequest(
@@ -4405,16 +4842,20 @@ function registerModelsCommand(program2) {
   );
   addExamples(del, [
     {
-      description: "Delete a model",
+      description: "Delete a data model by ID",
       command: "geonic models delete <model-id>"
+    },
+    {
+      description: "Remove a deprecated model definition",
+      command: "geonic models delete urn:ngsi-ld:DataModel:LegacySensor"
     }
   ]);
 }
 
 // src/commands/catalog.ts
 function registerCatalogCommand(program2) {
-  const catalog = program2.command("catalog").description("Browse DCAT-AP catalog");
-  const get = catalog.command("get").description("Get the catalog").action(
+  const catalog = program2.command("catalog").description("Browse the DCAT-AP data catalog for discovering and previewing datasets");
+  const get = catalog.command("get").description("Get the DCAT-AP catalog metadata including title, publisher, and dataset count").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4424,12 +4865,16 @@ function registerCatalogCommand(program2) {
   );
   addExamples(get, [
     {
-      description: "Get the DCAT-AP catalog",
+      description: "View catalog metadata (title, publisher, datasets summary)",
       command: "geonic catalog get"
+    },
+    {
+      description: "Get catalog metadata in table format",
+      command: "geonic catalog get --format table"
     }
   ]);
-  const datasets = catalog.command("datasets").description("Manage catalog datasets");
-  const datasetsList = datasets.command("list").description("List all datasets").action(
+  const datasets = catalog.command("datasets").description("List, inspect, and preview datasets published in the catalog");
+  const datasetsList = datasets.command("list").description("List all datasets published in the catalog").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4439,11 +4884,15 @@ function registerCatalogCommand(program2) {
   );
   addExamples(datasetsList, [
     {
-      description: "List all catalog datasets",
+      description: "List all catalog datasets as JSON",
       command: "geonic catalog datasets list"
+    },
+    {
+      description: "Browse datasets in table format",
+      command: "geonic catalog datasets list --format table"
     }
   ]);
-  const datasetsGet = datasets.command("get <id>").description("Get a dataset by ID").action(
+  const datasetsGet = datasets.command("get <id>").description("Get a dataset's metadata including description, distributions, and license").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4456,11 +4905,15 @@ function registerCatalogCommand(program2) {
   );
   addExamples(datasetsGet, [
     {
-      description: "Get a specific dataset",
+      description: "Inspect a dataset's metadata and distributions",
       command: "geonic catalog datasets get <dataset-id>"
+    },
+    {
+      description: "View dataset details including license and publisher",
+      command: "geonic catalog datasets get urn:ngsi-ld:Dataset:weather-stations"
     }
   ]);
-  const datasetsSample = datasets.command("sample <id>").description("Get sample data for a dataset").action(
+  const datasetsSample = datasets.command("sample <id>").description("Preview sample entities from a dataset to understand its structure and content").action(
     withErrorHandler(async (id, _opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4473,8 +4926,12 @@ function registerCatalogCommand(program2) {
   );
   addExamples(datasetsSample, [
     {
-      description: "Get sample data for a dataset",
+      description: "Preview sample entities from a dataset",
       command: "geonic catalog datasets sample <dataset-id>"
+    },
+    {
+      description: "Preview data in table format to quickly assess content",
+      command: "geonic catalog datasets sample <dataset-id> --format table"
     }
   ]);
 }
@@ -4482,7 +4939,7 @@ function registerCatalogCommand(program2) {
 // src/commands/health.ts
 import { createRequire } from "module";
 function registerHealthCommand(program2) {
-  const health = program2.command("health").description("Check the health status of the server").action(
+  const health = program2.command("health").description("Check Context Broker connectivity and health status").action(
     withErrorHandler(async (_opts, cmd) => {
       const client = createClient(cmd);
       const format = getFormat(cmd);
@@ -4494,11 +4951,19 @@ function registerHealthCommand(program2) {
     {
       description: "Check server health",
       command: "geonic health"
+    },
+    {
+      description: "Check health with table output",
+      command: "geonic health --format table"
+    },
+    {
+      description: "Check health of a specific server",
+      command: "geonic health --url https://api.example.com"
     }
   ]);
 }
 function registerVersionCommand(program2) {
-  const version = program2.command("version").description("Display CLI and server version information").action(
+  const version = program2.command("version").description("Display both CLI and server version information").action(
     withErrorHandler(async (_opts, cmd) => {
       const require2 = createRequire(import.meta.url);
       const pkg = require2("../package.json");
@@ -4515,11 +4980,16 @@ function registerVersionCommand(program2) {
     {
       description: "Show CLI and server version",
       command: "geonic version"
+    },
+    {
+      description: "Show version as JSON",
+      command: "geonic version --format json"
     }
   ]);
 }
 
 // src/commands/cli.ts
+import { execSync } from "child_process";
 import { createRequire as createRequire2 } from "module";
 function findOption(cmd, program2, flag) {
   return cmd.options.find((o) => o.long === flag || o.short === flag) || program2.options.find((o) => o.long === flag || o.short === flag);
@@ -4685,15 +5155,43 @@ function registerCliCommand(program2) {
       command: `echo 'eval "$(geonic cli completions zsh)"' >> ~/.zshrc`
     }
   ]);
-  const version = cli.command("version").description("Display the CLI version").action(() => {
+  const version = cli.command("version").description("Display the currently installed CLI version").action(() => {
     const require2 = createRequire2(import.meta.url);
     const pkg = require2("../package.json");
     console.log(pkg.version);
   });
   addExamples(version, [
     {
-      description: "Show CLI version",
+      description: "Show the installed version",
       command: "geonic cli version"
+    },
+    {
+      description: "Use in scripts to check the installed version",
+      command: 'echo "geonic $(geonic cli version)"'
+    }
+  ]);
+  const update = cli.command("update").description("Update the CLI to the latest version via npm (requires global install)").action(
+    withErrorHandler(async (...args) => {
+      const cmd = args[args.length - 1];
+      const opts = resolveOptions(cmd);
+      const updateCommand = "npm update -g @geolonia/geonicdb-cli";
+      if (opts.dryRun) {
+        printInfo(`[dry-run] ${updateCommand}`);
+        return;
+      }
+      printInfo("Updating @geolonia/geonicdb-cli...");
+      execSync(updateCommand, { stdio: "inherit" });
+      printSuccess("Update complete.");
+    })
+  );
+  addExamples(update, [
+    {
+      description: "Update CLI to the latest version",
+      command: "geonic cli update"
+    },
+    {
+      description: "Preview the update command without executing it",
+      command: "geonic cli update --dry-run"
     }
   ]);
 }