@camunda8/cli 3.2.0-alpha.1 → 3.2.0-alpha.3

package/CONTEXT.md

@@ -38,6 +38,9 @@ c8ctl help          # get structured JSON command reference
 | `inc` | incident(s)          |
 | `msg` | message              |
 | `vars`| variable(s)          |
+| `var` | variable             |
+| `auth`| authorization(s)     |
+| `mr`  | mapping-rule(s)      |
 
 ## Agent Flags
 
@@ -59,21 +62,10 @@ Use this to reduce context window size when parsing output programmatically.
 
 ### `--dry-run`
 
-Applies to all **mutating** commands: `create`, `cancel`, `deploy`,
-`complete`, `fail`, `activate`, `resolve`, `publish`, `correlate`.
-
-In dry-run mode:
-- All inputs are validated
-- The target profile/client is resolved
-- The equivalent API request is emitted as JSON to stdout:
-  `{ "dryRun": true, "command": "...", "method": "POST", "url": "...", "body": {...} }`
-- The actual API call is **not** executed
-- Exits 0
-
-**Recommended workflow for mutating operations:**
-1. Run the command with `--dry-run` and inspect the JSON output
-2. Confirm the request with the user (or validate programmatically)
-3. Re-run without `--dry-run` to execute
+Preview the API request without executing it. Supported by most commands.
+Emits a JSON object to stdout and exits 0:
+
+`{ "dryRun": true, "command": "...", "method": "...", "url": "...", "body": ... }`
 
 ```sh
 c8ctl create pi --id=my-process --dry-run

package/EXAMPLES.md

@@ -13,10 +13,16 @@ Comprehensive examples for all c8ctl operations.
 - [Deployments](#deployments)
 - [Forms](#forms)
 - [Topology](#topology)
+- [Variables](#variables)
+- [Date Range Filtering](#date-range-filtering)
+- [Identity Management](#identity-management)
+- [Open Camunda Applications](#open-camunda-applications)
 - [Profile Management](#profile-management)
 - [Session Management](#session-management)
 - [Plugin Management](#plugin-management)
 - [Local Cluster](#local-cluster)
+- [Which](#which)
+- [Doctor](#doctor)
 - [Agent / Programmatic Consumption](#agent--programmatic-consumption)
 
 ---
@@ -486,8 +492,11 @@ c8 publish msg order-placed --correlationKey=order-12345 --timeToLive=3600000
 
 ### Correlate Message
 
+Correlate delivers a message to a specific waiting process instance. Unlike
+`publish` (where `--correlationKey` is optional), `correlate` requires it.
+
 ```bash
