Skip to content

Commit 1d1905a

Browse files
miya0001miya0001
committed
docs: 全コマンドの help content を充実
全 24 コマンドファイルの description と examples を改善: - 各コマンドの description を具体的に（何が返るか、いつ使うか） - thin だった get/delete/list 等に table format や profile-scoped の例を追加 - admin コマンドに破壊的操作の注意書きを追加 - auth/profile に auto-refresh やテナント切り替えの文脈を追加 - catalog/snapshots/rules/models 等の説明を大幅に充実
1 parent 53ab96f commit 1d1905a

24 files changed

Lines changed: 398 additions & 132 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
## [Unreleased]
99

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

‎src/commands/admin/api-keys.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ export function registerApiKeysCommand(parent: Command): void {
107107
// api-keys list
108108
const list = apiKeys
109109
.command("list")
110-
.description("List all API keys")
110+
.description("List all API keys, showing name, tenant, policy, and status (key values are masked)")
111111
.option("--tenant-id <id>", "Filter by tenant ID")
112112
.action(
113113
withErrorHandler(async (_opts: unknown, cmd: Command) => {
@@ -130,6 +130,10 @@ export function registerApiKeysCommand(parent: Command): void {
130130
description: "List all API keys",
131131
command: "geonic admin api-keys list",
132132
},
133+
{
134+
description: "List API keys in table format",
135+
command: "geonic admin api-keys list --format table",
136+
},
133137
{
134138
description: "List API keys for a specific tenant",
135139
command: "geonic admin api-keys list --tenant-id <tenant-id>",
@@ -139,7 +143,7 @@ export function registerApiKeysCommand(parent: Command): void {
139143
// api-keys get
140144
const get = apiKeys
141145
.command("get <keyId>")
142-
.description("Get an API key by ID")
146+
.description("Get an API key's metadata — name, policy, allowed origins, and rate limit (key value is masked)")
143147
.action(
144148
withErrorHandler(async (keyId: unknown, _opts: unknown, cmd: Command) => {
145149
const client = createClient(cmd);
@@ -155,7 +159,7 @@ export function registerApiKeysCommand(parent: Command): void {
155159

156160
addExamples(get, [
157161
{
158-
description: "Get an API key by ID",
162+
description: "Inspect an API key's configuration",
159163
command: "geonic admin api-keys get <key-id>",
160164
},
161165
]);
@@ -346,7 +350,7 @@ export function registerApiKeysCommand(parent: Command): void {
346350
// api-keys delete
347351
const del = apiKeys
348352
.command("delete <keyId>")
349-
.description("Delete an API key")
353+
.description("Delete an API key. Any requests using this key will be immediately rejected")
350354
.action(
351355
withErrorHandler(async (keyId: unknown, _opts: unknown, cmd: Command) => {
352356
const client = createClient(cmd);
@@ -360,7 +364,7 @@ export function registerApiKeysCommand(parent: Command): void {
360364

361365
addExamples(del, [
362366
{
363-
description: "Delete an API key",
367+
description: "Delete an API key by ID",
364368
command: "geonic admin api-keys delete <key-id>",
365369
},
366370
]);

‎src/commands/admin/oauth-clients.ts‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
1212
// oauth-clients list
1313
const list = oauthClients
1414
.command("list")
15-
.description("List all OAuth clients")
15+
.description("List all registered OAuth clients and their configurations")
1616
.action(
1717
withErrorHandler(async (_opts: unknown, cmd: Command) => {
1818
const client = createClient(cmd);
@@ -27,12 +27,16 @@ export function registerOAuthClientsCommand(parent: Command): void {
2727
description: "List all OAuth clients",
2828
command: "geonic admin oauth-clients list",
2929
},
30+
{
31+
description: "List OAuth clients in table format",
32+
command: "geonic admin oauth-clients list --format table",
33+
},
3034
]);
3135

3236
// oauth-clients get
3337
const get = oauthClients
3438
.command("get <id>")
35-
.description("Get an OAuth client by ID")
39+
.description("Get an OAuth client's details — name, client ID, policy, and redirect URIs")
3640
.action(
3741
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
3842
const client = createClient(cmd);
@@ -47,7 +51,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
4751

4852
addExamples(get, [
4953
{
50-
description: "Get an OAuth client by ID",
54+
description: "Inspect an OAuth client's configuration",
5155
command: "geonic admin oauth-clients get <client-id>",
5256
},
5357
]);
@@ -134,7 +138,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
134138
// oauth-clients delete
135139
const del = oauthClients
136140
.command("delete <id>")
137-
.description("Delete an OAuth client")
141+
.description("Delete an OAuth client. Existing tokens issued by this client will be invalidated")
138142
.action(
139143
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
140144
const client = createClient(cmd);
@@ -148,7 +152,7 @@ export function registerOAuthClientsCommand(parent: Command): void {
148152

149153
addExamples(del, [
150154
{
151-
description: "Delete an OAuth client",
155+
description: "Delete an OAuth client by ID",
152156
command: "geonic admin oauth-clients delete <client-id>",
153157
},
154158
]);
@@ -157,12 +161,12 @@ export function registerOAuthClientsCommand(parent: Command): void {
157161
export function registerCaddeCommand(parent: Command): void {
158162
const cadde = parent
159163
.command("cadde")
160-
.description("Manage CADDE configuration");
164+
.description("Manage CADDE (data exchange) configuration for cross-platform data sharing");
161165

162166
// cadde get
163167
const caddeGet = cadde
164168
.command("get")
165-
.description("Get CADDE configuration")
169+
.description("Get the current CADDE data exchange configuration (provider, endpoint, etc.)")
166170
.action(
167171
withErrorHandler(async (_opts: unknown, cmd: Command) => {
168172
const client = createClient(cmd);
@@ -174,9 +178,13 @@ export function registerCaddeCommand(parent: Command): void {
174178

175179
addExamples(caddeGet, [
176180
{
177-
description: "Get CADDE configuration",
181+
description: "View current CADDE configuration",
178182
command: "geonic admin cadde get",
179183
},
184+
{
185+
description: "View CADDE configuration in table format",
186+
command: "geonic admin cadde get --format table",
187+
},
180188
]);
181189

182190
// cadde set
@@ -221,7 +229,7 @@ export function registerCaddeCommand(parent: Command): void {
221229
// cadde delete
222230
const caddeDelete = cadde
223231
.command("delete")
224-
.description("Delete CADDE configuration")
232+
.description("Remove the CADDE data exchange configuration, disabling cross-platform data sharing")
225233
.action(
226234
withErrorHandler(async (_opts: unknown, cmd: Command) => {
227235
const client = createClient(cmd);
@@ -232,7 +240,7 @@ export function registerCaddeCommand(parent: Command): void {
232240

233241
addExamples(caddeDelete, [
234242
{
235-
description: "Delete CADDE configuration",
243+
description: "Remove CADDE configuration",
236244
command: "geonic admin cadde delete",
237245
},
238246
]);

‎src/commands/admin/policies.ts‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,12 @@ import { addExamples } from "../help.js";
77
export function registerPoliciesCommand(parent: Command): void {
88
const policies = parent
99
.command("policies")
10-
.description("Manage policies");
10+
.description("Manage XACML access control policies");
1111

1212
// policies list
1313
const list = policies
1414
.command("list")
15-
.description("List all policies")
15+
.description("List all access control policies, showing their status and priority")
1616
.action(
1717
withErrorHandler(async (_opts: unknown, cmd: Command) => {
1818
const client = createClient(cmd);
@@ -27,12 +27,16 @@ export function registerPoliciesCommand(parent: Command): void {
2727
description: "List all policies",
2828
command: "geonic admin policies list",
2929
},
30+
{
31+
description: "List policies in table format for an overview",
32+
command: "geonic admin policies list --format table",
33+
},
3034
]);
3135

3236
// policies get
3337
const get = policies
3438
.command("get <id>")
35-
.description("Get a policy by ID")
39+
.description("Get a policy's full details — target rules, effect, priority, and status")
3640
.action(
3741
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
3842
const client = createClient(cmd);
@@ -47,7 +51,7 @@ export function registerPoliciesCommand(parent: Command): void {
4751

4852
addExamples(get, [
4953
{
50-
description: "Get a policy by ID",
54+
description: "Inspect a policy's rules and target configuration",
5155
command: "geonic admin policies get <policy-id>",
5256
},
5357
]);
@@ -167,7 +171,7 @@ export function registerPoliciesCommand(parent: Command): void {
167171
// policies delete
168172
const del = policies
169173
.command("delete <id>")
170-
.description("Delete a policy")
174+
.description("Delete a policy. Users or API keys referencing this policy will lose the access it granted")
171175
.action(
172176
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
173177
const client = createClient(cmd);
@@ -181,15 +185,15 @@ export function registerPoliciesCommand(parent: Command): void {
181185

182186
addExamples(del, [
183187
{
184-
description: "Delete a policy",
188+
description: "Delete a policy by ID",
185189
command: "geonic admin policies delete <policy-id>",
186190
},
187191
]);
188192

189193
// policies activate
190194
const activate = policies
191195
.command("activate <id>")
192-
.description("Activate a policy")
196+
.description("Activate a policy so its access control rules are enforced")
193197
.action(
194198
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
195199
const client = createClient(cmd);
@@ -203,15 +207,15 @@ export function registerPoliciesCommand(parent: Command): void {
203207

204208
addExamples(activate, [
205209
{
206-
description: "Activate a policy",
210+
description: "Enable a policy to start enforcing its rules",
207211
command: "geonic admin policies activate <policy-id>",
208212
},
209213
]);
210214

211215
// policies deactivate
212216
const deactivate = policies
213217
.command("deactivate <id>")
214-
.description("Deactivate a policy")
218+
.description("Deactivate a policy, suspending its rules without deleting it")
215219
.action(
216220
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
217221
const client = createClient(cmd);
@@ -225,7 +229,7 @@ export function registerPoliciesCommand(parent: Command): void {
225229

226230
addExamples(deactivate, [
227231
{
228-
description: "Deactivate a policy",
232+
description: "Temporarily disable a policy without deleting it",
229233
command: "geonic admin policies deactivate <policy-id>",
230234
},
231235
]);

‎src/commands/admin/tenants.ts‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ export function registerTenantsCommand(parent: Command): void {
1212
// tenants list
1313
const list = tenants
1414
.command("list")
15-
.description("List all tenants")
15+
.description("List all tenants in the system, including their status and configuration")
1616
.action(
1717
withErrorHandler(async (_opts: unknown, cmd: Command) => {
1818
const client = createClient(cmd);
@@ -27,12 +27,16 @@ export function registerTenantsCommand(parent: Command): void {
2727
description: "List all tenants",
2828
command: "geonic admin tenants list",
2929
},
30+
{
31+
description: "List tenants in table format",
32+
command: "geonic admin tenants list --format table",
33+
},
3034
]);
3135

3236
// tenants get
3337
const get = tenants
3438
.command("get <id>")
35-
.description("Get a tenant by ID")
39+
.description("Get a tenant's details — name, description, status, and creation date")
3640
.action(
3741
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
3842
const client = createClient(cmd);
@@ -47,9 +51,13 @@ export function registerTenantsCommand(parent: Command): void {
4751

4852
addExamples(get, [
4953
{
50-
description: "Get a tenant by ID",
54+
description: "Get tenant details by ID",
5155
command: "geonic admin tenants get <tenant-id>",
5256
},
57+
{
58+
description: "Get tenant details in table format",
59+
command: "geonic admin tenants get <tenant-id> --format table",
60+
},
5361
]);
5462

5563
// tenants create
@@ -150,7 +158,7 @@ export function registerTenantsCommand(parent: Command): void {
150158
// tenants delete
151159
const del = tenants
152160
.command("delete <id>")
153-
.description("Delete a tenant")
161+
.description("Permanently delete a tenant and all its associated data. This action cannot be undone")
154162
.action(
155163
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
156164
const client = createClient(cmd);
@@ -164,15 +172,19 @@ export function registerTenantsCommand(parent: Command): void {
164172

165173
addExamples(del, [
166174
{
167-
description: "Delete a tenant",
175+
description: "Delete a tenant by ID",
168176
command: "geonic admin tenants delete <tenant-id>",
169177
},
178+
{
179+
description: "Delete with verbose output to confirm",
180+
command: "geonic admin tenants delete <tenant-id> --verbose",
181+
},
170182
]);
171183

172184
// tenants activate
173185
const activate = tenants
174186
.command("activate <id>")
175-
.description("Activate a tenant")
187+
.description("Activate a tenant, restoring API access for all its users")
176188
.action(
177189
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
178190
const client = createClient(cmd);
@@ -186,15 +198,15 @@ export function registerTenantsCommand(parent: Command): void {
186198

187199
addExamples(activate, [
188200
{
189-
description: "Activate a tenant",
201+
description: "Activate a deactivated tenant",
190202
command: "geonic admin tenants activate <tenant-id>",
191203
},
192204
]);
193205

194206
// tenants deactivate
195207
const deactivate = tenants
196208
.command("deactivate <id>")
197-
.description("Deactivate a tenant")
209+
.description("Deactivate a tenant, blocking API access for all its users until reactivated")
198210
.action(
199211
withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
200212
const client = createClient(cmd);
@@ -208,7 +220,7 @@ export function registerTenantsCommand(parent: Command): void {
208220

209221
addExamples(deactivate, [
210222
{
211-
description: "Deactivate a tenant",
223+
description: "Deactivate a tenant to temporarily suspend access",
212224
command: "geonic admin tenants deactivate <tenant-id>",
213225
},
214226
]);

0 commit comments

Comments
 (0)