Merge pull request #96 from geolonia/feat/improve-help-content

docs: 全コマンドの help content を充実

Author: miya0001

CHANGELOG.md

@@ -8,6 +8,7 @@
 ## [Unreleased]
 
 ### 2026-04-03
+- **Docs**: 全コマンドの help 内容を充実 — description の具体化、examples の追加（テーブル形式、プロフィルスコープ、ユースケース別の例）、24 ファイル改善 (#96)
 - **Feat**: マルチテナント対応 — ログイン時のテナント名指定 (`-s <テナント名>`)、`tenantId` / `availableTenants` の config 保存、`profile use` 時のトークン自動リフレッシュ (#90)
 - **Feat**: `geonic cli update` コマンドを追加 — `npm update -g` のエイリアスとして CLI を最新版に更新可能に (#94)
 - **Fix**: 複数ターミナルで同一プロファイルを使用時、refresh token rotation によりセッションが無効化される問題を修正 — トークンリフレッシュ前に config を再読み込みし、別プロセスが既にリフレッシュ済みならそのトークンを使用する (#93)

src/commands/admin/api-keys.ts

@@ -107,7 +107,7 @@ export function registerApiKeysCommand(parent: Command): void {
   // api-keys list
   const list = apiKeys
     .command("list")
-    .description("List all API keys")
+    .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: unknown, cmd: Command) => {
@@ -130,6 +130,10 @@ export function registerApiKeysCommand(parent: Command): void {
       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>",
@@ -139,7 +143,7 @@ export function registerApiKeysCommand(parent: Command): void {
   // api-keys get
   const get = apiKeys
     .command("get <keyId>")
-    .description("Get an API key by ID")
+    .description("Get an API key's metadata — name, policy, allowed origins, and rate limit (key value is masked)")
     .action(
       withErrorHandler(async (keyId: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -155,7 +159,7 @@ export function registerApiKeysCommand(parent: Command): void {
 
   addExamples(get, [
     {
-      description: "Get an API key by ID",
+      description: "Inspect an API key's configuration",
       command: "geonic admin api-keys get <key-id>",
     },
   ]);
@@ -346,7 +350,7 @@ export function registerApiKeysCommand(parent: Command): void {
   // api-keys delete
   const del = apiKeys
     .command("delete <keyId>")
-    .description("Delete an API key")
+    .description("Delete an API key. Any requests using this key will be immediately rejected")
     .action(
       withErrorHandler(async (keyId: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -360,7 +364,7 @@ export function registerApiKeysCommand(parent: Command): void {
 
   addExamples(del, [
     {
-      description: "Delete an API key",
+      description: "Delete an API key by ID",
       command: "geonic admin api-keys delete <key-id>",
     },
   ]);

src/commands/admin/oauth-clients.ts

@@ -12,7 +12,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
   // oauth-clients list
   const list = oauthClients
     .command("list")
-    .description("List all OAuth clients")
+    .description("List all registered OAuth clients and their configurations")
     .action(
       withErrorHandler(async (_opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -27,12 +27,16 @@ export function registerOAuthClientsCommand(parent: Command): void {
       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",
+    },
   ]);
 
   // oauth-clients get
   const get = oauthClients
     .command("get <id>")
-    .description("Get an OAuth client by ID")
+    .description("Get an OAuth client's details — name, client ID, policy, and redirect URIs")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -47,14 +51,15 @@ export function registerOAuthClientsCommand(parent: Command): void {
 
   addExamples(get, [
     {
-      description: "Get an OAuth client by ID",
+      description: "Inspect an OAuth client's configuration",
       command: "geonic admin oauth-clients get <client-id>",
     },
   ]);
 
   // oauth-clients create
   const create = oauthClients
     .command("create [json]")
+    .summary("Create a new OAuth client")
     .description(
       "Create a new OAuth client\n\n" +
         "JSON payload example:\n" +
@@ -94,6 +99,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
   // oauth-clients update
   const update = oauthClients
     .command("update <id> [json]")
+    .summary("Update an OAuth client")
     .description(
       "Update an OAuth client\n\n" +
         "JSON payload: only specified fields are updated.\n" +
@@ -134,7 +140,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
   // oauth-clients delete
   const del = oauthClients
     .command("delete <id>")
-    .description("Delete an OAuth client")
+    .description("Delete an OAuth client. Existing tokens issued by this client will be invalidated")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -148,7 +154,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
 
   addExamples(del, [
     {
-      description: "Delete an OAuth client",
+      description: "Delete an OAuth client by ID",
       command: "geonic admin oauth-clients delete <client-id>",
     },
   ]);
@@ -157,12 +163,12 @@ export function registerOAuthClientsCommand(parent: Command): void {
 export function registerCaddeCommand(parent: Command): void {
   const cadde = parent
     .command("cadde")
-    .description("Manage CADDE configuration");
+    .description("Manage CADDE (data exchange) configuration for cross-platform data sharing");
 
   // cadde get
   const caddeGet = cadde
     .command("get")
-    .description("Get CADDE configuration")
+    .description("Get the current CADDE data exchange configuration (provider, endpoint, etc.)")
     .action(
       withErrorHandler(async (_opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -174,14 +180,19 @@ export function registerCaddeCommand(parent: Command): void {
 
   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",
+    },
   ]);
 
   // cadde set
   const caddeSet = cadde
     .command("set [json]")
+    .summary("Set CADDE configuration")
     .description(
       "Set CADDE configuration\n\n" +
         "JSON payload example:\n" +
@@ -221,7 +232,7 @@ export function registerCaddeCommand(parent: Command): void {
   // cadde delete
   const caddeDelete = cadde
     .command("delete")
-    .description("Delete CADDE configuration")
+    .description("Remove the CADDE data exchange configuration, disabling cross-platform data sharing")
     .action(
       withErrorHandler(async (_opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -232,7 +243,7 @@ export function registerCaddeCommand(parent: Command): void {
 
   addExamples(caddeDelete, [
     {
-      description: "Delete CADDE configuration",
+      description: "Remove CADDE configuration",
       command: "geonic admin cadde delete",
     },
   ]);

src/commands/admin/policies.ts

@@ -7,12 +7,12 @@ import { addExamples } from "../help.js";
 export function registerPoliciesCommand(parent: Command): void {
   const policies = parent
     .command("policies")
-    .description("Manage policies");
+    .description("Manage XACML access control policies");
 
   // policies list
   const list = policies
     .command("list")
-    .description("List all policies")
+    .description("List all access control policies, showing their status and priority")
     .action(
       withErrorHandler(async (_opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -27,12 +27,16 @@ export function registerPoliciesCommand(parent: Command): void {
       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",
+    },
   ]);
 
   // policies get
   const get = policies
     .command("get <id>")
-    .description("Get a policy by ID")
+    .description("Get a policy's full details — target rules, effect, priority, and status")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -47,14 +51,15 @@ export function registerPoliciesCommand(parent: Command): void {
 
   addExamples(get, [
     {
-      description: "Get a policy by ID",
+      description: "Inspect a policy's rules and target configuration",
       command: "geonic admin policies get <policy-id>",
     },
   ]);
 
   // policies create
   const create = policies
     .command("create [json]")
+    .summary("Create a new policy")
     .description(
       "Create a new policy\n\n" +
         "JSON payload examples:\n\n" +
@@ -127,6 +132,7 @@ export function registerPoliciesCommand(parent: Command): void {
   // policies update
   const update = policies
     .command("update <id> [json]")
+    .summary("Update a policy")
     .description(
       "Update a policy\n\n" +
         "JSON payload: only specified fields are updated.\n" +
@@ -167,7 +173,7 @@ export function registerPoliciesCommand(parent: Command): void {
   // policies delete
   const del = policies
     .command("delete <id>")
-    .description("Delete a policy")
+    .description("Delete a policy. Users or API keys referencing this policy will lose the access it granted")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -181,15 +187,15 @@ export function registerPoliciesCommand(parent: Command): void {
 
   addExamples(del, [
     {
-      description: "Delete a policy",
+      description: "Delete a policy by ID",
       command: "geonic admin policies delete <policy-id>",
     },
   ]);
 
   // policies activate
   const activate = policies
     .command("activate <id>")
-    .description("Activate a policy")
+    .description("Activate a policy so its access control rules are enforced")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -203,15 +209,15 @@ export function registerPoliciesCommand(parent: Command): void {
 
   addExamples(activate, [
     {
-      description: "Activate a policy",
+      description: "Enable a policy to start enforcing its rules",
       command: "geonic admin policies activate <policy-id>",
     },
   ]);
 
   // policies deactivate
   const deactivate = policies
     .command("deactivate <id>")
-    .description("Deactivate a policy")
+    .description("Deactivate a policy, suspending its rules without deleting it")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -225,7 +231,7 @@ export function registerPoliciesCommand(parent: Command): void {
 
   addExamples(deactivate, [
     {
-      description: "Deactivate a policy",
+      description: "Temporarily disable a policy without deleting it",
       command: "geonic admin policies deactivate <policy-id>",
     },
   ]);