-# Correlate is an alias for publish
+# Correlate a message to a specific process instance
 c8 correlate msg payment-received --correlationKey=order-12345 --variables='{"amount":250.00}'
 ```
 
@@ -727,6 +736,229 @@ c8 get topology
 
 ---
 
+## Variables
+
+### Set Variables
+
+Set variables on a process instance or flow element scope. Variables propagate to the outermost scope by default.
+
+```bash
+# Set variables on a process instance
+c8 set variable 2251799813685249 --variables='{"status":"approved"}'
+
+# Set variables in local scope only (no propagation)
+c8 set variable 2251799813685249 --variables='{"x":1}' --local
+```
+
+---
+
+## Date Range Filtering
+
+Use `--between=<from>..<to>` to filter by date range (process instances, user tasks, incidents, jobs). Either side can be omitted for open-ended ranges.
+
+```bash
+# Process instances between specific dates
+c8 search pi --between=2024-01-01..2024-12-31
+
+# Open-ended: everything from a date onward
+c8 search pi --between=2024-01-01..
+
+# Open-ended: everything up to a date
+c8 search pi --between=..2024-12-31
+
+# Use --dateField to filter on a different field (not supported by incidents)
+c8 search pi --between=2024-01-01..2024-12-31 --dateField=endDate
+```
+
+---
+
+## Identity Management
+
+c8ctl supports managing identity resources: users, roles, groups, tenants, authorizations, and mapping rules.
+
+### Users
+
+```bash
+# List users
+c8 list users
+
+# Search users
+c8 search users --username=john
+c8 search users --name=John --email=john@example.com
+
+# Get user by username
+c8 get user john
+
+# Create a user
+c8 create user --username=john --name='John Doe' --email=john@example.com --password=secret
+
+# Delete a user
+c8 delete user john
+```
+
+### Roles
+
+```bash
+# List roles
+c8 list roles
+
+# Search roles
+c8 search roles --name=admin
+
+# Get role by ID
+c8 get role admin
+
+# Create a role
+c8 create role --roleId=viewer --name=Viewer
+
+# Delete a role
+c8 delete role viewer
+
+# Assign a role to a user
+c8 assign role admin --to-user=john
+
+# Unassign a role from a user
+c8 unassign role admin --from-user=john
+
+# Assign a role to a group
+c8 assign role admin --to-group=engineering
+```
+
+### Groups
+
+```bash
+# List groups
+c8 list groups
+
+# Search groups
+c8 search groups --name=engineering
+
+# Get group by ID
+c8 get group engineering
+
+# Create a group
+c8 create group --groupId=engineering --name=Engineering
+
+# Delete a group
+c8 delete group engineering
+
+# Assign a user to a group
+c8 assign user john --to-group=engineering
+
+# Unassign a user from a group
+c8 unassign user john --from-group=engineering
+```
+
+### Tenants
+
+```bash
+# List tenants
+c8 list tenants
+
+# Search tenants
+c8 search tenants --name=production
+
+# Get tenant by ID
+c8 get tenant production
+
+# Create a tenant
+c8 create tenant --tenantId=production --name=Production
+
+# Delete a tenant
+c8 delete tenant production
+
+# Assign a group to a tenant
+c8 assign group engineering --to-tenant=production
+```
+
+### Authorizations
+
+```bash
+# List authorizations
+c8 list auth
+
+# Search authorizations
+c8 search auth --ownerId=john --ownerType=USER
+
+# Get authorization by key
+c8 get auth 2251799813685249
+
+# Create an authorization
+c8 create auth --ownerId=john --ownerType=USER --resourceType=PROCESS_DEFINITION --resourceId=order-process --permissions=READ,UPDATE
+
+# Delete an authorization
+c8 delete auth 2251799813685249
+```
+
+### Mapping Rules
+
+```bash
+# List mapping rules
+c8 list mapping-rules
+
+# Search mapping rules
+c8 search mapping-rules --claimName=groups --claimValue=admins
+
+# Get mapping rule by ID
+c8 get mapping-rule my-rule
+
+# Create a mapping rule
+c8 create mapping-rule --mappingRuleId=my-rule --name='Admin Mapping' --claimName=groups --claimValue=admins
+
+# Delete a mapping rule
+c8 delete mapping-rule my-rule
+
+# Assign a mapping rule to a tenant
+c8 assign mapping-rule my-rule --to-tenant=production
+```
+
+---
+
+## Which
+
+Show the currently active profile or output mode:
+
+```bash
+# Show active profile
+c8 which profile
+
+# Show current output mode
+c8 which output
+```
+
+---
+
+## Doctor
+
+Surface plugin-loading collisions detected at startup:
+
+```bash
+# List loaded plugins and any collisions
+c8 doctor plugin
+
+# Machine-readable output
+c8 doctor plugin --json
+```
+
+---
+
+## Watch with Process Applications
+
+Watch mode supports process application deployment with `--process-application` (or `--pa`):
+
+```bash
+# Watch and deploy the entire process application
+c8 watch --process-application
+
+# Short form
+c8 watch --pa
+
+# Watch a specific directory as a process application
+c8 watch ./my-app --pa
+```
+
+---
+
 ## Profile Management
 
 c8ctl supports two types of profiles:

package/README.md

@@ -4,11 +4,13 @@ c8ctl (_pronounced: "cocktail"_) — a minimal-dependency CLI for Camunda 8 oper
 
 ## Features
 
-- **Minimal Dependencies**: Only one runtime dependency (`@camunda8/orchestration-cluster-api`)
 - **Multi-Tenant Support**: Full support for multi-tenancy across all operations
 - **Profile Management**: Store and manage multiple cluster configurations
 - **Camunda Modeler Integration**: Automatically import and use profiles from Camunda Modeler
+- **Identity Management**: Manage users, roles, groups, tenants, authorizations, and mapping rules
 - **Plugin System**: Extend c8ctl with custom commands via npm packages
+- **Local Cluster**: Run a local Camunda 8 instance directly — no Docker required
+- **MCP Proxy**: Bridge local MCP clients to remote Camunda 8 for AI agent integration
 - **Building Block Deployment**: Automatic prioritization of `*_bb-*` folders during deployment, marked with 🧱 in results
 - **Process Application Support**: Resources in folders with `.process-application` file marked with 📦 in results
 - **Enhanced Deployment Results**: Table view showing file paths, visual indicators, resource details, and versions
@@ -17,6 +19,9 @@ c8ctl (_pronounced: "cocktail"_) — a minimal-dependency CLI for Camunda 8 oper
 - **Open Applications**: Open Camunda web applications (Operate, Tasklist, Modeler, Optimize) in the browser directly from the CLI
 - **Search**: Powerful search across process definitions, process instances, user tasks, incidents, jobs, and variables with filter, wildcard, and case-insensitive support
 - **Flexible Output**: Switch between human-readable text and JSON output modes
+- **Shell Completion**: Auto-install completions for bash, zsh, and fish with automatic refresh on upgrade
+- **Agent Flags**: `--dry-run` to preview API requests and `--fields` to filter output columns for AI agents and scripts
+- **Debug Mode**: Enable detailed logging to stderr with `DEBUG=1` or `C8CTL_DEBUG=true`
 
 ## Beware the 🤖
 
@@ -138,49 +143,27 @@ c8ctl completion install --shell zsh
 
 This writes a completion script to the c8ctl data directory and wires it into your shell config (RC file for bash/zsh; completions directory for fish). Completions are **automatically refreshed** when c8ctl is upgraded — no manual re-install needed.
 
-#### Manual Setup
+#### Manual setup
 
-If you prefer to manage the completion script yourself:
-
-#### Bash
+If you prefer to manage the completion script yourself, generate it with
+`c8ctl completion <shell>` (where `<shell>` is `bash`, `zsh`, or `fish`),
+then source or install it:
 
 ```bash
