docs: 全 JSON 入力コマンドのヘルプを改善

CHANGELOG.md

@@ -7,6 +7,12 @@
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-03-17
+
+### 2026-03-17
+- **Docs**: 全 JSON 入力コマンドのヘルプを改善 — description に JSON payload example を追加、examples にインライン JSON・stdin pipe・interactive mode の具体例を追加 (#72)
+- **Fix**: E2E テストの `performLogin` にリトライとトークン検証を追加 — DB クリーンアップ後のレースコンディションによるフレーキーテストを修正 (#72)
+
 ## [0.6.1] - 2026-03-13
 
 ### 2026-03-12
@@ -112,7 +118,8 @@
 ### 2026-02-26
 - **Docs**: README にインストール手順・使い方・コマンドリファレンスを追加 (#1)
 
-[Unreleased]: https://github.com/geolonia/geonicdb-cli/compare/v0.6.1...HEAD
+[Unreleased]: https://github.com/geolonia/geonicdb-cli/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/geolonia/geonicdb-cli/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/geolonia/geonicdb-cli/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/geolonia/geonicdb-cli/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/geolonia/geonicdb-cli/compare/v0.4.1...v0.5.0

src/commands/admin/oauth-clients.ts

@@ -55,7 +55,14 @@ export function registerOAuthClientsCommand(parent: Command): void {
   // oauth-clients create
   const create = oauthClients
     .command("create [json]")
-    .description("Create a new OAuth client")
+    .description(
+      "Create a new OAuth client\n\n" +
+        "JSON payload example:\n" +
+        "  {\n" +
+        '    "clientName": "my-app",\n' +
+        '    "allowedScopes": ["read:entities", "write:entities"]\n' +
+        "  }",
+    )
     .action(
       withErrorHandler(async (json: unknown, _opts: unknown, cmd: Command) => {
         const body = await parseJsonInput(json as string | undefined);
@@ -71,15 +78,27 @@ export function registerOAuthClientsCommand(parent: Command): void {
 
   addExamples(create, [
     {
-      description: "Create an OAuth client from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin oauth-clients create '{"clientName":"my-app","allowedScopes":["read:entities","write:entities"]}'`,
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin oauth-clients create @client.json",
     },
+    {
+      description: "Create from stdin pipe",
+      command: "cat client.json | geonic admin oauth-clients create",
+    },
   ]);
 
   // oauth-clients update
   const update = oauthClients
     .command("update <id> [json]")
-    .description("Update an OAuth client")
+    .description(
+      "Update an OAuth client\n\n" +
+        "JSON payload: only specified fields are updated.\n" +
+        '  e.g. {"description": "Updated client"}',
+    )
     .action(
       withErrorHandler(
         async (id: unknown, json: unknown, _opts: unknown, cmd: Command) => {
@@ -99,9 +118,17 @@ export function registerOAuthClientsCommand(parent: Command): void {
 
   addExamples(update, [
     {
-      description: "Update an OAuth client from a JSON file",
+      description: "Update description",
+      command: `geonic admin oauth-clients update <client-id> '{"description":"Updated client"}'`,
+    },
+    {
+      description: "Update from a JSON file",
       command: "geonic admin oauth-clients update <client-id> @client.json",
     },
+    {
+      description: "Update from stdin pipe",
+      command: "cat client.json | geonic admin oauth-clients update <client-id>",
+    },
   ]);
 
   // oauth-clients delete
@@ -155,7 +182,14 @@ export function registerCaddeCommand(parent: Command): void {
   // cadde set
   const caddeSet = cadde
     .command("set [json]")
-    .description("Set CADDE configuration")
+    .description(
+      "Set CADDE configuration\n\n" +
+        "JSON payload example:\n" +
+        "  {\n" +
+        '    "provider": "my-provider",\n' +
+        '    "endpoint": "http://localhost:6000"\n' +
+        "  }",
+    )
     .action(
       withErrorHandler(async (json: unknown, _opts: unknown, cmd: Command) => {
         const body = await parseJsonInput(json as string | undefined);
@@ -171,9 +205,17 @@ export function registerCaddeCommand(parent: Command): void {
 
   addExamples(caddeSet, [
     {
-      description: "Set CADDE configuration from a JSON file",
+      description: "Set with inline JSON",
+      command: `geonic admin cadde set '{"provider":"my-provider","endpoint":"http://localhost:6000"}'`,
+    },
+    {
+      description: "Set from a JSON file",
       command: "geonic admin cadde set @cadde-config.json",
     },
+    {
+      description: "Set from stdin pipe",
+      command: "cat cadde-config.json | geonic admin cadde set",
+    },
   ]);
 
   // cadde delete

src/commands/admin/policies.ts

@@ -55,7 +55,14 @@ export function registerPoliciesCommand(parent: Command): void {
   // policies create
   const create = policies
     .command("create [json]")
-    .description("Create a new policy")
+    .description(
+      "Create a new policy\n\n" +
+        "JSON payload example:\n" +
+        "  {\n" +
+        '    "description": "Allow all entities",\n' +
+        '    "rules": [{"ruleId": "allow-all", "effect": "Permit"}]\n' +
+        "  }",
+    )
     .action(
       withErrorHandler(async (json: unknown, _opts: unknown, cmd: Command) => {
         const body = await parseJsonInput(json as string | undefined);
@@ -71,15 +78,27 @@ export function registerPoliciesCommand(parent: Command): void {
 
   addExamples(create, [
     {
-      description: "Create a policy from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin policies create '{"description":"Allow all entities","rules":[{"ruleId":"allow-all","effect":"Permit"}]}'`,
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin policies create @policy.json",
     },
+    {
+      description: "Create from stdin pipe",
+      command: "cat policy.json | geonic admin policies create",
+    },
   ]);
 
   // policies update
   const update = policies
     .command("update <id> [json]")
-    .description("Update a policy")
+    .description(
+      "Update a policy\n\n" +
+        "JSON payload: only specified fields are updated.\n" +
+        '  e.g. {"description": "Updated policy"}',
+    )
     .action(
       withErrorHandler(
         async (id: unknown, json: unknown, _opts: unknown, cmd: Command) => {
@@ -99,9 +118,17 @@ export function registerPoliciesCommand(parent: Command): void {
 
   addExamples(update, [
     {
-      description: "Update a policy from a JSON file",
+      description: "Update description",
+      command: `geonic admin policies update <policy-id> '{"description":"Updated policy"}'`,
+    },
+    {
+      description: "Update from a JSON file",
       command: "geonic admin policies update <policy-id> @policy.json",
     },
+    {
+      description: "Update from stdin pipe",
+      command: "cat policy.json | geonic admin policies update <policy-id>",
+    },
   ]);
 
   // policies delete

src/commands/admin/tenants.ts

@@ -55,7 +55,14 @@ export function registerTenantsCommand(parent: Command): void {
   // tenants create
   const create = tenants
     .command("create [json]")
-    .description("Create a new tenant")
+    .description(
+      "Create a new tenant\n\n" +
+        "JSON payload example:\n" +
+        "  {\n" +
+        '    "name": "production",\n' +
+        '    "description": "Production environment tenant"\n' +
+        "  }",
+    )
     .action(
       withErrorHandler(async (json: unknown, _opts: unknown, cmd: Command) => {
         const body = await parseJsonInput(json as string | undefined);
@@ -71,15 +78,35 @@ export function registerTenantsCommand(parent: Command): void {
 
   addExamples(create, [
     {
-      description: "Create a tenant from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin tenants create '{"name":"my-tenant","description":"My first tenant"}'`,
+    },
+    {
+      description: "Minimal (name only)",
+      command: `geonic admin tenants create '{"name":"production"}'`,
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin tenants create @tenant.json",
     },
+    {
+      description: "Create from stdin pipe",
+      command: "cat tenant.json | geonic admin tenants create",
+    },
+    {
+      description: "Interactive mode (omit JSON argument)",
+      command: "geonic admin tenants create",
+    },
   ]);
 
   // tenants update
   const update = tenants
     .command("update <id> [json]")
-    .description("Update a tenant")
+    .description(
+      "Update a tenant\n\n" +
+        "JSON payload: only specified fields are updated.\n" +
+        '  e.g. {"name": "new-name", "description": "Updated description"}',
+    )
     .action(
       withErrorHandler(
         async (id: unknown, json: unknown, _opts: unknown, cmd: Command) => {
@@ -99,8 +126,24 @@ export function registerTenantsCommand(parent: Command): void {
 
   addExamples(update, [
     {
-      description: "Update a tenant from a JSON file",
-      command: "geonic admin tenants update <tenant-id> @tenant.json",
+      description: "Update description with inline JSON",
+      command: `geonic admin tenants update <tenant-id> '{"description":"Updated description"}'`,
+    },
+    {
+      description: "Rename a tenant",
+      command: `geonic admin tenants update <tenant-id> '{"name":"new-name"}'`,
+    },
+    {
+      description: "Update from a JSON file",
+      command: "geonic admin tenants update <tenant-id> @patch.json",
+    },
+    {
+      description: "Update from stdin pipe",
+      command: "cat patch.json | geonic admin tenants update <tenant-id>",
+    },
+    {
+      description: "Interactive mode",
+      command: "geonic admin tenants update <tenant-id>",
     },
   ]);
 

src/commands/admin/users.ts

@@ -55,7 +55,15 @@ export function registerUsersCommand(parent: Command): void {
   // users create
   const create = users
     .command("create [json]")
-    .description("Create a new user")
+    .description(
+      "Create a new user\n\n" +
+        "JSON payload example:\n" +
+        "  {\n" +
+        '    "email": "user@example.com",\n' +
+        '    "password": "SecurePassword123!",\n' +
+        '    "role": "super_admin"\n' +
+        "  }",
+    )
     .action(
       withErrorHandler(async (json: unknown, _opts: unknown, cmd: Command) => {
         const body = await parseJsonInput(json as string | undefined);
@@ -71,15 +79,27 @@ export function registerUsersCommand(parent: Command): void {
 
   addExamples(create, [
     {
-      description: "Create a user from a JSON file",
+      description: "Create with inline JSON",
+      command: `geonic admin users create '{"email":"user@example.com","password":"SecurePassword123!","role":"super_admin"}'`,
+    },
+    {
+      description: "Create from a JSON file",
       command: "geonic admin users create @user.json",
     },
+    {
+      description: "Create from stdin pipe",
+      command: "cat user.json | geonic admin users create",
+    },
   ]);
 
   // users update
   const update = users
     .command("update <id> [json]")
-    .description("Update a user")
+    .description(
+      "Update a user\n\n" +
+        "JSON payload: only specified fields are updated.\n" +
+        '  e.g. {"role": "admin"}',
+    )
     .action(
       withErrorHandler(
         async (id: unknown, json: unknown, _opts: unknown, cmd: Command) => {
@@ -99,9 +119,17 @@ export function registerUsersCommand(parent: Command): void {
 
   addExamples(update, [
     {
-      description: "Update a user from a JSON file",
+      description: "Update role with inline JSON",
+      command: `geonic admin users update <user-id> '{"role":"admin"}'`,
+    },
+    {
+      description: "Update from a JSON file",
       command: "geonic admin users update <user-id> @user.json",
     },
+    {
+      description: "Update from stdin pipe",
+      command: "cat user.json | geonic admin users update <user-id>",
+    },
   ]);
 
   // users delete

src/commands/attrs.ts

@@ -71,7 +71,11 @@ export function addAttrsSubcommands(attrs: Command): void {
   // attrs add
   const add = attrs
     .command("add")
-    .description("Add attributes to an entity")
+    .description(
+      "Add attributes to an entity\n\n" +
+        "JSON 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(
@@ -95,16 +99,28 @@ export function addAttrsSubcommands(attrs: Command): void {
     );
 
   addExamples(add, [
+    {
+      description: "Add an attribute with inline JSON",
+      command: `geonic entities attrs add urn:ngsi-ld:Sensor:001 '{"humidity":{"type":"Property","value":60}}'`,
+    },
     {
       description: "Add attributes from a file",
       command: "geonic entities attrs add urn:ngsi-ld:Sensor:001 @attrs.json",
     },
+    {
+      description: "Add from stdin pipe",
+      command: "cat attrs.json | geonic entities attrs add urn:ngsi-ld:Sensor:001",
+    },
   ]);
 
   // attrs update
   const attrUpdate = attrs
     .command("update")
-    .description("Update a specific attribute of an entity")
+    .description(
+      "Update a specific attribute of an entity\n\n" +
+        "JSON 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)")
@@ -131,9 +147,12 @@ export function addAttrsSubcommands(attrs: Command): void {
 
   addExamples(attrUpdate, [
     {
-      description: "Update a specific attribute",
-      command:
-        "geonic entities attrs update urn:ngsi-ld:Sensor:001 temperature '{\"value\":25}'",
+      description: "Update a Property value",
+      command: `geonic entities attrs update urn:ngsi-ld:Sensor:001 temperature '{"type":"Property","value":25}'`,
+    },
+    {
+      description: "Update from a file",
+      command: "geonic entities attrs update urn:ngsi-ld:Sensor:001 temperature @attr.json",
     },
   ]);