@camunda8/cli 2.7.0-alpha.1 → 2.7.0-alpha.10

package/dist/command-registry.js

@@ -5,6 +5,7 @@
  * Consumers (help, completion, validation, dispatch) derive their
  * data from this registry instead of maintaining separate copies.
  */
+import { AuthorizationKey, IncidentKey, JobKey, ProcessDefinitionId, ProcessDefinitionKey, ProcessInstanceKey, TenantId, Username, UserTaskKey, } from "@camunda8/orchestration-cluster-api";
 // ─── Resource Aliases ────────────────────────────────────────────────────────
 /**
  * Maps short/plural resource names to their canonical singular form.
@@ -12,11 +13,16 @@
  */
 export const RESOURCE_ALIASES = {
     pi: "process-instance",
+    "process-instances": "process-instance",
     pd: "process-definition",
+    "process-definitions": "process-definition",
     ut: "user-task",
+    "user-tasks": "user-task",
     inc: "incident",
+    incidents: "incident",
     msg: "message",
     vars: "variable",
+    variables: "variable",
     profile: "profile",
     profiles: "profile",
     plugin: "plugin",
@@ -45,11 +51,15 @@ export const GLOBAL_FLAGS = {
     "dry-run": {
         type: "boolean",
         description: "Preview the API request without executing",
+        agentDescription: "Preview the API request that would be sent, without executing it.\nEmits JSON: { dryRun, command, method, url, body }\nAlways exits 0.",
+        agentAppliesTo: "all commands",
     },
     verbose: { type: "boolean", description: "Show verbose output" },
     fields: {
         type: "string",
         description: "Comma-separated list of fields to display",
+        agentDescription: "Comma-separated list of output fields to include.\nReduces context window size when parsing output.\nExample: c8ctl list pi --fields Key,State,processDefinitionId\nCase-insensitive.",
+        agentAppliesTo: "all list/search/get commands",
     },
 };
 /**
@@ -79,16 +89,22 @@ const PI_SEARCH_FLAGS = {
     processDefinitionId: {
         type: "string",
         description: "Filter by process definition ID",
+        validate: ProcessDefinitionId.assumeExists,
     },
     processDefinitionKey: {
         type: "string",
         description: "Filter by process definition key",
+        validate: ProcessDefinitionKey.assumeExists,
+    },
+    state: {
+        type: "string",
+        description: "Filter by state (ACTIVE, COMPLETED, etc)",
     },
-    state: { type: "string", description: "Filter by state" },
     key: { type: "string", description: "Filter by key" },
     parentProcessInstanceKey: {
         type: "string",
         description: "Filter by parent process instance key",
+        validate: ProcessInstanceKey.assumeExists,
     },
     iid: {
         type: "string",
@@ -104,6 +120,7 @@ const PD_SEARCH_FLAGS = {
     processDefinitionId: {
         type: "string",
         description: "Filter by process definition ID",
+        validate: ProcessDefinitionId.assumeExists,
     },
     name: { type: "string", description: "Filter by name" },
     key: { type: "string", description: "Filter by key" },
@@ -119,10 +136,12 @@ const UT_SEARCH_FLAGS = {
     processInstanceKey: {
         type: "string",
         description: "Filter by process instance key",
+        validate: ProcessInstanceKey.assumeExists,
     },
     processDefinitionKey: {
         type: "string",
         description: "Filter by process definition key",
+        validate: ProcessDefinitionKey.assumeExists,
     },
     elementId: { type: "string", description: "Filter by element ID" },
     iassignee: {
@@ -135,10 +154,12 @@ const INC_SEARCH_FLAGS = {
     processInstanceKey: {
         type: "string",
         description: "Filter by process instance key",
+        validate: ProcessInstanceKey.assumeExists,
     },
     processDefinitionKey: {
         type: "string",
         description: "Filter by process definition key",
+        validate: ProcessDefinitionKey.assumeExists,
     },
     bpmnProcessId: {
         type: "string",
@@ -148,6 +169,7 @@ const INC_SEARCH_FLAGS = {
     processDefinitionId: {
         type: "string",
         description: "Filter by process definition ID",
+        validate: ProcessDefinitionId.assumeExists,
     },
     errorType: { type: "string", description: "Filter by error type" },
     errorMessage: {
@@ -169,10 +191,12 @@ const JOB_SEARCH_FLAGS = {
     processInstanceKey: {
         type: "string",
         description: "Filter by process instance key",
+        validate: ProcessInstanceKey.assumeExists,
     },
     processDefinitionKey: {
         type: "string",
         description: "Filter by process definition key",
+        validate: ProcessDefinitionKey.assumeExists,
     },
     itype: {
         type: "string",
@@ -185,6 +209,7 @@ const VAR_SEARCH_FLAGS = {
     processInstanceKey: {
         type: "string",
         description: "Filter by process instance key",
+        validate: ProcessInstanceKey.assumeExists,
     },
     scopeKey: { type: "string", description: "Filter by scope key" },
     fullValue: {
@@ -201,7 +226,11 @@ const VAR_SEARCH_FLAGS = {
     },
 };
 const USER_SEARCH_FLAGS = {
-    username: { type: "string", description: "Filter by username" },
+    username: {
+        type: "string",
+        description: "Filter by username",
+        validate: Username.assumeExists,
+    },
     name: { type: "string", description: "Filter by name" },
     email: { type: "string", description: "Filter by email" },
 };
@@ -214,7 +243,11 @@ const GROUP_SEARCH_FLAGS = {
     name: { type: "string", description: "Filter by name" },
 };
 const TENANT_SEARCH_FLAGS = {
-    tenantId: { type: "string", description: "Filter by tenant ID" },
+    tenantId: {
+        type: "string",
+        description: "Filter by tenant ID",
+        validate: TenantId.assumeExists,
+    },
     name: { type: "string", description: "Filter by name" },
 };
 const AUTH_SEARCH_FLAGS = {
@@ -268,13 +301,115 @@ const PROFILE_CONNECTION_FLAGS = {
         description: "Import from environment variables",
     },
 };
+// ─── Per-resource get flags ──────────────────────────────────────────────────
+export const GET_PD_FLAGS = {
+    xml: {
+        type: "boolean",
+        description: "Get BPMN XML (process definitions)",
+        showInTopLevelHelp: true,
+        helpHint: "use with 'get pd'",
+    },
+};
+const GET_FORM_FLAGS = {
+    userTask: {
+        type: "boolean",
+        description: "Get form for user task",
+        showInTopLevelHelp: true,
+        helpHint: "use with 'get form'",
+    },
+    ut: {
+        type: "boolean",
+        description: "Alias for --userTask",
+    },
+    processDefinition: {
+        type: "boolean",
+        description: "Get form for process definition",
+        showInTopLevelHelp: true,
+        helpHint: "use with 'get form'",
+    },
+    pd: {
+        type: "boolean",
+        description: "Alias for --processDefinition",
+    },
+};
+const GET_PI_FLAGS = {
+    variables: {
+        type: "boolean",
+        description: "Include variables in output",
+        showInTopLevelHelp: true,
+        helpHint: "use with 'get pi'",
+    },
+};
+// ─── Per-resource get positionals ────────────────────────────────────────────
+export const GET_PD_POSITIONALS = [
+    {
+        name: "key",
+        required: true,
+        validate: ProcessDefinitionKey.assumeExists,
+    },
+];
+const GET_PI_POSITIONALS = [
+    {
+        name: "key",
+        required: true,
+        validate: ProcessInstanceKey.assumeExists,
+    },
+];
+const GET_INCIDENT_POSITIONALS = [
+    {
+        name: "key",
+        required: true,
+        validate: IncidentKey.assumeExists,
+    },
+];
+const GET_USER_POSITIONALS = [
+    {
+        name: "username",
+        required: true,
+        validate: Username.assumeExists,
+    },
+];
+const GET_ROLE_POSITIONALS = [
+    { name: "roleId", required: true },
+];
+const GET_GROUP_POSITIONALS = [
+    { name: "groupId", required: true },
+];
+const GET_TENANT_POSITIONALS = [
+    {
+        name: "tenantId",
+        required: true,
+        validate: TenantId.assumeExists,
+    },
+];
+const GET_AUTHORIZATION_POSITIONALS = [
+    {
+        name: "authorizationKey",
+        required: true,
+        validate: AuthorizationKey.assumeExists,
+    },
+];
+const GET_MAPPING_RULE_POSITIONALS = [
+    { name: "mappingRuleId", required: true },
+];
+const GET_FORM_POSITIONALS = [
+    { name: "key", required: true },
+];
 // ─── Command Registry ────────────────────────────────────────────────────────
 export const COMMAND_REGISTRY = {
     // ── Read commands ──────────────────────────────────────────────────────
     list: {
         description: "List resources (process, identity)",
+        helpDescription: "List resources",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show all list resources and their flags",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            { command: "c8ctl list pi", description: "List process instances" },
+            { command: "c8ctl list pd", description: "List process definitions" },
+            { command: "c8ctl list users", description: "List users" },
+        ],
         resources: [
             "pi",
             "pd",
@@ -296,8 +431,6 @@ export const COMMAND_REGISTRY = {
                 description: "List all (disable pagination limit)",
             },
             ...SEARCH_FLAGS,
-            // List supports the same resource-specific filters as search;
-            // per-resource scoping is handled by SEARCH_RESOURCE_FLAGS.
             ...PI_SEARCH_FLAGS,
             ...PD_SEARCH_FLAGS,
             ...UT_SEARCH_FLAGS,
@@ -310,11 +443,77 @@ export const COMMAND_REGISTRY = {
             ...AUTH_SEARCH_FLAGS,
             ...MR_SEARCH_FLAGS,
         },
+        resourceFlags: {
+            "process-definition": PD_SEARCH_FLAGS,
+            "process-instance": PI_SEARCH_FLAGS,
+            "user-task": UT_SEARCH_FLAGS,
+            incident: INC_SEARCH_FLAGS,
+            jobs: JOB_SEARCH_FLAGS,
+            user: USER_SEARCH_FLAGS,
+            role: ROLE_SEARCH_FLAGS,
+            group: GROUP_SEARCH_FLAGS,
+            tenant: TENANT_SEARCH_FLAGS,
+            authorization: AUTH_SEARCH_FLAGS,
+            "mapping-rule": MR_SEARCH_FLAGS,
+        },
     },
     search: {
         description: "Search resources with filters",
+        helpDescription: "Search resources with filters (wildcards, date ranges, case-insensitive)",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show all search resources and their flags",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl search pi --state=ACTIVE",
+                description: "Search for active process instances",
+            },
+            {
+                command: "c8ctl search pd --bpmnProcessId=myProcess",
+                description: "Search process definitions by ID",
+            },
+            {
+                command: "c8ctl search pd --name='*main*'",
+                description: "Search process definitions with wildcard",
+            },
+            {
+                command: "c8ctl search ut --assignee=john",
+                description: "Search user tasks assigned to john",
+            },
+            {
+                command: "c8ctl search inc --state=ACTIVE",
+                description: "Search for active incidents",
+            },
+            {
+                command: "c8ctl search jobs --type=myJobType",
+                description: "Search jobs by type",
+            },
+            {
+                command: "c8ctl search jobs --type='*service*'",
+                description: 'Search jobs with type containing "service"',
+            },
+            {
+                command: "c8ctl search variables --name=myVar",
+                description: "Search for variables by name",
+            },
+            {
+                command: "c8ctl search variables --value=foo",
+                description: "Search for variables by value",
+            },
+            {
+                command: "c8ctl search variables --processInstanceKey=123 --fullValue",
+                description: "Search variables with full values",
+            },
+            {
+                command: "c8ctl search pd --iname='*order*'",
+                description: "Case-insensitive search by name",
+            },
+            {
+                command: "c8ctl search ut --iassignee=John",
+                description: "Case-insensitive search by assignee",
+            },
+        ],
         resources: [
             "pi",
             "pd",
@@ -331,8 +530,6 @@ export const COMMAND_REGISTRY = {
         ],
         flags: {
             ...SEARCH_FLAGS,
-            // Resource-specific flags are all accepted; per-resource scoping
-            // is handled by SEARCH_RESOURCE_FLAGS below.
             ...PI_SEARCH_FLAGS,
             ...PD_SEARCH_FLAGS,
             ...UT_SEARCH_FLAGS,
@@ -346,11 +543,59 @@ export const COMMAND_REGISTRY = {
             ...AUTH_SEARCH_FLAGS,
             ...MR_SEARCH_FLAGS,
         },
+        resourceFlags: {
+            "process-definition": PD_SEARCH_FLAGS,
+            "process-instance": PI_SEARCH_FLAGS,
+            "user-task": UT_SEARCH_FLAGS,
+            incident: INC_SEARCH_FLAGS,
+            jobs: JOB_SEARCH_FLAGS,
+            variable: VAR_SEARCH_FLAGS,
+            user: USER_SEARCH_FLAGS,
+            role: ROLE_SEARCH_FLAGS,
+            group: GROUP_SEARCH_FLAGS,
+            tenant: TENANT_SEARCH_FLAGS,
+            authorization: AUTH_SEARCH_FLAGS,
+            "mapping-rule": MR_SEARCH_FLAGS,
+        },
     },
     get: {
         description: "Get resource by key",
+        helpDescription: "Get a resource by key",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show all get resources and their flags",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl get pi 123456",
+                description: "Get process instance by key",
+            },
+            {
+                command: "c8ctl get pi 123456 --variables",
+                description: "Get process instance with variables",
+            },
+            {
+                command: "c8ctl get pd 123456",
+                description: "Get process definition by key",
+            },
+            {
+                command: "c8ctl get pd 123456 --xml",
+                description: "Get process definition XML",
+            },
+            {
+                command: "c8ctl get form 123456",
+                description: "Get form (searches both user task and process definition)",
+            },
+            {
+                command: "c8ctl get form 123456 --ut",
+                description: "Get form for user task only",
+            },
+            {
+                command: "c8ctl get form 123456 --pd",
+                description: "Get start form for process definition only",
+            },
+            { command: "c8ctl get user john", description: "Get user by username" },
+        ],
         resources: [
             "pi",
             "pd",
@@ -364,26 +609,47 @@ export const COMMAND_REGISTRY = {
             "auth",
             "mapping-rule",
         ],
-        flags: {
-            xml: {
-                type: "boolean",
-                description: "Get BPMN XML (process definitions)",
-            },
-            userTask: {
-                type: "boolean",
-                description: "Get form for user task",
-            },
-            processDefinition: {
-                type: "boolean",
-                description: "Get form for process definition",
-            },
+        flags: { ...GET_PD_FLAGS, ...GET_FORM_FLAGS, ...GET_PI_FLAGS },
+        resourceFlags: {
+            "process-definition": GET_PD_FLAGS,
+            form: GET_FORM_FLAGS,
+            "process-instance": GET_PI_FLAGS,
+        },
+        resourcePositionals: {
+            "process-definition": GET_PD_POSITIONALS,
+            "process-instance": GET_PI_POSITIONALS,
+            incident: GET_INCIDENT_POSITIONALS,
+            user: GET_USER_POSITIONALS,
+            role: GET_ROLE_POSITIONALS,
+            group: GET_GROUP_POSITIONALS,
+            tenant: GET_TENANT_POSITIONALS,
+            authorization: GET_AUTHORIZATION_POSITIONALS,
+            "mapping-rule": GET_MAPPING_RULE_POSITIONALS,
+            form: GET_FORM_POSITIONALS,
         },
     },
     // ── Mutating commands ──────────────────────────────────────────────────
     create: {
         description: "Create resource",
+        helpDescription: "Create a resource (process instance, identity)",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show all create resources and their flags",
         mutating: true,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl create pi --id=myProcess",
+                description: "Create a process instance",
+            },
+            {
+                command: "c8ctl create pi --id=myProcess --awaitCompletion",
+                description: "Create and await completion",
+            },
+            {
+                command: "c8ctl create user --username=john --name='John Doe' --email=john@example.com --password=secret",
+                description: "Create a user",
+            },
+        ],
         resources: [
             "pi",
             "user",
@@ -398,10 +664,13 @@ export const COMMAND_REGISTRY = {
             processDefinitionId: {
                 type: "string",
                 description: "Process definition ID (BPMN process ID)",
+                validate: ProcessDefinitionId.assumeExists,
             },
             id: {
                 type: "string",
                 description: "Process definition ID (alias for --processDefinitionId)",
+                showInTopLevelHelp: true,
+                helpHint: "alias for --bpmnProcessId",
             },
             bpmnProcessId: {
                 type: "string",
@@ -411,17 +680,26 @@ export const COMMAND_REGISTRY = {
             awaitCompletion: {
                 type: "boolean",
                 description: "Wait for process to complete",
+                showInTopLevelHelp: true,
+                helpHint: "use with 'create pi'",
             },
             fetchVariables: {
                 type: "boolean",
                 description: "Fetch result variables on completion",
+                showInTopLevelHelp: true,
             },
             requestTimeout: {
                 type: "string",
                 description: "Await timeout in milliseconds",
+                showInTopLevelHelp: true,
+                helpHint: "use with --awaitCompletion",
             },
             // Identity user
-            username: { type: "string", description: "Username" },
+            username: {
+                type: "string",
+                description: "Username",
+                validate: Username.assumeExists,
+            },
             name: { type: "string", description: "Display name" },
             email: { type: "string", description: "Email address" },
             password: { type: "string", description: "Password" },
@@ -430,7 +708,11 @@ export const COMMAND_REGISTRY = {
             // Identity group
             groupId: { type: "string", description: "Group ID" },
             // Identity tenant
-            tenantId: { type: "string", description: "Tenant ID" },
+            tenantId: {
+                type: "string",
+                description: "Tenant ID",
+                validate: TenantId.assumeExists,
+            },
             // Identity authorization
             ownerId: {
                 type: "string",
@@ -469,27 +751,60 @@ export const COMMAND_REGISTRY = {
     },
     delete: {
         description: "Delete resource",
+        helpDescription: "Delete a resource by key",
+        helpResource: "<resource> <key>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show delete command with all flags",
         mutating: true,
         requiresResource: true,
+        helpExamples: [
+            { command: "c8ctl delete user john", description: "Delete user" },
+        ],
         resources: ["user", "role", "group", "tenant", "auth", "mapping-rule"],
         flags: {},
+        resourcePositionals: {
+            user: GET_USER_POSITIONALS,
+            role: GET_ROLE_POSITIONALS,
+            group: GET_GROUP_POSITIONALS,
+            tenant: GET_TENANT_POSITIONALS,
+            authorization: GET_AUTHORIZATION_POSITIONALS,
+            "mapping-rule": GET_MAPPING_RULE_POSITIONALS,
+        },
     },
     cancel: {
         description: "Cancel resource",
+        helpDescription: "Cancel a process instance",
+        helpResource: "<resource> <key>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show cancel command with all flags",
         mutating: true,
         requiresResource: true,
         resources: ["pi"],
         flags: {},
+        resourcePositionals: {
+            "process-instance": GET_PI_POSITIONALS,
+        },
     },
     await: {
         description: "Create and await completion (alias for create --awaitCompletion)",
+        helpDescription: "Create and await process instance completion (server-side waiting)",
+        helpResource: "<resource>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show await command with all flags",
         mutating: true,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl await pi --id=myProcess",
+                description: "Create and wait for completion",
+            },
+        ],
         resources: ["pi"],
         flags: {
             processDefinitionId: {
                 type: "string",
                 description: "Process definition ID (BPMN process ID)",
+                validate: ProcessDefinitionId.assumeExists,
             },
             id: {
                 type: "string",
@@ -512,15 +827,38 @@ export const COMMAND_REGISTRY = {
     },
     complete: {
         description: "Complete resource",
+        helpDescription: "Complete a user task or job",
+        helpResource: "<resource> <key>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show all complete resources and their flags",
         mutating: true,
         requiresResource: true,
         resources: ["ut", "job"],
         flags: {
             variables: { type: "string", description: "JSON variables" },
         },
+        resourcePositionals: {
+            "user-task": [
+                {
+                    name: "key",
+                    required: true,
+                    validate: UserTaskKey.assumeExists,
+                },
+            ],
+            job: [
+                {
+                    name: "key",
+                    required: true,
+                    validate: JobKey.assumeExists,
+                },
+            ],
+        },
     },
     fail: {
         description: "Fail a job",
+        helpDescription: "Mark a job as failed with optional error message and retry count",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show fail command with all flags",
         mutating: true,
         requiresResource: true,
         resources: ["job"],
@@ -534,9 +872,21 @@ export const COMMAND_REGISTRY = {
                 description: "Error message",
             },
         },
+        resourcePositionals: {
+            job: [
+                {
+                    name: "key",
+                    required: true,
+                    validate: JobKey.assumeExists,
+                },
+            ],
+        },
     },
     activate: {
         description: "Activate jobs by type",
+        helpDescription: "Activate jobs of a specific type for processing",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show activate command with all flags",
         mutating: true,
         requiresResource: true,
         resources: ["jobs"],
@@ -551,16 +901,30 @@ export const COMMAND_REGISTRY = {
             },
             worker: { type: "string", description: "Worker name" },
         },
+        resourcePositionals: {
+            jobs: [
+                { name: "type", required: true },
+            ],
+        },
     },
     resolve: {
         description: "Resolve incident",
+        helpDescription: "Resolve an incident (marks resolved, allows process to continue)",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show resolve command with all flags",
         mutating: true,
         requiresResource: true,
         resources: ["inc"],
         flags: {},
+        resourcePositionals: {
+            incident: GET_INCIDENT_POSITIONALS,
+        },
     },
     publish: {
         description: "Publish message",
+        helpDescription: "Publish a message for message correlation",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show publish command with all flags",
         mutating: true,
         requiresResource: true,
         resources: ["msg"],
@@ -575,9 +939,17 @@ export const COMMAND_REGISTRY = {
                 description: "Time to live in milliseconds",
             },
         },
+        resourcePositionals: {
+            message: [
+                { name: "name", required: true },
+            ],
+        },
     },
     correlate: {
         description: "Correlate message",
+        helpDescription: "Correlate a message to a specific process instance",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show correlate command with all flags",
         mutating: true,
         requiresResource: true,
         resources: ["msg"],
@@ -593,18 +965,43 @@ export const COMMAND_REGISTRY = {
                 description: "Time to live in milliseconds",
             },
         },
+        resourcePositionals: {
+            message: [
+                { name: "name", required: true },
+            ],
+        },
     },
     deploy: {
         description: "Deploy BPMN/DMN/forms",
+        helpDescription: "Deploy BPMN, DMN, and form files (auto-discovers deployable files)",
+        helpResource: "[path...]",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show deploy command with all flags",
         mutating: true,
         requiresResource: false,
+        helpExamples: [
+            {
+                command: "c8ctl deploy ./my-process.bpmn",
+                description: "Deploy a BPMN file",
+            },
+        ],
         resources: [],
         flags: {},
     },
     run: {
         description: "Deploy and start process",
+        helpDescription: "Deploy and start a process instance from a BPMN file",
+        helpResource: "<path>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show run command with all flags",
         mutating: true,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl run ./my-process.bpmn",
+                description: "Deploy and start process",
+            },
+        ],
         resources: [],
         flags: {
             variables: { type: "string", description: "JSON variables" },
@@ -613,36 +1010,96 @@ export const COMMAND_REGISTRY = {
     // ── Assignment commands ────────────────────────────────────────────────
     assign: {
         description: "Assign resource to target",
+        helpDescription: "Assign a resource to a target (--to-user, --to-group, etc.)",
+        helpResource: "<resource> <id>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show assign command with all flags",
         mutating: true,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl assign role admin --to-user=john",
+                description: "Assign role to user",
+            },
+        ],
         resources: ["role", "user", "group", "mapping-rule"],
         flags: { ...ASSIGN_FLAGS },
+        resourcePositionals: {
+            role: GET_ROLE_POSITIONALS,
+            user: GET_USER_POSITIONALS,
+            group: GET_GROUP_POSITIONALS,
+            "mapping-rule": GET_MAPPING_RULE_POSITIONALS,
+        },
     },
     unassign: {
         description: "Unassign resource from target",
+        helpDescription: "Unassign a resource from a target (--from-user, --from-group, etc.)",
+        helpResource: "<resource> <id>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show unassign command with all flags",
         mutating: true,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl unassign role admin --from-user=john",
+                description: "Unassign role from user",
+            },
+        ],
         resources: ["role", "user", "group", "mapping-rule"],
         flags: { ...UNASSIGN_FLAGS },
+        resourcePositionals: {
+            role: GET_ROLE_POSITIONALS,
+            user: GET_USER_POSITIONALS,
+            group: GET_GROUP_POSITIONALS,
+            "mapping-rule": GET_MAPPING_RULE_POSITIONALS,
+        },
     },
     // ── Operational commands ───────────────────────────────────────────────
     watch: {
         description: "Watch files for changes and auto-deploy",
+        helpDescription: "Watch files for changes and auto-deploy (BPMN, DMN, forms)",
+        helpResource: "[path...]",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show watch command with all flags",
         mutating: false,
         requiresResource: false,
+        helpExamples: [
+            {
+                command: "c8ctl watch ./src",
+                description: "Watch directory for changes",
+            },
+        ],
         resources: [],
         flags: {
             force: {
                 type: "boolean",
-                description: "Force re-deploy unchanged files",
+                description: "Continue watching after all deployment errors",
             },
         },
         aliases: ["w"],
     },
     open: {
         description: "Open Camunda web application in browser",
+        helpDescription: "Open Camunda web app in browser",
+        helpResource: "<app>",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show open command with all apps",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl open operate",
+                description: "Open Camunda Operate in browser",
+            },
+            {
+                command: "c8ctl open tasklist",
+                description: "Open Camunda Tasklist in browser",
+            },
+            {
+                command: "c8ctl open operate --profile=prod",
+                description: "Open Operate using a specific profile",
+            },
+        ],
         resources: ["operate", "tasklist", "modeler", "optimize"],
         flags: {},
     },
@@ -653,12 +1110,19 @@ export const COMMAND_REGISTRY = {
         requiresResource: true,
         resources: ["profile"],
         flags: { ...PROFILE_CONNECTION_FLAGS },
+        resourcePositionals: {
+            profile: [
+                { name: "name", required: true },
+            ],
+        },
     },
     remove: {
-        description: "Remove a profile",
+        description: "Remove a profile or plugin",
+        helpResource: "profile <name>",
+        helpDescription: "Remove a profile (alias: rm)",
         mutating: false,
         requiresResource: true,
-        resources: ["profile"],
+        resources: ["profile", "plugin"],
         flags: {
             none: {
                 type: "boolean",
@@ -666,21 +1130,50 @@ export const COMMAND_REGISTRY = {
             },
         },
         aliases: ["rm"],
+        resourcePositionals: {
+            profile: [
+                { name: "name", required: true },
+            ],
+            plugin: [
+                { name: "package", required: true },
+            ],
+        },
     },
     load: {
         description: "Load a c8ctl plugin",
+        helpResource: "plugin [name|--from url]",
+        helpDescription: "Load a c8ctl plugin (npm registry or URL)",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl load plugin my-plugin",
+                description: "Load plugin from npm registry",
+            },
+            {
+                command: "c8ctl load plugin --from https://github.com/org/plugin",
+                description: "Load plugin from URL",
+            },
+        ],
         resources: ["plugin"],
         flags: {
             from: {
                 type: "string",
                 description: "Load plugin from URL",
+                showInTopLevelHelp: true,
+                helpHint: "use with 'load plugin'",
             },
         },
+        resourcePositionals: {
+            plugin: [
+                { name: "package", required: false },
+            ],
+        },
     },
     unload: {
         description: "Unload a c8ctl plugin",
+        helpResource: "plugin <name>",
+        helpDescription: "Unload a c8ctl plugin (npm uninstall wrapper)",
         mutating: false,
         requiresResource: true,
         resources: ["plugin"],
@@ -691,25 +1184,59 @@ export const COMMAND_REGISTRY = {
             },
         },
         aliases: ["rm"],
+        resourcePositionals: {
+            plugin: [
+                { name: "package", required: true },
+            ],
+        },
     },
     upgrade: {
         description: "Upgrade a plugin",
+        helpResource: "plugin <name> [version]",
+        helpDescription: "Upgrade a plugin (respects source type)",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl upgrade plugin my-plugin",
+                description: "Upgrade plugin to latest version",
+            },
+            {
+                command: "c8ctl upgrade plugin my-plugin 1.2.3",
+                description: "Upgrade plugin to a specific version (source-aware)",
+            },
+        ],
         resources: ["plugin"],
         flags: {},
+        resourcePositionals: {
+            plugin: [
+                { name: "package", required: true },
+                { name: "version", required: false },
+            ],
+        },
     },
     downgrade: {
         description: "Downgrade a plugin to a specific version",
+        helpResource: "plugin <name> <version>",
         mutating: false,
         requiresResource: true,
         resources: ["plugin"],
         flags: {},
+        resourcePositionals: {
+            plugin: [
+                { name: "package", required: true },
+                { name: "version", required: true },
+            ],
+        },
     },
     sync: {
         description: "Synchronize plugins",
+        helpDescription: "Synchronize plugins from registry (rebuild/reinstall)",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            { command: "c8ctl sync plugin", description: "Synchronize plugins" },
+        ],
         resources: ["plugin"],
         flags: {},
     },
@@ -717,14 +1244,29 @@ export const COMMAND_REGISTRY = {
         description: "Create a new plugin from TypeScript template",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl init plugin my-plugin",
+                description: "Create new plugin from template (c8ctl-plugin-my-plugin)",
+            },
+        ],
         resources: ["plugin"],
         flags: {},
+        resourcePositionals: {
+            plugin: [
+                { name: "name", required: false },
+            ],
+        },
     },
     // ── Session commands ───────────────────────────────────────────────────
     use: {
         description: "Set active profile or tenant",
+        helpResource: "profile|tenant",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            { command: "c8ctl use profile prod", description: "Set active profile" },
+        ],
         resources: ["profile", "tenant"],
         flags: {
             none: {
@@ -732,24 +1274,63 @@ export const COMMAND_REGISTRY = {
                 description: "Clear active profile/tenant",
             },
         },
+        resourcePositionals: {
+            profile: [
+                { name: "name", required: false },
+            ],
+            tenant: [
+                { name: "tenantId", required: true },
+            ],
+        },
     },
     output: {
         description: "Show or set output format",
+        helpResource: "[json|text]",
         mutating: false,
         requiresResource: false,
+        helpExamples: [
+            { command: "c8ctl output json", description: "Switch to JSON output" },
+        ],
         resources: ["json", "text"],
         flags: {},
     },
     // ── Utility commands ───────────────────────────────────────────────────
     completion: {
         description: "Generate shell completion script",
-        mutating: false,
+        helpResource: "bash|zsh|fish|install",
+        mutating: true,
         requiresResource: false,
-        resources: ["bash", "zsh", "fish"],
+        helpExamples: [
+            {
+                command: "c8ctl completion bash",
+                description: "Generate bash completion script",
+            },
+            {
+                command: "c8ctl completion install",
+                description: "Auto-detect shell and install completions (auto-refreshes on upgrade)",
+            },
+            {
+                command: "c8ctl completion install --shell zsh",
+                description: "Install completions for a specific shell",
+            },
+        ],
+        resources: ["bash", "zsh", "fish", "install"],
         flags: {},
+        resourceFlags: {
+            install: {
+                shell: {
+                    type: "string",
+                    description: "Shell to install completions for (bash, zsh, fish)",
+                },
+            },
+        },
     },
     "mcp-proxy": {
         description: "Start a STDIO to remote HTTP MCP proxy server",
+        helpDescription: "Start a STDIO MCP proxy (bridges local MCP clients to remote Camunda 8)",
+        helpResource: "[mcp-path]",
+        hasDetailedHelp: true,
+        helpFooterLabel: "Show mcp-proxy setup and usage",
         mutating: false,
         requiresResource: false,
         resources: [],
@@ -764,39 +1345,28 @@ export const COMMAND_REGISTRY = {
     },
     help: {
         description: "Show help",
+        helpResource: "[command]",
+        helpDescription: "Show help (run 'c8ctl help <command>' for details)",
         mutating: false,
         requiresResource: false,
         resources: [],
         flags: {},
+        aliases: ["menu"],
     },
     which: {
         description: "Show active profile",
         mutating: false,
         requiresResource: true,
+        helpExamples: [
+            {
+                command: "c8ctl which profile",
+                description: "Show currently active profile",
+            },
+        ],
         resources: ["profile"],
         flags: {},
     },
 };
-// ─── Per-resource search flag scoping ────────────────────────────────────────
-/**
- * Maps each searchable resource (canonical name) to the set of flag names
- * that are valid for that resource's search command. Used for unknown-flag
- * detection in search commands.
- */
-export const SEARCH_RESOURCE_FLAGS = {
-    "process-definition": new Set(Object.keys(PD_SEARCH_FLAGS)),
-    "process-instance": new Set(Object.keys(PI_SEARCH_FLAGS)),
-    "user-task": new Set(Object.keys(UT_SEARCH_FLAGS)),
-    incident: new Set(Object.keys(INC_SEARCH_FLAGS)),
-    jobs: new Set(Object.keys(JOB_SEARCH_FLAGS)),
-    variable: new Set([...Object.keys(VAR_SEARCH_FLAGS), "limit"]),
-    user: new Set([...Object.keys(USER_SEARCH_FLAGS), "limit"]),
-    role: new Set([...Object.keys(ROLE_SEARCH_FLAGS), "limit"]),
-    group: new Set([...Object.keys(GROUP_SEARCH_FLAGS), "limit"]),
-    tenant: new Set([...Object.keys(TENANT_SEARCH_FLAGS), "limit"]),
-    authorization: new Set([...Object.keys(AUTH_SEARCH_FLAGS), "limit"]),
-    "mapping-rule": new Set([...Object.keys(MR_SEARCH_FLAGS), "limit"]),
-};
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Maps verb aliases to their canonical verb names.
@@ -805,6 +1375,7 @@ export const SEARCH_RESOURCE_FLAGS = {
  */
 export const VERB_ALIASES = (() => {
     const map = {};
+    // biome-ignore lint/plugin: widen to CommandDef to access optional aliases property
     for (const [verb, def] of Object.entries(COMMAND_REGISTRY)) {
         for (const alias of def.aliases ?? []) {
             if (!map[alias]) {
@@ -828,11 +1399,15 @@ export function resolveAlias(resource) {
  * returns the first match. Use VERB_ALIASES directly for multi-target aliases.
  */
 export function getCommandDef(verb) {
+    // biome-ignore lint/plugin: trust boundary — verb is unvalidated CLI input, must index dynamically
     const direct = COMMAND_REGISTRY[verb];
     if (direct)
         return direct;
     const targets = VERB_ALIASES[verb];
-    return targets ? COMMAND_REGISTRY[targets[0]] : undefined;
+    return targets
+        ? // biome-ignore lint/plugin: trust boundary — alias target is a dynamic string
+            COMMAND_REGISTRY[targets[0]]
+        : undefined;
 }
 /**
  * Get all flags accepted for a given verb, including global flags.
@@ -843,12 +1418,6 @@ export function getAcceptedFlags(verb) {
         return undefined;
     return { ...GLOBAL_FLAGS, ...def.flags };
 }
-/**
- * Get the set of resource-specific search flags for a given canonical resource.
- */
-export function getSearchFlagsForResource(resource) {
-    return SEARCH_RESOURCE_FLAGS[resource];
-}
 /**
  * Check whether a verb×resource combination is valid.
  * Accepts both raw aliases and canonical resource names.
@@ -868,26 +1437,44 @@ export function isValidCommand(verb, resource) {
  * Derive parseArgs options from the registry. This produces the flat
  * options object that node:util parseArgs expects, covering all flags
  * from all commands plus global flags.
+ *
+ * When the same flag name appears with different types across commands
+ * (e.g. `--variables` is boolean for `get pi` but string for `create pi`),
+ * "string" wins because parseArgs with `type: "string"` can accept any
+ * value, whereas `type: "boolean"` would discard the string payload.
  */
 export function deriveParseArgsOptions() {
     const options = {};
-    // Global flags
-    for (const [name, def] of Object.entries(GLOBAL_FLAGS)) {
-        options[name] = { type: def.type, ...(def.short && { short: def.short }) };
-    }
-    // Search flags
-    for (const [name, def] of Object.entries(SEARCH_FLAGS)) {
-        options[name] = { type: def.type, ...(def.short && { short: def.short }) };
-    }
-    // All command-specific flags
-    for (const cmd of Object.values(COMMAND_REGISTRY)) {
-        for (const [name, def] of Object.entries(cmd.flags)) {
-            if (!options[name]) {
+    function addFlags(flags) {
+        for (const [name, def] of Object.entries(flags)) {
+            const existing = options[name];
+            if (!existing) {
                 options[name] = {
                     type: def.type,
                     ...(def.short && { short: def.short }),
                 };
             }
+            else {
+                // String is more permissive — upgrade when any usage is string
+                if (def.type === "string")
+                    existing.type = "string";
+                if (def.short && !existing.short)
+                    existing.short = def.short;
+            }
+        }
+    }
+    // Global flags
+    addFlags(GLOBAL_FLAGS);
+    // Search flags
+    addFlags(SEARCH_FLAGS);
+    // All command-specific flags
+    for (const cmd of Object.values(COMMAND_REGISTRY)) {
+        addFlags(cmd.flags);
+        // Include resource-specific flags so parseArgs can parse them
+        if ("resourceFlags" in cmd && cmd.resourceFlags) {
+            for (const rFlags of Object.values(cmd.resourceFlags)) {
+                addFlags(rFlags);
+            }
         }
     }
     return options;