-# Generate and source completion script
+# Bash
 c8ctl completion bash > ~/.c8ctl-completion.bash
 echo 'source ~/.c8ctl-completion.bash' >> ~/.bashrc
-source ~/.bashrc
-```
-
-Or for immediate use in the current session:
-
-```bash
-source <(c8ctl completion bash)
-```
-
-#### Zsh
+source ~/.c8ctl-completion.bash
 
-```bash
-# Generate and source completion script
+# Zsh
 c8ctl completion zsh > ~/.c8ctl-completion.zsh
 echo 'source ~/.c8ctl-completion.zsh' >> ~/.zshrc
-source ~/.zshrc
-```
-
-Or for immediate use in the current session:
-
-```bash
-source <(c8ctl completion zsh)
-```
+source ~/.c8ctl-completion.zsh
 
-#### Fish
-
-```bash
-# Generate and install completion script
+# Fish (auto-loaded on next start)
 c8ctl completion fish > ~/.config/fish/completions/c8ctl.fish
 ```
 
-Fish will automatically load the completion on next shell start.
-
 ### Credential Resolution
 
 Credentials are resolved in the following order:
@@ -418,63 +401,9 @@ c8ctl help
   - URL/git source: installs `<source>#<version>`
   - file source (`file://`): version downgrade is not supported; use `load plugin --from` with the desired local plugin checkout
 
