{"id":45840804,"url":"https://github.com/camunda/c8ctl","last_synced_at":"2026-05-31T23:00:58.614Z","repository":{"id":339080290,"uuid":"1144087440","full_name":"camunda/c8ctl","owner":"camunda","description":"a cli for Camunda 8 Cluster inspection, Process Management, and Dev-time support","archived":false,"fork":false,"pushed_at":"2026-05-26T16:41:38.000Z","size":3370,"stargazers_count":6,"open_issues_count":47,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T17:30:54.733Z","etag":null,"topics":["ai-first-check","camunda-8","camunda-bpm-platform","camunda-engine","cli","zeebe"],"latest_commit_sha":null,"homepage":"https://docs.camunda.io/docs/next/apis-tools/c8ctl/getting-started/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/camunda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-28T09:22:36.000Z","updated_at":"2026-05-26T03:36:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/camunda/c8ctl","commit_stats":null,"previous_names":["camunda/c8ctl"],"tags_count":108,"template":false,"template_full_name":null,"purl":"pkg:github/camunda/c8ctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fc8ctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fc8ctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fc8ctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fc8ctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/camunda","download_url":"https://codeload.github.com/camunda/c8ctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda%2Fc8ctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33752286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-first-check","camunda-8","camunda-bpm-platform","camunda-engine","cli","zeebe"],"created_at":"2026-02-27T00:05:45.159Z","updated_at":"2026-05-31T23:00:58.607Z","avatar_url":"https://github.com/camunda.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cocktail (c8ctl) - Camunda 8 CLI\n\nc8ctl (_pronounced: \"cocktail\"_) — a minimal-dependency CLI for Camunda 8 operations built on top of [`@camunda8/orchestration-cluster-api`](https://www.npmjs.com/package/@camunda8/orchestration-cluster-api).\n\n## Features\n\n- **Multi-Tenant Support**: Full support for multi-tenancy across all operations\n- **Profile Management**: Store and manage multiple cluster configurations\n- **Camunda Modeler Integration**: Automatically import and use profiles from Camunda Modeler\n- **Identity Management**: Manage users, roles, groups, tenants, authorizations, and mapping rules\n- **Plugin System**: Extend c8ctl with custom commands via npm packages\n- **Local Cluster**: Run a local Camunda 8 instance directly — no Docker required\n- **MCP Proxy**: Bridge local MCP clients to remote Camunda 8 for AI agent integration\n- **Building Block Deployment**: Automatic prioritization of `*_bb-*` folders during deployment, marked with 🧱 in results\n- **Process Application Support**: Resources in folders with `.process-application` file marked with 📦 in results\n- **Enhanced Deployment Results**: Table view showing file paths, visual indicators, resource details, and versions\n- **Watch Mode**: Monitors a folder for file changes and auto-redeploys (configurable extensions via `--extensions`)\n- **`.c8ignore` Support**: Filter deploy/watch file scanning with `.gitignore`-style patterns; `node_modules/`, `target/`, `.git/` ignored by default\n- **Open Applications**: Open Camunda web applications (Operate, Tasklist, Modeler, Optimize) in the browser directly from the CLI\n- **Search**: Powerful search across process definitions, process instances, user tasks, incidents, jobs, and variables with filter, wildcard, and case-insensitive support\n- **Flexible Output**: Switch between human-readable text and JSON output modes\n- **Shell Completion**: Auto-install completions for bash, zsh, and fish with automatic refresh on upgrade\n- **Agent Flags**: `--dry-run` to preview API requests and `--fields` to filter output columns for AI agents and scripts\n- **Debug Mode**: Enable detailed logging to stderr with `DEBUG=1` or `C8CTL_DEBUG=true`\n\n## Beware the 🤖\n\n_Full transparency_:  \nthis cli is also a pilot-coding experiment, practicing [Agentic Engineering](https://addyosmani.com/blog/agentic-engineering/).  \nGuided by humans, the codebase is (mostly) built by your friendly neighborhood LLM, fully dogfooding the Human-in-the-Loop pattern.\n\n## Installation\n\n### Requirements\n\n- Node.js \u003e= 22.18.0 (for native TypeScript support)\n\n### Global Installation (Recommended)\n\n```bash\nnpm install @camunda8/cli -g\n```\n\nAfter installation, the CLI is available as `c8ctl` (or its alias `c8`).\n\n**Note**: The `c8` alias provides typing ergonomics for common keyboard layouts - the `c` key (left index finger) followed by `8` (right middle finger) makes for a comfortable typing experience on both QWERTY and QWERTZ keyboards.\n\n## Usage\n\n### Getting Help\n\n```bash\n# Show general help\nc8ctl help\n\n# Show detailed help for specific commands with all flags\nc8ctl help list       # Shows all list resources and their flags\nc8ctl help get        # Shows all get resources and their flags\nc8ctl help create     # Shows all create resources and their flags\nc8ctl help complete   # Shows all complete resources and their flags\nc8ctl help await      # Shows await command with all flags\nc8ctl help search     # Shows all search resources and their flags\nc8ctl help deploy     # Shows deploy command with all flags\nc8ctl help run        # Shows run command with all flags\nc8ctl help watch      # Shows watch command with all flags\nc8ctl help open       # Shows open command with all apps\nc8ctl help cancel     # Shows cancel command with all flags\nc8ctl help resolve    # Shows resolve command with all flags\nc8ctl help fail       # Shows fail command with all flags\nc8ctl help activate   # Shows activate command with all flags\nc8ctl help publish    # Shows publish command with all flags\nc8ctl help correlate  # Shows correlate command with all flags\nc8ctl help cluster    # Shows local cluster management help\nc8ctl help profiles   # Shows profile management help\nc8ctl help plugin     # Shows plugin management help\n\n# Show version\nc8ctl --version\n```\n\n### Default Extensions\n\nWhen scanning directories, `deploy` and `watch` only include files with these extensions by default:\n\n`.bpmn`, `.dmn`, `.form`\n\nExplicitly named files bypass the extension allow-list (e.g. `c8 deploy my-doc.md`). Note that `.c8ignore` rules still apply.\n\nUse `--extensions` to add more types during directory discovery (merged with defaults):\n\n```bash\nc8 deploy --extensions=.md,.txt\nc8 watch --extensions=.md\n```\n\nUse `--all-extensions` to include all server-supported types (`.md`, `.txt`, `.xml`, `.rpa`, `.json`, `.config`, `.yml`, `.yaml`):\n\n```bash\nc8 deploy --all-extensions\n```\n\nSkipped files are logged to stderr with an actionable hint.\n\n### Ignoring Files (`.c8ignore`)\n\nWhen scanning directories for deployment artifacts, c8ctl automatically ignores:\n\n- `node_modules/`\n- `target/`\n- `.git/`\n\nCreate a `.c8ignore` file in your project root to add custom patterns (`.gitignore` syntax):\n\n```gitignore\n# Ignore build output\ndist/\nbuild/\n\n# Ignore draft processes\n**/draft-*.bpmn\n\n# But keep this specific one\n!draft-approved.bpmn\n```\n\n`.c8ignore` rules apply to both `deploy` (directory scan) and `watch` (file monitoring).\n\nFor comprehensive examples of all commands and their flags, see [EXAMPLES.md](EXAMPLES.md).\n\n### Shell Completion\n\nc8ctl supports shell completion for `bash`, `zsh`, and `fish`.\n\n#### Quick Install (recommended)\n\n```bash\n# Auto-detect your shell and install completions\nc8ctl completion install\n\n# Or specify a shell explicitly\nc8ctl completion install --shell zsh\n```\n\nThis 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.\n\n#### Manual setup\n\nIf you prefer to manage the completion script yourself, generate it with\n`c8ctl completion \u003cshell\u003e` (where `\u003cshell\u003e` is `bash`, `zsh`, or `fish`),\nthen source or install it:\n\n```bash\n# Bash\nc8ctl completion bash \u003e ~/.c8ctl-completion.bash\necho 'source ~/.c8ctl-completion.bash' \u003e\u003e ~/.bashrc\nsource ~/.c8ctl-completion.bash\n\n# Zsh\nc8ctl completion zsh \u003e ~/.c8ctl-completion.zsh\necho 'source ~/.c8ctl-completion.zsh' \u003e\u003e ~/.zshrc\nsource ~/.c8ctl-completion.zsh\n\n# Fish (auto-loaded on next start)\nc8ctl completion fish \u003e ~/.config/fish/completions/c8ctl.fish\n```\n\n### Credential Resolution\n\nCredentials are resolved in the following order:\n\n1. `--profile` flag (one-off override)\n2. Active profile from session state (⚠ warns if `CAMUNDA_*` env vars are also present)\n3. Environment variables (`CAMUNDA_*`)\n4. Default `local` profile (`http://localhost:8080/v2`)\n\n**Note**: Credential configuration via environment variables follows the same conventions as the `@camunda8/orchestration-cluster-api` module.\n\n```bash\n# Using environment variables\nexport CAMUNDA_BASE_URL=https://camunda.example.com\nexport CAMUNDA_CLIENT_ID=your-client-id\nexport CAMUNDA_CLIENT_SECRET=your-client-secret\nc8ctl list process-instances\n\n# Create a profile from a .env file\nc8ctl add profile staging --from-file .env.staging\n\n# Create a profile from current environment variables\nsource .env.prod\nc8ctl add profile prod --from-env\n\n# Clear the active session profile (so env vars take effect)\nc8ctl use profile --none\n\n# Using profile override\nc8ctl list process-instances --profile prod\n```\n\n### Tenant Resolution\n\nTenants are resolved in the following order:\n\n1. Active tenant from session state\n2. Default tenant from active profile\n3. `CAMUNDA_DEFAULT_TENANT_ID` environment variable\n4. `\u003cdefault\u003e` tenant\n\n```bash\n# Set active tenant for the session\nc8ctl use tenant my-tenant-id\n\n# Now all commands use this tenant\nc8ctl list process-instances\n```\n\n### Profile Management\n\nc8ctl supports two types of profiles:\n\n1. **c8ctl profiles**: Managed directly by c8ctl\n2. **Camunda Modeler profiles**: Automatically imported from Camunda Modeler (with `modeler:` prefix)\n\nFor profile-related commands and flags, run:\n\n```bash\nc8ctl help profiles\n```\n\n```bash\n# Add a c8ctl profile\nc8 add profile prod --baseUrl=https://camunda.example.com --clientId=xxx --clientSecret=yyy\n\n# List all profiles (includes both c8ctl and modeler profiles)\nc8 list profiles\n\n# Set active profile (works with both types)\nc8 use profile prod\nc8 use profile \"modeler:Local Dev\"\n\n# Remove c8ctl profile (modeler profiles are read-only)\nc8 remove profile prod\n```\n\n#### Camunda Modeler Integration\n\nc8ctl automatically reads profiles from Camunda Modeler's `profiles.json` file. These profiles are:\n\n- **Read-only**: Cannot be modified or deleted via c8ctl\n- **Prefixed**: Always displayed with `modeler:` prefix (e.g., `modeler:Local Dev`)\n- **Dynamic**: Loaded fresh on each command execution (no caching)\n- **Platform-specific locations**:\n  - Linux: `~/.config/camunda-modeler/profiles.json`\n  - macOS: `~/Library/Application Support/camunda-modeler/profiles.json`\n  - Windows: `%APPDATA%\\camunda-modeler\\profiles.json`\n\n**Using modeler profiles:**\n\n```bash\n# List includes modeler profiles with 'modeler:' prefix\nc8 list profiles\n\n# Use a modeler profile by name\nc8 use profile modeler:Local Dev\n\n# Use a modeler profile by cluster ID\nc8 use profile modeler:abc123-def456\n\n# One-off command with modeler profile\nc8 list pi --profile=modeler:Cloud Cluster\n```\n\n**URL Construction:**\n\n- **Self-managed** (localhost): Appends `/v2` to the URL (e.g., `http://localhost:8080/v2`)\n- **Cloud**: Uses the cluster URL as-is (e.g., `https://abc123.region.zeebe.camunda.io`)\n- **Any port**: Supports any port number in the URL\n\n### Session Management\n\n```bash\n# Show current output mode\nc8ctl output\n\n# Switch to JSON output\nc8ctl output json\n\n# Switch back to text output\nc8ctl output text\n```\n\n#### Per-invocation output override\n\nThe persisted output mode (set by `c8ctl output json|text`) can be overridden for a single invocation without mutating `session.json`. This is useful for scripts, agent integrations, and one-off JSON capture without flipping global state.\n\nPrecedence (highest first):\n\n1. `--json` global flag — force JSON for this invocation only.\n2. `C8CTL_OUTPUT_MODE` env var — accepts `json` or `text`. Other values (including unset or typos) fall through to the persisted mode without erroring.\n3. Persisted `session.json` `outputMode`.\n\n```bash\n# Force JSON for one command — session.json is not touched\nc8ctl --json list profile\n\n# Same effect via env var (handy for scoped shells / CI steps)\nC8CTL_OUTPUT_MODE=json c8ctl list profile\n\n# --json wins over the env var\nC8CTL_OUTPUT_MODE=text c8ctl --json list profile  # → JSON\n```\n\n### Debug Mode\n\nEnable debug logging to see detailed information about plugin loading and other internal operations:\n\n```bash\n# Enable debug mode with environment variable\nDEBUG=1 c8 \u003ccommand\u003e\n\n# Or use C8CTL_DEBUG\nC8CTL_DEBUG=true c8 \u003ccommand\u003e\n\n# Example: See plugin loading details\nDEBUG=1 c8 list plugins\n```\n\nDebug output is written to stderr with timestamps and won't interfere with normal command output.\n\n### Plugin Management\n\nc8ctl supports a global plugin system that allows extending the CLI with custom commands via npm packages. Plugins are installed globally to a user-specific directory and tracked in a registry file.\n\n**Plugin Storage Locations:**\n\nThe plugin system uses OS-specific directories:\n\n| OS | Plugins Directory | Registry File |\n|----|-------------------|---------------|\n| **Linux** | `~/.config/c8ctl/plugins/node_modules` | `~/.config/c8ctl/plugins.json` |\n| **macOS** | `~/Library/Application Support/c8ctl/plugins/node_modules` | `~/Library/Application Support/c8ctl/plugins.json` |\n| **Windows** | `%APPDATA%\\c8ctl\\plugins\\node_modules` | `%APPDATA%\\c8ctl\\plugins.json` |\n\n\u003e **Note:** You can override the data directory with the `C8CTL_DATA_DIR` environment variable.\n\n```bash\n# Create a new plugin from template\nc8ctl init plugin my-plugin\n\n# Load a plugin from npm registry\nc8ctl load plugin \u003cpackage-name\u003e\n\n# Load a plugin from a URL (including file URLs)\nc8ctl load plugin --from \u003curl\u003e\nc8ctl load plugin --from file:///path/to/plugin\nc8ctl load plugin --from https://github.com/user/repo\nc8ctl load plugin --from git://github.com/user/repo.git\n\n# Upgrade a plugin to latest or specific version\nc8ctl upgrade plugin \u003cpackage-name\u003e\nc8ctl upgrade plugin \u003cpackage-name\u003e 1.2.3\n\n# Downgrade a plugin to a specific version\nc8ctl downgrade plugin \u003cpackage-name\u003e 1.0.0\n\n# Unload a plugin\nc8ctl unload plugin \u003cpackage-name\u003e\n\n# List installed plugins (shows version and sync status)\nc8ctl list plugins\n\n# Synchronize plugins from registry\n# - First tries npm rebuild for installed plugins\n# - Falls back to fresh npm install if rebuild fails\nc8ctl sync plugins\n\n# View help including plugin commands\nc8ctl help\n```\n\n**Global Plugin System:**\n\n- Plugins are installed to a global directory (OS-specific, see table above)\n- Plugin registry file (`plugins.json`) tracks all installed plugins\n- No local `package.json` is required in your working directory\n- Plugins are available globally from any directory\n- The registry serves as the source of truth for installed plugins\n- Default plugins are bundled with c8ctl and loaded automatically\n- **Plugin commands cannot override built-in commands** - built-in commands always take precedence\n- `c8ctl list plugins` shows plugin versions and sync status:\n  - `✓ Installed` - Plugin is in registry and installed\n  - `⚠ Not installed` - Plugin is in registry but not in global directory (run `sync`)\n  - `⚠ Not in registry` - Plugin is installed but not tracked in registry\n- `c8ctl sync plugins` synchronizes plugins from the registry, rebuilding or reinstalling as needed\n- `c8ctl upgrade plugin \u003cname\u003e [version]` respects the plugin source from the registry:\n  - without `version`: reinstalls the registered source as-is\n  - npm package source with `version`: installs `\u003cname\u003e@\u003cversion\u003e`\n  - URL/git source with `version`: installs `\u003csource\u003e#\u003cversion\u003e`\n  - file source (`file://`) with `version`: version upgrade is not supported; use `load plugin --from` with the desired local plugin checkout\n- `c8ctl downgrade plugin \u003cname\u003e \u003cversion\u003e` respects the plugin source from the registry:\n  - npm package source: installs `\u003cname\u003e@\u003cversion\u003e`\n  - URL/git source: installs `\u003csource\u003e#\u003cversion\u003e`\n  - file source (`file://`): version downgrade is not supported; use `load plugin --from` with the desired local plugin checkout\n\nWhen plugins are loaded, their commands automatically appear in `c8ctl help` output.\n\nFor plugin development (scaffolding, runtime API, flags, TypeScript support), see [PLUGIN-HELP.md](PLUGIN-HELP.md).\n\n---\n\n## Agent Usage (AI / Programmatic Consumption)\n\nc8ctl ships two flags designed specifically for AI agents and programmatic consumers.\nThey appear in their own clearly labelled section in `c8ctl help`.\n\n\u003e For a full machine-readable reference, see [`CONTEXT.md`](./CONTEXT.md).\n\n### `--fields \u003ccomma-separated\u003e`\n\nFilters output to only the specified field names. Applies to all `list`, `search`,\nand `get` commands. Field matching is **case-insensitive**.\n\n```bash\n# Only return Key and State columns — reduces context window size\nc8ctl list pi --fields Key,State\nc8ctl search pd --fields Key,processDefinitionId,name\n\n# Works in both text and JSON modes\nc8ctl output json\nc8ctl list pi --fields Key,State,processDefinitionId | jq .\n```\n\n### `--dry-run`\n\nPreviews the API request that **would** be sent without executing it.\nWorks on **all commands**: queries (`list`, `search`, `get`) and mutations\n(`create`, `cancel`, `deploy`, `complete`, `fail`, `activate`, `resolve`,\n`publish`, `correlate`).\n\nEmits a JSON object to stdout and exits 0:\n```json\n{\n  \"dryRun\": true,\n  \"command\": \"create process-instance\",\n  \"method\": \"POST\",\n  \"url\": \"http://localhost:8080/v2/process-instances\",\n  \"body\": { \"processDefinitionId\": \"my-process\", \"tenantId\": \"\u003cdefault\u003e\" }\n}\n```\n\n**Recommended agent workflow for mutations:**\n1. Run with `--dry-run` and show the user the would-be API call\n2. Wait for user confirmation\n3. Re-run without `--dry-run` to execute\n\n```bash\n# Preview before creating\nc8ctl create pi --id=my-process --dry-run\n\n# Preview a deployment\nc8ctl deploy ./my-process.bpmn --dry-run\n\n# Preview cancelling a process instance\nc8ctl cancel pi 2251799813685249 --dry-run\n\n# Debug a search query — see the filter body that would be sent\nc8ctl search pi --state ACTIVE --between 2024-01-01..2024-12-31 --dry-run\n\n# Inspect a list operation\nc8ctl list pd --dry-run\n\n# Preview a get request\nc8ctl get pi 12345 --dry-run\n```\n\n### Machine-Readable Help (JSON Mode)\n\nIn JSON output mode, `c8ctl help` emits structured JSON containing the full\ncommand tree, flags (with types), and agent flags:\n\n```bash\nc8ctl output json\nc8ctl help          # → JSON with commands[], globalFlags[], agentFlags[], resourceAliases\nc8ctl help list     # → JSON for specific command\n```\n\n---\n\n### Local Cluster\n\nc8ctl includes a built-in `cluster` command for managing a local Camunda 8 instance (powered by a default plugin). No Docker or docker-compose required — it downloads and runs Camunda directly.\n\n```bash\n# Start the latest stable version\nc8ctl cluster start\n\n# Start a specific version\nc8ctl cluster start 8.9\nc8ctl cluster start 8.9.0-alpha5\n\n# Stop the running cluster\nc8ctl cluster stop\n\n# Check cluster status\nc8ctl cluster status\n\n# Stream cluster logs\nc8ctl cluster logs\n\n# List locally cached versions\nc8ctl cluster list\n\n# List available remote versions\nc8ctl cluster list-remote\n\n# Pre-download a version without starting it\nc8ctl cluster install 8.9\n\n# Remove a cached version\nc8ctl cluster delete 8.9\n```\n\n#### Version Aliases\n\nInstead of an exact version number, you can use:\n\n- **`stable`** — the latest GA release (highest minor version that has shipped a `.0` release)\n- **`alpha`** — the latest alpha-train release (highest minor version overall, which may only have alpha builds)\n- **A major.minor pattern** like `8.9` — resolves to the latest patch/alpha within that minor\n\n`c8ctl cluster start` with no version argument defaults to `stable`.\n\n```bash\nc8ctl cluster start stable\nc8ctl cluster start alpha\nc8ctl cluster start 8.9     # latest 8.9.x\n```\n\n#### Online vs Offline Behaviour\n\n- **`cluster start`** prefers locally cached versions. If the requested version is already installed, it starts immediately without going online. A non-blocking background check runs to hint if a newer build is available, but never delays startup.\n- **`cluster install`** always checks the remote download server for the latest build. If a newer ETag is detected for an already-installed version, it re-downloads.\n- **`cluster list-remote`** fetches the full list of available versions from the download server.\n- **Offline fallback**: if the network is unavailable, alias resolution falls back to a locally cached mapping, then to a hardcoded default.\n\nRun `c8ctl help cluster` for full details. See [EXAMPLES.md](EXAMPLES.md#local-cluster) for a complete local development workflow.\n\n---\n\n### Command Structure\n\n```shell\nc8ctl \u003cverb\u003e \u003cresource\u003e [arguments] [flags]\n```\n\n\u003c!-- verb-resource-list:start --\u003e\n\u003c!-- Auto-generated from COMMAND_REGISTRY. Do not edit manually.\n     Run: node --experimental-strip-types scripts/sync-readme-commands.ts --\u003e\n\n**Verbs**:\n\n- `list` - List resources (process, identity)\n- `search` - Search resources with filters\n- `get` - Get resource by key\n- `create` - Create resource\n- `delete` - Delete resource\n- `cancel` - Cancel resource\n- `await` - Create and await completion (alias for create --awaitCompletion)\n- `complete` - Complete resource\n- `fail` - Fail a job\n- `activate` - Activate jobs by type\n- `resolve` - Resolve incident\n- `publish` - Publish message\n- `correlate` - Correlate message\n- `set` - Set variables on an element instance\n- `deploy` - Deploy resources\n- `run` - Deploy and start process\n- `assign` - Assign resource to target\n- `unassign` - Unassign resource from target\n- `watch` (alias: `w`) - Watch files for changes and auto-deploy\n- `open` - Open Camunda web application in browser\n- `add` - Add a profile\n- `remove` (alias: `rm`) - Remove a profile\n- `load` - Load a c8ctl plugin\n- `unload` (alias: `rm`) - Unload a c8ctl plugin\n- `upgrade` - Upgrade a plugin\n- `downgrade` - Downgrade a plugin to a specific version\n- `sync` - Synchronize plugins\n- `init` - Create a new plugin from TypeScript template\n- `doctor` - Diagnose plugin loading state and collisions\n- `use` - Set active profile or tenant\n- `output` - Show or set output format\n- `completion` - Generate shell completion script\n- `mcp-proxy` - Start a STDIO to remote HTTP MCP proxy server\n- `feedback` - Open the feedback page to report issues or request features\n- `help` (alias: `menu`) - Show help\n- `which` - Show active profile or output mode\n\n**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)\n\u003c!-- verb-resource-list:end --\u003e\n\n**Tip**: Run `c8ctl help \u003ccommand\u003e` to see detailed help for specific commands with all available flags.\n\n## Environment Variables\n\n- `CAMUNDA_BASE_URL`: Cluster base URL\n- `CAMUNDA_CLIENT_ID`: OAuth client ID\n- `CAMUNDA_CLIENT_SECRET`: OAuth client secret\n- `CAMUNDA_TOKEN_AUDIENCE`: OAuth token audience\n- `CAMUNDA_OAUTH_URL`: OAuth token endpoint\n- `CAMUNDA_DEFAULT_TENANT_ID`: Default tenant ID\n- `C8CTL_OUTPUT_MODE`: Per-invocation output mode override (`json` or `text`); does not persist. Lower precedence than `--json`. See [Per-invocation output override](#per-invocation-output-override).\n- `C8CTL_DATA_DIR`: Override the OS-default data directory for plugins and session state.\n- `C8CTL_DEBUG` / `DEBUG`: Enable debug logging to stderr.\n\n## Configuration Files\n\n### c8ctl Configuration\n\nConfiguration is stored in platform-specific user data directories:\n\n- **Linux**: `~/.config/c8ctl/`\n- **macOS**: `~/Library/Application Support/c8ctl/`\n- **Windows**: `%APPDATA%\\c8ctl\\`\n\nFiles:\n\n- `profiles.json`: Saved cluster configurations\n- `session.json`: Active profile, tenant, and output mode\n- `plugins.json`: Plugin registry tracking installed plugins\n\n### Camunda Modeler Configuration\n\nc8ctl automatically reads profiles from Camunda Modeler (if installed):\n\n- **Linux**: `~/.config/camunda-modeler/profiles.json`\n- **macOS**: `~/Library/Application Support/camunda-modeler/profiles.json`\n- **Windows**: `%APPDATA%\\camunda-modeler\\profiles.json`\n\nModeler profiles are:\n\n- Read-only in c8ctl (managed via Camunda Modeler)\n- Automatically loaded on each command execution\n- Prefixed with `modeler:` when used in c8ctl\n- Support both cloud and self-managed clusters\n\n\u003c!-- command-reference:start --\u003e\n\n## Command Reference\n\n\u003c!-- Auto-generated from COMMAND_REGISTRY. Do not edit manually.\n     Run: node --experimental-strip-types scripts/sync-readme-commands.ts --\u003e\n\n### Global Flags\n\nThese flags are accepted by every command.\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--help` / `-h` | boolean |  | Show help |\n| `--version` / `-v` | string |  | Show CLI version, or filter by process definition version on supported commands |\n| `--profile` | string |  | Use a specific profile |\n| `--dry-run` | boolean |  | Preview the API request without executing |\n| `--verbose` | boolean |  | Show verbose output |\n| `--fields` | string |  | Comma-separated list of fields to display |\n| `--json` | boolean |  | Force JSON output for this invocation (does not persist; overrides session state and C8CTL_OUTPUT_MODE) |\n\n### Resource Aliases\n\n| Alias | Resource |\n|-------|----------|\n| `auth` | `authorization` |\n| `inc` | `incident` |\n| `mr` | `mapping-rule` |\n| `msg` | `message` |\n| `pd` | `process-definition` |\n| `pi` | `process-instance` |\n| `ut` | `user-task` |\n| `vars` | `variable` |\n| `var` | `variable` |\n\n### Search Flags\n\nThese flags are available on `list` and `search` commands.\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--sortBy` | string |  | Sort results by field |\n| `--asc` | boolean |  | Sort ascending |\n| `--desc` | boolean |  | Sort descending |\n| `--limit` | string |  | Maximum number of results |\n| `--between` | string |  | Date range filter (e.g. 2024-01-01..2024-12-31, ..2024-12-31, 2024-01-01..) |\n| `--dateField` | string |  | Date field for --between filter |\n\n### Commands\n\n#### `list`\n\nList resources\n\n**Resources:** pi (process-instance), pd (process-definition), ut (user-task), inc (incident), jobs, profiles (profile), plugins (plugin), users (user), roles (role), groups (group), tenants (tenant), auth (authorization), mapping-rules (mapping-rule)\n\n**Verb-level flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--all` | boolean |  | List all (disable pagination limit) |\n\n**Resource-specific flags:**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eprocess-definition\u003c/code\u003e (\u003ccode\u003epd\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--bpmnProcessId` | string |  | Filter by BPMN process ID |\n| `--id` | string |  | Filter by BPMN process ID (alias) |\n| `--processDefinitionId` | string |  | Filter by process definition ID |\n| `--name` | string |  | Filter by name |\n| `--key` | string |  | Filter by key |\n| `--iid` | string |  | Case-insensitive filter by BPMN process ID |\n| `--iname` | string |  | Case-insensitive filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eprocess-instance\u003c/code\u003e (\u003ccode\u003epi\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--bpmnProcessId` | string |  | Filter by BPMN process ID |\n| `--id` | string |  | Filter by BPMN process ID (alias) |\n| `--processDefinitionId` | string |  | Filter by process definition ID |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--state` | string |  | Filter by state (ACTIVE, COMPLETED, etc) |\n| `--key` | string |  | Filter by key |\n| `--parentProcessInstanceKey` | string |  | Filter by parent process instance key |\n| `--iid` | string |  | Case-insensitive filter by BPMN process ID |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003euser-task\u003c/code\u003e (\u003ccode\u003eut\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--state` | string |  | Filter by state |\n| `--assignee` | string |  | Filter by assignee |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--elementId` | string |  | Filter by element ID |\n| `--iassignee` | string |  | Case-insensitive filter by assignee |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eincident\u003c/code\u003e (\u003ccode\u003einc\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--state` | string |  | Filter by state |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--bpmnProcessId` | string |  | Filter by BPMN process ID |\n| `--id` | string |  | Filter by BPMN process ID (alias) |\n| `--processDefinitionId` | string |  | Filter by process definition ID |\n| `--errorType` | string |  | Filter by error type |\n| `--errorMessage` | string |  | Filter by error message |\n| `--ierrorMessage` | string |  | Case-insensitive filter by error message |\n| `--iid` | string |  | Case-insensitive filter by BPMN process ID |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ejobs\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--state` | string |  | Filter by state |\n| `--type` | string |  | Filter by job type |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--itype` | string |  | Case-insensitive filter by job type |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003euser\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--username` | string |  | Filter by username |\n| `--name` | string |  | Filter by name |\n| `--email` | string |  | Filter by email |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003erole\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--roleId` | string |  | Filter by role ID |\n| `--name` | string |  | Filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egroup\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--groupId` | string |  | Filter by group ID |\n| `--name` | string |  | Filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003etenant\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--tenantId` | string |  | Filter by tenant ID |\n| `--name` | string |  | Filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eauthorization\u003c/code\u003e (\u003ccode\u003eauth\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--ownerId` | string |  | Filter by owner ID |\n| `--ownerType` | string |  | Filter by owner type |\n| `--resourceType` | string |  | Filter by resource type |\n| `--resourceId` | string |  | Filter by resource ID |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003emapping-rule\u003c/code\u003e (\u003ccode\u003emr\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--mappingRuleId` | string |  | Filter by mapping rule ID |\n| `--name` | string |  | Filter by name |\n| `--claimName` | string |  | Filter by claim name |\n| `--claimValue` | string |  | Filter by claim value |\n\n\u003c/details\u003e\n\n**Examples:**\n\n```bash\nc8ctl list pi                                               # List process instances\nc8ctl list pd                                               # List process definitions\nc8ctl list users                                            # List users\n```\n\n---\n\n#### `search`\n\nSearch resources with filters (wildcards, date ranges, case-insensitive)\n\n**Resources:** pi (process-instance), pd (process-definition), ut (user-task), inc (incident), jobs, vars (variable), users (user), roles (role), groups (group), tenants (tenant), auth (authorization), mapping-rules (mapping-rule)\n\n**Resource-specific flags:**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eprocess-definition\u003c/code\u003e (\u003ccode\u003epd\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--bpmnProcessId` | string |  | Filter by BPMN process ID |\n| `--id` | string |  | Filter by BPMN process ID (alias) |\n| `--processDefinitionId` | string |  | Filter by process definition ID |\n| `--name` | string |  | Filter by name |\n| `--key` | string |  | Filter by key |\n| `--iid` | string |  | Case-insensitive filter by BPMN process ID |\n| `--iname` | string |  | Case-insensitive filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eprocess-instance\u003c/code\u003e (\u003ccode\u003epi\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--bpmnProcessId` | string |  | Filter by BPMN process ID |\n| `--id` | string |  | Filter by BPMN process ID (alias) |\n| `--processDefinitionId` | string |  | Filter by process definition ID |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--state` | string |  | Filter by state (ACTIVE, COMPLETED, etc) |\n| `--key` | string |  | Filter by key |\n| `--parentProcessInstanceKey` | string |  | Filter by parent process instance key |\n| `--iid` | string |  | Case-insensitive filter by BPMN process ID |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003euser-task\u003c/code\u003e (\u003ccode\u003eut\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--state` | string |  | Filter by state |\n| `--assignee` | string |  | Filter by assignee |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--elementId` | string |  | Filter by element ID |\n| `--iassignee` | string |  | Case-insensitive filter by assignee |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eincident\u003c/code\u003e (\u003ccode\u003einc\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--state` | string |  | Filter by state |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--bpmnProcessId` | string |  | Filter by BPMN process ID |\n| `--id` | string |  | Filter by BPMN process ID (alias) |\n| `--processDefinitionId` | string |  | Filter by process definition ID |\n| `--errorType` | string |  | Filter by error type |\n| `--errorMessage` | string |  | Filter by error message |\n| `--ierrorMessage` | string |  | Case-insensitive filter by error message |\n| `--iid` | string |  | Case-insensitive filter by BPMN process ID |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003ejobs\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--state` | string |  | Filter by state |\n| `--type` | string |  | Filter by job type |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--processDefinitionKey` | string |  | Filter by process definition key |\n| `--itype` | string |  | Case-insensitive filter by job type |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003evariable\u003c/code\u003e (\u003ccode\u003evar\u003c/code\u003e, \u003ccode\u003evars\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--name` | string |  | Filter by variable name |\n| `--value` | string |  | Filter by value |\n| `--processInstanceKey` | string |  | Filter by process instance key |\n| `--scopeKey` | string |  | Filter by scope key |\n| `--fullValue` | boolean |  | Return full variable values (not truncated) |\n| `--iname` | string |  | Case-insensitive filter by name |\n| `--ivalue` | string |  | Case-insensitive filter by value |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003euser\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--username` | string |  | Filter by username |\n| `--name` | string |  | Filter by name |\n| `--email` | string |  | Filter by email |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003erole\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--roleId` | string |  | Filter by role ID |\n| `--name` | string |  | Filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003egroup\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--groupId` | string |  | Filter by group ID |\n| `--name` | string |  | Filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003etenant\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--tenantId` | string |  | Filter by tenant ID |\n| `--name` | string |  | Filter by name |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eauthorization\u003c/code\u003e (\u003ccode\u003eauth\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--ownerId` | string |  | Filter by owner ID |\n| `--ownerType` | string |  | Filter by owner type |\n| `--resourceType` | string |  | Filter by resource type |\n| `--resourceId` | string |  | Filter by resource ID |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003emapping-rule\u003c/code\u003e (\u003ccode\u003emr\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--mappingRuleId` | string |  | Filter by mapping rule ID |\n| `--name` | string |  | Filter by name |\n| `--claimName` | string |  | Filter by claim name |\n| `--claimValue` | string |  | Filter by claim value |\n\n\u003c/details\u003e\n\n**Examples:**\n\n```bash\nc8ctl search pi --state=ACTIVE                              # Search for active process instances\nc8ctl search pd --bpmnProcessId=myProcess                   # Search process definitions by ID\nc8ctl search pd --name='*main*'                             # Search process definitions with wildcard\nc8ctl search ut --assignee=john                             # Search user tasks assigned to john\nc8ctl search inc --state=ACTIVE                             # Search for active incidents\nc8ctl search jobs --type=myJobType                          # Search jobs by type\nc8ctl search jobs --type='*service*'                        # Search jobs with type containing \"service\"\nc8ctl search variables --name=myVar                         # Search for variables by name\nc8ctl search variables --value=foo                          # Search for variables by value\nc8ctl search variables --processInstanceKey=123 --fullValue  # Search variables with full values\nc8ctl search pd --iname='*order*'                           # Case-insensitive search by name\nc8ctl search ut --iassignee=John                            # Case-insensitive search by assignee\n```\n\n---\n\n#### `get`\n\nGet a resource by key\n\n**Resources:** pi (process-instance), pd (process-definition), inc (incident), topology, form, user, role, group, tenant, auth (authorization), mapping-rule\n\n**Positional arguments:**\n\n- **process-definition:** `\u003ckey\u003e` (required)\n- **process-instance:** `\u003ckey\u003e` (required)\n- **incident:** `\u003ckey\u003e` (required)\n- **user:** `\u003cusername\u003e` (required)\n- **role:** `\u003croleId\u003e` (required)\n- **group:** `\u003cgroupId\u003e` (required)\n- **tenant:** `\u003ctenantId\u003e` (required)\n- **authorization:** `\u003cauthorizationKey\u003e` (required)\n- **mapping-rule:** `\u003cmappingRuleId\u003e` (required)\n- **form:** `\u003ckey\u003e` (required)\n\n**Resource-specific flags:**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eprocess-definition\u003c/code\u003e (\u003ccode\u003epd\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--xml` | boolean |  | Get BPMN XML (process definitions) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eform\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--userTask` | boolean |  | Get form for user task |\n| `--ut` | boolean |  | Alias for --userTask |\n| `--processDefinition` | boolean |  | Get form for process definition |\n| `--pd` | boolean |  | Alias for --processDefinition |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eprocess-instance\u003c/code\u003e (\u003ccode\u003epi\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--variables` | boolean |  | Include variables in output |\n\n\u003c/details\u003e\n\n**Examples:**\n\n```bash\nc8ctl get pi 123456                                         # Get process instance by key\nc8ctl get pi 123456 --variables                             # Get process instance with variables\nc8ctl get pd 123456                                         # Get process definition by key\nc8ctl get pd 123456 --xml                                   # Get process definition XML\nc8ctl get form 123456                                       # Get form (searches both user task and process definition)\nc8ctl get form 123456 --ut                                  # Get form for user task only\nc8ctl get form 123456 --pd                                  # Get start form for process definition only\nc8ctl get user john                                         # Get user by username\n```\n\n---\n\n#### `create`\n\nCreate a resource (process instance, identity)\n\n**Resources:** pi (process-instance), user, role, group, tenant, auth (authorization), mapping-rule\n\n**Verb-level flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--processDefinitionId` | string |  | Process definition ID (BPMN process ID) |\n| `--id` | string |  | Process definition ID (alias for --processDefinitionId) |\n| `--bpmnProcessId` | string |  | BPMN process ID (alias for --processDefinitionId) |\n| `--variables` | string |  | JSON variables |\n| `--awaitCompletion` | boolean |  | Wait for process to complete |\n| `--fetchVariables` | boolean |  | Fetch result variables on completion |\n| `--requestTimeout` | string |  | Await timeout in milliseconds |\n| `--username` | string |  | Username |\n| `--name` | string |  | Display name |\n| `--email` | string |  | Email address |\n| `--password` | string |  | Password |\n| `--roleId` | string |  | Role ID |\n| `--groupId` | string |  | Group ID |\n| `--tenantId` | string |  | Tenant ID |\n| `--mappingRuleId` | string |  | Mapping rule ID |\n| `--claimName` | string |  | Claim name |\n| `--claimValue` | string |  | Claim value |\n\n**Resource-specific flags:**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003eauthorization\u003c/code\u003e (\u003ccode\u003eauth\u003c/code\u003e)\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--ownerId` | string | Yes | Authorization owner ID |\n| `--ownerType` | string | Yes | Authorization owner type |\n| `--resourceType` | string | Yes | Authorization resource type |\n| `--resourceId` | string | Yes | Authorization resource ID |\n| `--permissions` | string | Yes | Comma-separated permissions |\n\n\u003c/details\u003e\n\n**Examples:**\n\n```bash\nc8ctl create pi --id=myProcess                              # Create a process instance\nc8ctl create pi --id=myProcess --awaitCompletion            # Create and await completion\nc8ctl create user --username=john --name='John Doe' --email=john@example.com --password=secret  # Create a user\n```\n\n---\n\n#### `delete`\n\nDelete a resource by key\n\n**Usage:** `c8ctl delete \u003cresource\u003e \u003ckey\u003e`\n\n**Resources:** user, role, group, tenant, auth (authorization), mapping-rule\n\n**Positional arguments:**\n\n- **user:** `\u003cusername\u003e` (required)\n- **role:** `\u003croleId\u003e` (required)\n- **group:** `\u003cgroupId\u003e` (required)\n- **tenant:** `\u003ctenantId\u003e` (required)\n- **authorization:** `\u003cauthorizationKey\u003e` (required)\n- **mapping-rule:** `\u003cmappingRuleId\u003e` (required)\n\n**Examples:**\n\n```bash\nc8ctl delete user john                                      # Delete user\n```\n\n---\n\n#### `cancel`\n\nCancel a process instance\n\n**Usage:** `c8ctl cancel \u003cresource\u003e \u003ckey\u003e`\n\n**Resources:** pi (process-instance)\n\n**Positional arguments:**\n\n- **process-instance:** `\u003ckey\u003e` (required)\n\n---\n\n#### `await`\n\nCreate and await process instance completion (server-side waiting)\n\n**Usage:** `c8ctl await \u003cresource\u003e`\n\n**Resources:** pi (process-instance)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--processDefinitionId` | string |  | Process definition ID (BPMN process ID) |\n| `--id` | string |  | Process definition ID (alias for --processDefinitionId) |\n| `--bpmnProcessId` | string |  | BPMN process ID (alias for --processDefinitionId) |\n| `--variables` | string |  | JSON variables |\n| `--fetchVariables` | boolean |  | Fetch result variables on completion |\n| `--requestTimeout` | string |  | Await timeout in milliseconds |\n\n**Examples:**\n\n```bash\nc8ctl await pi --id=myProcess                               # Create and wait for completion\n```\n\n---\n\n#### `complete`\n\nComplete a user task or job\n\n**Usage:** `c8ctl complete \u003cresource\u003e \u003ckey\u003e`\n\n**Resources:** ut (user-task), job\n\n**Positional arguments:**\n\n- **user-task:** `\u003ckey\u003e` (required)\n- **job:** `\u003ckey\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--variables` | string |  | JSON variables |\n\n---\n\n#### `fail`\n\nMark a job as failed with optional error message and retry count\n\n**Resources:** job\n\n**Positional arguments:**\n\n- **job:** `\u003ckey\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--retries` | string |  | Remaining retries |\n| `--errorMessage` | string |  | Error message |\n\n---\n\n#### `activate`\n\nActivate jobs of a specific type for processing\n\n**Resources:** jobs\n\n**Positional arguments:**\n\n- **jobs:** `\u003ctype\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--maxJobsToActivate` | string |  | Maximum number of jobs to activate |\n| `--timeout` | string |  | Job timeout in milliseconds |\n| `--worker` | string |  | Worker name |\n\n---\n\n#### `resolve`\n\nResolve an incident (marks resolved, allows process to continue)\n\n**Resources:** inc (incident)\n\n**Positional arguments:**\n\n- **incident:** `\u003ckey\u003e` (required)\n\n---\n\n#### `publish`\n\nPublish a message for message correlation\n\n**Resources:** msg (message)\n\n**Positional arguments:**\n\n- **message:** `\u003cname\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--correlationKey` | string |  | Correlation key |\n| `--variables` | string |  | JSON variables |\n| `--timeToLive` | string |  | Time to live in milliseconds |\n\n---\n\n#### `correlate`\n\nCorrelate a message to a specific process instance\n\n**Resources:** msg (message)\n\n**Positional arguments:**\n\n- **message:** `\u003cname\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--correlationKey` | string | Yes | Correlation key |\n| `--variables` | string |  | JSON variables |\n| `--timeToLive` | string |  | Time to live in milliseconds |\n\n---\n\n#### `set`\n\nSet variables on an element instance (process instance or flow element scope). Variables are propagated to the outermost scope by default; use --local to restrict to the specified scope.\n\n**Usage:** `c8ctl set variable \u003ckey\u003e`\n\n**Resources:** variable\n\n**Positional arguments:**\n\n- **variable:** `\u003ckey\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--variables` | string | Yes | JSON object of variables to set (required) |\n| `--local` | boolean |  | Set variables in local scope only (default: propagate to outermost scope) |\n\n**Examples:**\n\n```bash\nc8ctl set variable 2251799813685249 --variables='{\"status\":\"approved\"}'  # Set variables on a process instance\nc8ctl set variable 2251799813685249 --variables='{\"x\":1}' --local  # Set variables in local scope only\n```\n\n---\n\n#### `deploy`\n\nDeploy files to Camunda (auto-discovers deployable files in directories). When deploying a directory that is inside a process application (a parent directory contains a .process-application marker), the entire application root is deployed. Explicit file paths are not expanded.\n\n**Usage:** `c8ctl deploy [path...]`\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--force` | boolean |  | Deploy any file type, ignoring the default extension allow-list |\n| `--extensions` | string |  | Comma-separated list of additional file extensions to include when scanning directories (e.g. .md,.txt). Explicit file paths bypass the extension allow-list. |\n| `--all-extensions` | boolean |  | Include all server-supported file extensions during directory discovery |\n\n**Examples:**\n\n```bash\nc8ctl deploy ./my-process.bpmn                              # Deploy a BPMN file\nc8ctl deploy                                                # Deploy from current directory (detects process application root)\n```\n\n---\n\n#### `run`\n\nDeploy and start a process instance from a BPMN file\n\n**Usage:** `c8ctl run \u003cpath\u003e`\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--variables` | string |  | JSON variables |\n| `--force` | boolean |  | Deploy any file type, ignoring the default extension allow-list |\n\n**Examples:**\n\n```bash\nc8ctl run ./my-process.bpmn                                 # Deploy and start process\n```\n\n---\n\n#### `assign`\n\nAssign a resource to a target (--to-user, --to-group, etc.)\n\n**Usage:** `c8ctl assign \u003cresource\u003e \u003cid\u003e`\n\n**Resources:** role, user, group, mapping-rule\n\n**Positional arguments:**\n\n- **role:** `\u003croleId\u003e` (required)\n- **user:** `\u003cusername\u003e` (required)\n- **group:** `\u003cgroupId\u003e` (required)\n- **mapping-rule:** `\u003cmappingRuleId\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--to-user` | string |  | Target user ID |\n| `--to-group` | string |  | Target group ID |\n| `--to-tenant` | string |  | Target tenant ID |\n| `--to-mapping-rule` | string |  | Target mapping rule ID |\n\n**Examples:**\n\n```bash\nc8ctl assign role admin --to-user=john                      # Assign role to user\n```\n\n---\n\n#### `unassign`\n\nUnassign a resource from a target (--from-user, --from-group, etc.)\n\n**Usage:** `c8ctl unassign \u003cresource\u003e \u003cid\u003e`\n\n**Resources:** role, user, group, mapping-rule\n\n**Positional arguments:**\n\n- **role:** `\u003croleId\u003e` (required)\n- **user:** `\u003cusername\u003e` (required)\n- **group:** `\u003cgroupId\u003e` (required)\n- **mapping-rule:** `\u003cmappingRuleId\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--from-user` | string |  | Source user ID |\n| `--from-group` | string |  | Source group ID |\n| `--from-tenant` | string |  | Source tenant ID |\n| `--from-mapping-rule` | string |  | Source mapping rule ID |\n\n**Examples:**\n\n```bash\nc8ctl unassign role admin --from-user=john                  # Unassign role from user\n```\n\n---\n\n#### `watch`\n\nWatch files for changes and auto-deploy\n\n**Usage:** `c8ctl watch [path...]`\n\n**Aliases:** `w`\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--force` | boolean |  | Continue watching after all deployment errors |\n| `--extensions` | string |  | Comma-separated list of additional file extensions to watch (merged with defaults, e.g. .md,.txt) |\n| `--all-extensions` | boolean |  | Watch all server-supported file extensions |\n| `--process-application` | boolean |  | Watch and deploy the entire process application (requires .process-application marker) |\n| `--pa` | boolean |  | Alias for --process-application |\n\n**Examples:**\n\n```bash\nc8ctl watch ./src                                           # Watch directory for changes\n```\n\n---\n\n#### `open`\n\nOpen Camunda web app in browser\n\n**Usage:** `c8ctl open \u003capp\u003e`\n\n**Resources:** operate, tasklist, modeler, optimize\n\n**Examples:**\n\n```bash\nc8ctl open operate                                          # Open Camunda Operate in browser\nc8ctl open tasklist                                         # Open Camunda Tasklist in browser\nc8ctl open operate --profile=prod                           # Open Operate using a specific profile\n```\n\n---\n\n#### `add`\n\nAdd a profile\n\n**Resources:** profile\n\n**Positional arguments:**\n\n- **profile:** `\u003cname\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--baseUrl` | string |  | Cluster base URL |\n| `--clientId` | string |  | OAuth client ID |\n| `--clientSecret` | string |  | OAuth client secret |\n| `--audience` | string |  | OAuth audience |\n| `--oAuthUrl` | string |  | OAuth token URL |\n| `--defaultTenantId` | string |  | Default tenant ID |\n| `--username` | string |  | Basic auth username |\n| `--password` | string |  | Basic auth password |\n| `--from-file` | string |  | Import from .env file |\n| `--from-env` | boolean |  | Import from environment variables |\n\n---\n\n#### `remove`\n\nRemove a profile (alias: rm)\n\n**Usage:** `c8ctl remove profile \u003cname\u003e`\n\n**Aliases:** `rm`\n\n**Resources:** profile\n\n**Positional arguments:**\n\n- **profile:** `\u003cname\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--none` | boolean |  | Clear active profile |\n\n---\n\n#### `load`\n\nLoad a c8ctl plugin (npm registry or URL)\n\n**Usage:** `c8ctl load plugin [name|--from url]`\n\n**Resources:** plugin\n\n**Positional arguments:**\n\n- **plugin:** `\u003cpackage\u003e` (optional)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--from` | string |  | Load plugin from URL |\n\n**Examples:**\n\n```bash\nc8ctl load plugin my-plugin                                 # Load plugin from npm registry\nc8ctl load plugin --from https://github.com/org/plugin      # Load plugin from URL\n```\n\n---\n\n#### `unload`\n\nUnload a c8ctl plugin (npm uninstall wrapper)\n\n**Usage:** `c8ctl unload plugin \u003cname\u003e`\n\n**Aliases:** `rm`\n\n**Resources:** plugin\n\n**Positional arguments:**\n\n- **plugin:** `\u003cpackage\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--force` | boolean |  | Force unload without confirmation |\n\n---\n\n#### `upgrade`\n\nUpgrade a plugin (respects source type)\n\n**Usage:** `c8ctl upgrade plugin \u003cname\u003e [version]`\n\n**Resources:** plugin\n\n**Positional arguments:**\n\n- **plugin:** `\u003cpackage\u003e` (required), `\u003cversion\u003e` (optional)\n\n**Examples:**\n\n```bash\nc8ctl upgrade plugin my-plugin                              # Upgrade plugin to latest version\nc8ctl upgrade plugin my-plugin 1.2.3                        # Upgrade plugin to a specific version (source-aware)\n```\n\n---\n\n#### `downgrade`\n\nDowngrade a plugin to a specific version\n\n**Usage:** `c8ctl downgrade plugin \u003cname\u003e \u003cversion\u003e`\n\n**Resources:** plugin\n\n**Positional arguments:**\n\n- **plugin:** `\u003cpackage\u003e` (required), `\u003cversion\u003e` (required)\n\n---\n\n#### `sync`\n\nSynchronize plugins from registry (rebuild/reinstall)\n\n**Resources:** plugin\n\n**Examples:**\n\n```bash\nc8ctl sync plugin                                           # Synchronize plugins\n```\n\n---\n\n#### `init`\n\nCreate a new plugin from TypeScript template\n\n**Resources:** plugin\n\n**Positional arguments:**\n\n- **plugin:** `\u003cname\u003e` (optional)\n\n**Examples:**\n\n```bash\nc8ctl init plugin my-plugin                                 # Create new plugin from template (c8ctl-plugin-my-plugin)\n```\n\n---\n\n#### `doctor`\n\nSurface plugin-loading collisions detected at startup (#363). Reports loaded plugins with their command names, and any first-registration-wins drops (plugin-name or command-name).\n\n**Resources:** plugin\n\n**Examples:**\n\n```bash\nc8ctl doctor plugin                                         # List loaded plugins and any load-time collisions\nc8ctl doctor plugin --json                                  # Machine-readable doctor output\n```\n\n---\n\n#### `use`\n\nSet active profile or tenant\n\n**Usage:** `c8ctl use profile|tenant`\n\n**Resources:** profile, tenant\n\n**Positional arguments:**\n\n- **profile:** `\u003cname\u003e` (optional)\n- **tenant:** `\u003ctenantId\u003e` (required)\n\n**Flags:**\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--none` | boolean |  | Clear active profile/tenant |\n\n**Examples:**\n\n```bash\nc8ctl use profile prod                                      # Set active profile\n```\n\n---\n\n#### `output`\n\nShow or set output format\n\n**Usage:** `c8ctl output [json|text]`\n\n**Resources:** json, text\n\n**Examples:**\n\n```bash\nc8ctl output json                                           # Switch to JSON output\n```\n\n---\n\n#### `completion`\n\nGenerate shell completion script\n\n**Usage:** `c8ctl completion bash|zsh|fish|install`\n\n**Resources:** bash, zsh, fish, install\n\n**Resource-specific flags:**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003einstall\u003c/code\u003e\u003c/summary\u003e\n\n| Flag | Type | Required | Description |\n|------|------|----------|-------------|\n| `--shell` | string |  | Shell to install completions for (bash, zsh, fish) |\n\n\u003c/details\u003e\n\n**Examples:**\n\n```bash\nc8ctl completion bash                                       # Generate bash completion script\nc8ctl completion install                                    # Auto-detect shell and install completions (auto-refreshes on upgrade)\nc8ctl completion install --shell zsh                        # Install completions for a specific shell\n```\n\n---\n\n#### `mcp-proxy`\n\nStart a STDIO MCP proxy (bridges local MCP clients to remote Camunda 8)\n\n**Usage:** `c8ctl mcp-proxy [mcp-path]`\n\n---\n\n#### `feedback`\n\nOpen the feedback page to report issues or request features\n\n---\n\n#### `help`\n\nShow help (run 'c8ctl help \\\u003ccommand\u003e' for details)\n\n**Usage:** `c8ctl help [command]`\n\n**Aliases:** `menu`\n\n---\n\n#### `which`\n\nShow active profile or output mode\n\n**Resources:** profile, output\n\n**Examples:**\n\n```bash\nc8ctl which profile                                         # Show currently active profile\nc8ctl which output                                          # Show current output mode\n```\n\n\n\u003c!-- command-reference:end --\u003e\n\n## License\n\nApache 2.0 - see LICENSE.md\n\n## Contributing\n\nSee [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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamunda%2Fc8ctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcamunda%2Fc8ctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamunda%2Fc8ctl/lists"}