-**Plugin Development:**
-
-- Use `c8ctl init plugin <name>` to scaffold a new plugin with TypeScript template
-- Convention over configuration: the directory is always prefixed with `c8ctl-plugin-`, and the plugin is registered by the suffix after the prefix (e.g., `c8ctl init plugin c8ctl-plugin-foo` creates directory `c8ctl-plugin-foo` and registers plugin name `foo`)
-- Generated scaffold includes all necessary files, build configuration, and an `AGENTS.md` guide for autonomous plugin implementation
-- Plugins have access to the c8ctl runtime via `globalThis.c8ctl`
-- Plugins can create SDK clients via `globalThis.c8ctl.createClient(profile?, sdkConfig?)`
-- Plugins can resolve tenant IDs via `globalThis.c8ctl.resolveTenantId(profile?)`
-- Plugins can access c8ctl output-aware logging via `globalThis.c8ctl.getLogger()`
-- See the bundled `hello-world` plugin in `default-plugins/` for a complete example
-
-**Plugin Requirements:**
-
-- Plugin packages must be regular Node.js modules
-- They must include a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory
-- The plugin file must export a `commands` object
-- Optionally export a `metadata` object to provide help text
-- Plugins are installed globally and work from any directory
-- The runtime object `c8ctl` provides environment information to plugins
-- The runtime object `c8ctl` exposes `createClient(profile?, sdkConfig?)` for creating Camunda SDK clients from plugins
-- The runtime object `c8ctl` exposes `resolveTenantId(profile?)` using the same fallback logic as built-in commands
-- The runtime object `c8ctl` exposes `getLogger()` returning the c8ctl logger instance (respects current output mode)
-- **Important**: `c8ctl-plugin.js` must be JavaScript. Node.js doesn't support type stripping in `node_modules`. If writing in TypeScript, transpile to JS before publishing.
-
-**TypeScript Plugin Autocomplete:**
-
-```typescript
-import type { C8ctlPluginRuntime } from '@camunda8/cli/runtime';
-
-const c8ctl = globalThis.c8ctl as C8ctlPluginRuntime;
-const tenantId = c8ctl.resolveTenantId();
-const logger = c8ctl.getLogger();
-logger.info(`Tenant: ${tenantId}`);
-```
+When plugins are loaded, their commands automatically appear in `c8ctl help` output.
 
-**Example Plugin Structure:**
-
-```typescript
-// c8ctl-plugin.ts
-export const metadata = {
-  name: 'my-plugin',
-  description: 'My custom c8ctl plugin',
-  commands: {
-    analyze: {
-      description: 'Analyze BPMN processes'
-    }
-  }
-};
-
-export const commands = {
-  analyze: async (args: string[]) => {
-    console.log('Analyzing...', args);
-  }
-};
-```
-
-When plugins are loaded, their commands automatically appear in `c8ctl help` output. See [PLUGIN-HELP.md](PLUGIN-HELP.md) for detailed documentation on plugin help integration.
+For plugin development (scaffolding, runtime API, flags, TypeScript support), see [PLUGIN-HELP.md](PLUGIN-HELP.md).
 
 ---
 
@@ -617,122 +546,60 @@ Run `c8ctl help cluster` for full details. See [EXAMPLES.md](EXAMPLES.md#local-c
 
 ---
 
-### Core Components
-
-- **Logger** (`src/logger.ts`): Handles output in text or JSON mode
-- **Config** (`src/config.ts`): Manages profiles, session state, and credential resolution
-- **Client** (`src/client.ts`): Factory for creating Camunda 8 SDK clients
-- **Commands** (`src/commands/`): Domain-specific command handlers
-
 ### Command Structure
 
 ```shell
 c8ctl <verb> <resource> [arguments] [flags]
 ```
 
+<!-- verb-resource-list:start -->
+<!-- Auto-generated from COMMAND_REGISTRY. Do not edit manually.
+     Run: node --experimental-strip-types scripts/sync-readme-commands.ts -->
+
 **Verbs**:
 
-- `list` - List resources
+- `list` - List resources (process, identity)
 - `search` - Search resources with filters
 - `get` - Get resource by key
 - `create` - Create resource
+- `delete` - Delete resource
 - `cancel` - Cancel resource
+- `await` - Create and await completion (alias for create --awaitCompletion)
 - `complete` - Complete resource
 - `fail` - Fail a job
-- `activate` - Activate jobs
+- `activate` - Activate jobs by type
 - `resolve` - Resolve incident
 - `publish` - Publish message
 - `correlate` - Correlate message
+- `set` - Set variables on an element instance
 - `deploy` - Deploy resources
 - `run` - Deploy and start process
-- `watch` (alias: `w`) - Watch for changes and auto-deploy
+- `assign` - Assign resource to target
+- `unassign` - Unassign resource from target
+- `watch` (alias: `w`) - Watch files for changes and auto-deploy
+- `open` - Open Camunda web application in browser
 - `add` - Add a profile
 - `remove` (alias: `rm`) - Remove a profile
-- `load` - Load a plugin
-- `unload` - Unload a plugin
+- `load` - Load a c8ctl plugin
+- `unload` (alias: `rm`) - Unload a c8ctl plugin
+- `upgrade` - Upgrade a plugin
+- `downgrade` - Downgrade a plugin to a specific version
 - `sync` - Synchronize plugins
+- `init` - Create a new plugin from TypeScript template
+- `doctor` - Diagnose plugin loading state and collisions
 - `use` - Set active profile or tenant
 - `output` - Show or set output format
-- `cluster` - Manage local Camunda 8 cluster (start, stop, status, logs, install, delete, list, list-remote)
 - `completion` - Generate shell completion script
+- `mcp-proxy` - Start a STDIO to remote HTTP MCP proxy server
 - `feedback` - Open the feedback page to report issues or request features
+- `help` (alias: `menu`) - Show help
+- `which` - Show active profile or output mode
 
-**Resources**: process-instance (pi), process-definition (pd), user-task (ut), incident (inc), job, jobs, variables (vars), message (msg), topology, profile, tenant, plugin
+**Resources**: authorization (auth), form, group, incident (inc), job, jobs, mapping-rule (mr), message (msg), plugin, process-definition (pd), process-instance (pi), profile, role, tenant, topology, user, user-task (ut), variable (var, vars)
+<!-- verb-resource-list:end -->
 
 **Tip**: Run `c8ctl help <command>` to see detailed help for specific commands with all available flags.
 
-## Testing
-
-### Run All Tests
-
-```bash
-npm test
-```
-
-### Run Unit Tests Only
-
-```bash
-npm run test:unit
-```
-
-### Run Integration Tests
-
-Integration tests require a running Camunda 8 instance at `http://localhost:8080`.
-
-1. Start a local Camunda 8 instance (e.g., using `c8ctl cluster start`)
-2. Run: `npm run test:integration`
-
-## Development
-
-- **Native TypeScript**: Runs directly with Node.js 22.18+ (no compilation needed)
-
-### Project Structure
-
-```shell
-c8ctl/
-├── src/
-│   ├── index.ts              # CLI entry point
-│   ├── logger.ts             # Output handling
-│   ├── config.ts             # Configuration management
-│   ├── client.ts             # SDK client factory
-│   └── commands/             # Command handlers
-│       └── ...
-├── tests/
-│   ├── unit/                 # Unit tests
-│   ├── integration/          # Integration tests
-│   └── fixtures/             # Test fixtures
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-### Running the CLI
-
-```bash
-# If installed globally
-c8ctl <command>
-# Or using the alias
-c8 <command>
-
-# For local development with Node.js 22.18+ (native TypeScript)
-node src/index.ts <command>
-
-# Testing with npm link (requires build first)
-npm run build
-npm link
-c8ctl <command>
-```
-
-**Note**: The build step is only required for publishing or using `npm link`. Development uses native TypeScript execution via `node src/index.ts`.
-
-### Adding New Commands
-
-1. Create command handler in `src/commands/`
-2. Wire into `src/index.ts` command routing
-3. Add tests in `tests/unit/` and `tests/integration/`
-4. Update help text in `src/commands/help.ts`
-5. Document in `EXAMPLES.md`
-
 ## Environment Variables
 
 - `CAMUNDA_BASE_URL`: Cluster base URL
@@ -821,7 +688,7 @@ These flags are available on `list` and `search` commands.
 | `--asc` | boolean |  | Sort ascending |
 | `--desc` | boolean |  | Sort descending |
 | `--limit` | string |  | Maximum number of results |
-| `--between` | string |  | Date range filter (e.g. 7d, 30d, 2024-01-01..2024-12-31) |
+| `--between` | string |  | Date range filter (e.g. 2024-01-01..2024-12-31, ..2024-12-31, 2024-01-01..) |
 | `--dateField` | string |  | Date field for --between filter |
 
 ### Commands
@@ -1686,12 +1553,11 @@ Remove a profile (alias: rm)
 
 **Aliases:** `rm`
 
-**Resources:** profile, plugin
+**Resources:** profile
 
 **Positional arguments:**
 
 - **profile:** `<name>` (required)
-- **plugin:** `<package>` (required)
 
 **Flags:**
 
@@ -1950,4 +1816,4 @@ Apache 2.0 - see LICENSE.md
 
 ## Contributing
 
-See `AGENTS.md` for commit message conventions.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, project structure, and how to add new commands. See [AGENTS.md](AGENTS.md) for commit conventions and coding standards.

package/dist/command-registry.d.ts

@@ -199,7 +199,7 @@ export declare const SEARCH_FLAGS: {
     };
     readonly between: {
         readonly type: "string";
-        readonly description: "Date range filter (e.g. 7d, 30d, 2024-01-01..2024-12-31)";
+        readonly description: "Date range filter (e.g. 2024-01-01..2024-12-31, ..2024-12-31, 2024-01-01..)";
     };
     readonly dateField: {
         readonly type: "string";
@@ -249,7 +249,7 @@ export declare const COMMAND_REGISTRY: {
             };
             between: {
                 readonly type: "string";
-                readonly description: "Date range filter (e.g. 7d, 30d, 2024-01-01..2024-12-31)";
+                readonly description: "Date range filter (e.g. 2024-01-01..2024-12-31, ..2024-12-31, 2024-01-01..)";
             };
             dateField: {
                 readonly type: "string";
@@ -541,7 +541,7 @@ export declare const COMMAND_REGISTRY: {
             };
             between: {
                 readonly type: "string";
-                readonly description: "Date range filter (e.g. 7d, 30d, 2024-01-01..2024-12-31)";
+                readonly description: "Date range filter (e.g. 2024-01-01..2024-12-31, ..2024-12-31, 2024-01-01..)";
             };
             dateField: {
                 readonly type: "string";
@@ -1612,10 +1612,6 @@ export declare const COMMAND_REGISTRY: {
                 readonly name: "name";
                 readonly required: true;
             }];
-            plugin: readonly [{
-                readonly name: "package";
-                readonly required: true;
-            }];
         };
     };
     load: {
@@ -1861,6 +1857,22 @@ export declare function resolveAlias(resource: string): string;
  * returns the first match. Use VERB_ALIASES directly for multi-target aliases.
  */
 export declare function getCommandDef(verb: string): CommandDef | undefined;
+/**
+ * Resolve a verb alias to its canonical verb name.
+ * Returns the input unchanged if it is already canonical (i.e. a direct
+ * registry key) or if no alias mapping exists.
+ *
+ * For multi-target aliases (e.g. "rm" → ["remove", "unload"]),
+ * disambiguates using the resource argument: picks the canonical verb
+ * whose `resources` list includes `resource`. Falls back to the first
+ * target when no resource is given or no match is found.
+ *
+ * Multi-target aliases should be unambiguous at declaration time: each
+ * target verb should own a disjoint set of resources. If two targets
+ * both declare the same resource, the first match wins — fix the
+ * registry to remove the overlap rather than adding runtime tiebreakers.
+ */
+export declare function resolveVerbAlias(verb: string, resource?: string): string;
 /**
  * Get all flags accepted for a given verb, including global flags and any
  * resource-scoped flags declared under `resourceFlags`.