@camunda8/cli 3.3.0 → 3.4.0-alpha.1

package/EXAMPLES.md

@@ -1,1607 +1,20 @@
 # c8ctl Examples
 
-Comprehensive examples for all c8ctl operations.
-
-## Table of Contents
-
-- [Process Instances](#process-instances)
-- [User Tasks](#user-tasks)
-- [Incidents](#incidents)
-- [Jobs](#jobs)
-- [Search](#search)
-- [Messages](#messages)
-- [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)
-
----
-
-## Process Instances
-
-### List All Process Instances
-
-```bash
-c8 list pi
-c8 list process-instances
-```
-
-### List Process Instances with Filter
-
-```bash
-# Filter by BPMN process ID
-c8 list pi --id=order-process
-
-# Filter by state
-c8 list pi --state=ACTIVE
-
-# Filter by process definition version
-c8 list pi --id=order-process --version=2
-```
-
-### Get Process Instance by Key
-
-```bash
-c8 get pi 2251799813685249
-c8 get process-instance 2251799813685249
-
-# Get process instance with variables
-c8 get pi 2251799813685249 --variables
-```
-
-### Create Process Instance
-
-```bash
-# Create with process ID
-c8 create pi --id=order-process
-
-# Create with specific version
-c8 create pi --id=order-process --version=2
-
-# Create with variables
-c8 create pi --id=order-process --variables='{"orderId":"12345","amount":100}'
-
-# Create and wait for completion
-c8 create pi --id=order-process --awaitCompletion
-
-# Create and wait with custom timeout (30 seconds)
-c8 create pi --id=order-process --awaitCompletion --requestTimeout=30000
-
-# Note: --fetchVariables is reserved for future API support
-# All variables are currently returned by default
-```
-
-### Await Process Instance Completion
-
-The `await` command is an alias for `create` with `--awaitCompletion`. It uses the Camunda 8 API's built-in server-side waiting to create a process instance and wait for completion.
-
-The `--requestTimeout` option specifies the maximum time in milliseconds to wait for the process instance to complete. By default (or when set to 0), the generic request timeout configured in the cluster is used.
-
-```bash
-# Create and wait for completion (shorthand)
-c8 await pi --id=order-process
-c8 await process-instance --id=order-process
-
-# With variables
-c8 await pi --id=order-process --variables='{"orderId":"12345"}'
-
-# With custom timeout (60 seconds)
-c8 await pi --id=order-process --requestTimeout=60000
-
-# Equivalent to:
-c8 create pi --id=order-process --awaitCompletion
-
-# Note: --fetchVariables is reserved for future API support
-# All variables are currently returned by default
-```
-
-### Cancel Process Instance
-
-```bash
-c8 cancel pi 2251799813685249
-```
-
----
-
-## User Tasks
-
-### List All User Tasks
-
-```bash
-c8 list ut
-c8 list user-tasks
-```
-
-### List User Tasks with Filter
-
-```bash
-# Filter by state
-c8 list ut --state=CREATED
-
-# Filter by assignee
-c8 list ut --assignee=john.doe
-```
-
-### Complete User Task
-
-```bash
-# Complete without variables
-c8 complete ut 2251799813685250
-
-# Complete with variables
-c8 complete ut 2251799813685250 --variables='{"approved":true,"notes":"Looks good"}'
-```
-
----
-
-## Incidents
-
-### List All Incidents
-
-```bash
-c8 list inc
-c8 list incidents
-```
-
-### List Incidents with Filter
-
-```bash
-# Filter by state
-c8 list inc --state=ACTIVE
-
-# Filter by process instance
-c8 list inc --processInstanceKey=2251799813685249
-```
-
-### Get Incident by Key
-
-```bash
-c8 get inc 2251799813685251
-c8 get incident 2251799813685251
-```
-
-### Resolve Incident
-
-```bash
-c8 resolve inc 2251799813685251
-```
-
----
-
-## Jobs
-
-### List All Jobs
-
-```bash
-c8 list jobs
-```
-
-### List Jobs with Filter
-
-```bash
-# Filter by type
-c8 list jobs --type=email-service
-
-# Filter by state
-c8 list jobs --state=ACTIVATABLE
-```
-
-### Activate Jobs
-
-```bash
-# Activate jobs of a specific type
-c8 activate jobs email-service
-
-# Activate with options
-c8 activate jobs email-service --maxJobsToActivate=20 --timeout=120000 --worker=my-worker
-```
-
-### Complete Job
-
-```bash
-# Complete without variables
-c8 complete job 2251799813685252
-
-# Complete with variables
-c8 complete job 2251799813685252 --variables='{"emailSent":true,"timestamp":"2024-01-15T10:30:00Z"}'
-```
-
-### Fail Job
-
-```bash
-# Fail job with default message
-c8 fail job 2251799813685252
-
-# Fail job with custom message and retries
-c8 fail job 2251799813685252 --retries=3 --errorMessage="Email service unavailable"
-```
-
----
-
-## Search
-
-The `search` command provides powerful filtering across all major resource types. Unlike `list`, which shows resources with basic filters, `search` supports fine-grained query options including wildcard matching and case-insensitive search. All search commands respect the active tenant and profile.
-
-### Wildcard Search
-
-String filters support wildcard matching using the `$like` operator (applied automatically when wildcards are detected):
-
-- `*` — matches zero, one, or multiple characters
-- `?` — matches exactly one character
-- Escape with backslash: `\*` or `\?`
-
-```bash
-# Find process definitions with names containing "order"
-c8 search pd --name='*order*'
-
-# Find process definitions starting with "main"
-c8 search pd --name='main*'
-
-# Find jobs with type matching a pattern
-c8 search jobs --type='*-service'
-
-# Find variables with names matching a pattern
-c8 search variables --name='order*'
-
-# Single character wildcard
-c8 search pd --id='process-v?'
-```
-
-**Wildcard-capable fields per resource:**
-
-| Resource | Fields supporting wildcards |
-|---|---|
-| Process Definitions | `--name`, `--id` (bpmnProcessId) |
-| Process Instances | `--id` (processDefinitionId) |
-| User Tasks | `--assignee` |
-| Incidents | `--errorMessage`, `--id` (processDefinitionId) |
-| Jobs | `--type` |
-| Variables | `--name`, `--value` |
-| Wait States | `--elementId` |
-
-### Case-Insensitive Search
-
-For case-insensitive matching, prefix the flag name with `i` (e.g., `--name` becomes `--iname`). Case-insensitive filtering is performed client-side after fetching results from the server, so it works with wildcards too.
-
-```bash
-# Case-insensitive name search — matches "order", "Order", "ORDER", etc.
-c8 search pd --iname=order
-
-# Case-insensitive wildcard search
-c8 search pd --iname='*ORDER*'
-
-# Case-insensitive assignee search
-c8 search ut --iassignee=John
-
-# Case-insensitive job type search
-c8 search jobs --itype='*Service*'
-
-# Case-insensitive error message search
-c8 search inc --ierrorMessage='*timeout*'
-
-# Case-insensitive variable name and value
-c8 search variables --iname='OrderId'
-c8 search variables --ivalue='*pending*'
-
-# Combine case-insensitive with regular (case-sensitive) filters
-c8 search pd --iname='*order*' --key=2251799813685249
-```
-
-**Case-insensitive flags per resource:**
-
-| Resource | Case-insensitive flags |
-|---|---|
-| Process Definitions | `--iname`, `--iid` |
-| Process Instances | `--iid` |
-| User Tasks | `--iassignee` |
-| Incidents | `--ierrorMessage`, `--iid` |
-| Jobs | `--itype` |
-| Variables | `--iname`, `--ivalue` |
-
-> **Note:** Case-insensitive filtering fetches up to 1000 results from the server and filters client-side. For very large result sets, consider combining with other (case-sensitive) filters to narrow results.
-
-### Search Process Definitions
-
-```bash
-# Search by BPMN process ID
-c8 search pd --id=order-process
-c8 search process-definitions --bpmnProcessId=order-process
-
-# Search by name
-c8 search pd --name=Order
-
-# Search by version
-c8 search pd --id=order-process --version=2
-
-# Search by key
-c8 search pd --key=2251799813685249
-
-# Combine filters
-c8 search pd --id=order-process --name=Order
-
-# Using a specific profile
-c8 search pd --id=order-process --profile=prod
-```
-
-### Search Process Instances
-
-```bash
-# Search by state
-c8 search pi --state=ACTIVE
-c8 search pi --state=COMPLETED
-
-# Search by process definition ID
-c8 search pi --id=order-process
-c8 search pi --bpmnProcessId=order-process
-
-# Search by process definition version
-c8 search pi --id=order-process --version=2
-
-# Search by process definition key
-c8 search pi --processDefinitionKey=2251799813685249
-
-# Search by process instance key
-c8 search pi --key=2251799813685260
-
-# Search by parent process instance (for call activities)
-c8 search pi --parentProcessInstanceKey=2251799813685250
-
-# Combine filters
-c8 search pi --id=order-process --state=ACTIVE
-```
-
-### Search User Tasks
-
-```bash
-# Search by state
-c8 search ut --state=CREATED
-c8 search ut --state=COMPLETED
-
-# Search by assignee
-c8 search ut --assignee=john.doe
-
-# Search by process instance
-c8 search ut --processInstanceKey=2251799813685249
-
-# Search by process definition key
-c8 search ut --processDefinitionKey=2251799813685249
-
-# Search by element ID (BPMN element)
-c8 search ut --elementId=UserTask_Approve
-
-# Combine filters
-c8 search ut --state=CREATED --assignee=john.doe
-```
-
-### Search Incidents
-
-```bash
-# Search by state
-c8 search inc --state=ACTIVE
-c8 search incidents --state=ACTIVE
-
-# Search by process instance
-c8 search inc --processInstanceKey=2251799813685249
-
-# Search by process definition key
-c8 search inc --processDefinitionKey=2251799813685249
-
-# Search by error type
-c8 search inc --errorType=JOB_NO_RETRIES
-
-# Search by error message (with wildcard)
-c8 search inc --errorMessage='*timeout*'
-
-# Combine filters
-c8 search inc --state=ACTIVE --errorType=JOB_NO_RETRIES
-```
-
-### Search Jobs
-
-```bash
-# Search by type
-c8 search jobs --type=email-service
-
-# Search by state
-c8 search jobs --state=CREATED
-c8 search jobs --state=FAILED
-
-# Search by process instance
-c8 search jobs --processInstanceKey=2251799813685249
-
-# Search by process definition key
-c8 search jobs --processDefinitionKey=2251799813685249
-
-# Combine filters
-c8 search jobs --type=email-service --state=CREATED
-```
-
-### Search Variables
-
-```bash
-# Search by variable name
-c8 search variables --name=orderId
-
-# Search by variable value
-c8 search variables --value=12345
-
-# Search by process instance
-c8 search variables --processInstanceKey=2251799813685249
-
-# Search by scope key
-c8 search variables --scopeKey=2251799813685260
-
-# Show full (non-truncated) variable values
-c8 search variables --name=orderPayload --fullValue
-
-# Combine filters
-c8 search variables --name=orderId --processInstanceKey=2251799813685249
-
-# Combine name and full value
-c8 search variables --name=orderPayload --processInstanceKey=2251799813685249 --fullValue
-```
-
-**Note**: By default, long variable values are truncated in the output. Truncated values are marked with a `✓` in the "Truncated" column. Use `--fullValue` to see the complete values.
-
-### Search Wait States
-
-```bash
-# Search all wait states
-c8 search wait-state
-
-# Search wait states by type
-c8 search ws --waitStateType=JOB
-c8 search ws --waitStateType=MESSAGE
-c8 search ws --waitStateType=TIMER
-
-# Search wait states by BPMN element type
-c8 search ws --elementType=SERVICE_TASK
-c8 search ws --elementType=USER_TASK
-
-# Filter by process instance
-c8 search ws --processInstanceKey=2251799813685249
-
-# Filter by element ID
-c8 search ws --elementId=serviceTask1
-
-# Combine filters
-c8 search ws --processInstanceKey=2251799813685249 --waitStateType=JOB
-c8 search ws --elementType=SERVICE_TASK --waitStateType=JOB
-```
-
-### Search Output
-
-Search results are displayed as tables in text mode:
-
-```bash
-# Text mode (default)
-c8 search pi --state=ACTIVE
-# Key              | Process ID     | State  | Version | Tenant ID
-# 2251799813685260 | order-process  | ACTIVE | 3       | <default>
-# 2251799813685270 | order-process  | ACTIVE | 3       | <default>
-# Found 2 process instance(s)
-
-# JSON mode
-c8 output json
-c8 search pi --state=ACTIVE
-# [{"processInstanceKey":"2251799813685260",...}, ...]
-```
-
----
-
-## Messages
-
-### Publish Message
-
-```bash
-# Publish simple message
-c8 publish msg order-placed
-
-# Publish with correlation key
-c8 publish msg order-placed --correlationKey=order-12345
-
-# Publish with variables
-c8 publish msg order-placed --correlationKey=order-12345 --variables='{"orderId":"12345","total":250.00}'
-
-# Publish with time-to-live
-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 a message to a specific process instance
-c8 correlate msg payment-received --correlationKey=order-12345 --variables='{"amount":250.00}'
-```
-
----
-
-## Deployments
-
-### Deploy Single File
-
-```bash
-c8 deploy ./process.bpmn
-c8 deploy ./decision.dmn
-c8 deploy ./form.form
-```
-
-### Deploy Multiple Files
-
-```bash
-c8 deploy ./process1.bpmn ./process2.bpmn ./decision.dmn
-```
-
-### Deploy Directory
-
-```bash
-# Deploy current directory
-c8 deploy
-
-# Deploys all files in specified directory and subdirectories
-c8 deploy ./my-project
-
-# Building block folders (containing _bb- in name) are prioritized and marked with 🧱
-# Process applications (folders with .process-application file) are marked with 📦
-# Example output:
-#   Deploying 4 resource(s)...
-#   ✓ Deployment successful [Key: 123456789]
-#   
-#   File                              | Type    | ID              | Version | Key
-#   ----------------------------------|---------|-----------------|---------|-------------------
-#   🧱 _bb-shared/common-process.bpmn | Process | common-process  | 1       | 2251799813685249
-#   📦 my-app/process.bpmn            | Process | my-proc         | 1       | 2251799813685250
-#   📦 my-app/decision.dmn            | Decision| my-dec          | 1       | 2251799813685251
-#   processes/order-process.bpmn      | Process | order-process   | 1       | 2251799813685252
-```
-
-### Process Application Deployment
-
-If a directory contains a `.process-application` file, **all resources in that directory and its subdirectories** are marked with the 📦 emoji in the deployment results table. Resources are grouped together based on their location:
-
-```bash
-# Directory structure:
-# my-project/
-#   _bb-shared/
-#     common.bpmn
-#     nested/
-#       util.bpmn        # Also part of _bb-shared group
-#   my-app/
-#     .process-application
-#     process.bpmn
-#     subfolder/
-#       form.form        # Also part of my-app group
-#   standalone.bpmn
-
-c8 deploy ./my-project
-
-# Output shows resources grouped by their folder hierarchy:
-# Deploying 5 resource(s)...
-# ✓ Deployment successful [Key: 123456789]
-#
-# File                            | Type    | ID            | Version | Key
-# --------------------------------|---------|---------------|---------|-------------------
-# 🧱 _bb-shared/common.bpmn       | Process | common        | 1       | 2251799813685249
-# 🧱 _bb-shared/nested/util.bpmn  | Process | util          | 1       | 2251799813685250
-# 📦 my-app/process.bpmn          | Process | my-proc       | 1       | 2251799813685251
-# 📦 my-app/subfolder/form.form   | Form    | form-id       | 1       | 2251799813685252
-# standalone.bpmn                 | Process | standalone    | 1       | 2251799813685253
-```
-
-### Resource Grouping Rules
-
-Resources are automatically grouped based on their folder hierarchy:
-
-1. **Building Block Groups** - All resources in a folder with `_bb-` in the name (and its subdirectories) belong to the same group and are marked with 🧱
-2. **Process Application Groups** - All resources in a folder containing `.process-application` file (and its subdirectories) belong to the same group and are marked with 📦
-3. **Standalone Resources** - Resources not in a building block or process application folder are treated as standalone
-
-In the deployment output:
-- Building block groups are listed first, grouped together
-- Process application groups are listed next, grouped together
-- Standalone resources are listed last
-
-### Deployment Output Details
-
-The deployment results table shows:
-- **File column** - Shows the file name with relative path
-  - 🧱 emoji indicates building block resources (from `_bb-*` folders, including nested files)
-  - 📦 emoji indicates process application resources (from folders with `.process-application` file, including nested files)
-- **Type column** - Resource type (Process, Decision, or Form)
-- **ID column** - The process/decision/form ID
-- **Version column** - Version number assigned by Camunda
-- **Key column** - Unique key assigned by Camunda
-
-### Important: Duplicate Process IDs
-
-Camunda does not allow deploying multiple resources with the same process/decision ID in a single deployment. If you have multiple BPMN files with the same process definition ID, deploy them separately:
-
-```bash
-# This will fail if both files have the same process ID
-# c8 deploy process-v1.bpmn process-v2.bpmn
-
-# Instead, deploy separately:
-c8 deploy process-v1.bpmn
-c8 deploy process-v2.bpmn
-```
-
-The CLI will detect duplicate IDs and provide a helpful error message showing which files conflict.
-
-### Default Extensions
-
-When scanning directories, `deploy` and `watch` only include files matching these extensions by default:
-
-`.bpmn`, `.dmn`, `.form`
-
-Explicitly named files bypass the extension allow-list (`.c8ignore` rules still apply):
-
-```bash
-# Explicit file — deploys regardless of extension
-c8 deploy my-doc.md
-
-# Directory walk — only .bpmn/.dmn/.form by default
-c8 deploy ./my-project/
-```
-
-Use `--extensions` to add more types during directory discovery (merged with defaults):
-
-```bash
-c8 deploy --extensions=.md,.txt
-c8 watch --extensions=.md
-```
-
-Use `--all-extensions` to include all server-supported types:
-
-```bash
-c8 deploy --all-extensions
-c8 watch --all-extensions
-```
-
-### Ignoring Files (`.c8ignore`)
-
-When deploying or watching a directory, c8ctl ignores `node_modules/`, `target/`, and `.git/` by default. Add a `.c8ignore` file to your project root for custom patterns (uses `.gitignore` syntax):
-
-```gitignore
-# .c8ignore — filter directories for deploy and watch
-
-# Ignore build output
-dist/
-build/
-
-# Ignore draft processes
-**/draft-*.bpmn
-
-# But keep this approved draft
-!draft-approved.bpmn
-```
-
-```bash
-# Deploy respects .c8ignore automatically
-c8 deploy
-
-# Watch mode also respects .c8ignore
-c8 watch
-```
-
-### Deploy Confirmation
-
-When multiple profiles are configured, `c8 deploy` presents an interactive
-profile picker to prevent deploying to the wrong cluster:
-
-```bash
-# Shows an interactive profile selection menu
-c8 deploy ./process.bpmn
-
-# Skip the prompt with --yes / -y (uses active profile)
-c8 deploy ./process.bpmn --yes
-c8 deploy ./process.bpmn -y
-
-# Explicit --profile also skips the prompt (target is unambiguous)
-c8 deploy ./process.bpmn --profile=staging
-```
-
-In non-interactive environments (CI, piped input), the deploy fails with
-guidance to use `--profile` or `--yes` to make the target explicit.
-
-### Run (Deploy + Start)
-
-```bash
-# Deploy BPMN and create process instance
-c8 run ./order-process.bpmn
-
-# With variables
-c8 run ./order-process.bpmn --variables='{"orderId":"12345","amount":100}'
-```
-
----
-
-## Forms
-
-Forms in Camunda 8 are linked to user tasks and process definitions. You can retrieve the form associated with a specific resource.
-
-### Get Form (Search Both Types)
-
-```bash
-# Search both user task and process definition (no flag required)
-c8 get form 2251799813685251
-
-# The output will indicate whether the form was found as a user task, process definition, both, or neither
-# Using profile
-c8 get form 2251799813685251 --profile prod
-```
-
-### Get Form for User Task Only
-
-```bash
-# Get the form associated with a user task (short form with --ut alias)
-c8 get form 2251799813685251 --ut
-
-# Long form
-c8 get form 2251799813685251 --userTask
-
-# Using profile
-c8 get form 2251799813685251 --ut --profile prod
-```
-
-### Get Start Form for Process Definition Only
-
-```bash
-# Get the start form for a process definition (short form with --pd alias)
-c8 get form 2251799813685252 --pd
-
-# Long form
-c8 get form 2251799813685252 --processDefinition
-
-# Using profile
-c8 get form 2251799813685252 --pd --profile prod
-```
-
-**Note**: When no flag is specified, the command searches both user tasks and process definitions and reports where the form was found. With a flag, it only searches the specified type.
-
----
-
-## Topology
-
-### Get Cluster Topology
-
-```bash
-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:
-1. **c8ctl profiles**: Directly managed by c8ctl commands
-2. **Modeler profiles**: Automatically imported from Camunda Modeler (read-only)
-
-### Show Profile Help
-
-```bash
-# Show all profile-related commands and flags
-c8 help profiles
-```
-
-### Add c8ctl Profile
-
-`c8 add profile <name>` usage rules:
-
-- **Always required**: profile `<name>`
-- **Required for OAuth-secured clusters**: `--clientId`, `--clientSecret`
-- **Optional with defaults**:
-  - `--baseUrl` (default: `http://localhost:8080/v2`)
-  - `--defaultTenantId` (runtime default tenant: `<default>`)
-- **Optional without c8ctl defaults**: `--audience`, `--oAuthUrl`, `--scope`
-- **Import shortcuts**: `--from-file <path>`, `--from-env`
-
-```bash
-# Minimal local profile (uses default --baseUrl)
-c8 add profile local
-
-# Local profile with explicit URL
-c8 add profile local --baseUrl=http://localhost:8080
-
-# Minimal OAuth profile (required OAuth switches)
-c8 add profile prod \
-  --baseUrl=https://camunda.example.com \
-  --clientId=your-client-id \
-  --clientSecret=your-client-secret
-
-# OAuth profile with explicit audience/token endpoint
-c8 add profile prod \
-  --baseUrl=https://camunda.example.com \
-  --clientId=your-client-id \
-  --clientSecret=your-client-secret \
-  --audience=camunda-api \
-  --oAuthUrl=https://auth.example.com/oauth/token
-
-# OAuth profile against an IdP that requires an explicit scope (e.g. Microsoft Entra ID)
-c8 add profile prod \
-  --baseUrl=https://camunda.example.com \
-  --clientId=your-client-id \
-  --clientSecret=your-client-secret \
-  --oAuthUrl=https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token \
-  --scope=api://your-app-id/.default
-
-# Add profile with default tenant
-c8 add profile dev \
-  --baseUrl=https://dev.camunda.example.com \
-  --clientId=dev-client \
-  --clientSecret=dev-secret \
-  --defaultTenantId=dev-tenant
-
-# Create a profile from a .env file
-c8 add profile staging --from-file .env.staging
-
-# Create a profile from current environment variables
-source .env.prod
-c8 add profile prod --from-env
-```
-
-### List All Profiles
-
-```bash
-# Lists both c8ctl and modeler profiles
-# Modeler profiles are shown with 'modeler:' prefix
-c8 list profiles
-
-# Example output:
-# Name                      Base URL                                     Client ID      Default Tenant
-# local                     http://localhost:8080/v2                     (none)         <default>
-# prod                      https://camunda.example.com                  your-client    <default>
-# modeler:Local Dev         http://localhost:8080/v2                     (none)         <default>
-# modeler:Cloud Cluster     https://abc123.zeebe.camunda.io             XYZ            <default>
-```
-
-### Use Modeler Profiles
-
-```bash
-# Use a modeler profile by name
-c8 use profile modeler:Local Dev
-
-# Use a modeler profile by cluster ID
-c8 use profile modeler:abc123-def456
-
-# One-off command with modeler profile
-c8 list pi --profile=modeler:Cloud Cluster
-
-# Deploy with modeler profile
-c8 deploy ./process.bpmn --profile=modeler:Local Dev
-```
-
-### Remove c8ctl Profile
-
-```bash
-# Only c8ctl profiles can be removed
-# Modeler profiles are managed via Camunda Modeler
-c8 remove profile local
-c8 rm profile local  # alias
-
-# Attempting to remove a modeler profile will fail
-# c8 remove profile modeler:Local Dev  # Error: Profile not found
-```
-
----
-
-## Session Management
-
-### Set Active Profile
-
-```bash
-# Set c8ctl profile to use for all subsequent commands
-c8 use profile prod
-
-# Set modeler profile to use for all subsequent commands
-c8 use profile modeler:Local Dev
-
-# Clear the active profile (so env vars or default 'local' take effect)
-c8 use profile --none
-
-# All commands now use the active profile automatically
-c8 list pi
-c8 deploy ./process.bpmn
-```
-
-### Override Profile for Single Command
-
-```bash
-# Use specific profile for one command only
-c8 list pi --profile=dev
-c8 deploy ./process.bpmn --profile=staging
-```
-
-### Set Active Tenant
-
-```bash
-# Set tenant for all subsequent commands
-c8 use tenant my-tenant-123
-
-# All commands now include tenant filter/parameter
-c8 list pi
-c8 create pi --id=order-process
-```
-
-### Set Output Mode
-
-```bash
-# Switch to JSON output
-c8 output json
-
-# All commands now output JSON
-c8 list pi
-# Output: [{"processInstanceKey":"...","bpmnProcessId":"..."}]
-
-# Switch back to human-readable text
-c8 output text
-```
-
----
-
-## Local Cluster
-
-### Start a Local Cluster
-
-```bash
-# Start a local Camunda 8 cluster (downloads c8run automatically if needed)
-c8 cluster start
-
-# Start a specific version
-c8 cluster start 8.9.0-alpha5
-
-# Start the latest cached release for a major.minor version
-c8 cluster start 8.8
-
-# Start with debug output (streams raw c8run logs)
-c8 cluster start --debug
-```
-
-### Stop a Local Cluster
-
-```bash
-c8 cluster stop
-```
-
-### Cluster Status
-
-```bash
-# Check if a cluster is running and see connection details
-c8 cluster status
-```
-
-### Stream Logs
-
-```bash
-# Stream log output from the running cluster (Ctrl+C to stop)
-c8 cluster logs
-```
-
-### List Installed Versions
-
-```bash
-# Show locally cached versions and version aliases
-c8 cluster list
-```
-
-### List Available Remote Versions
-
-```bash
-# Query the Camunda Download Center for all available versions
-c8 cluster list-remote
-```
-
-### Install a Version Without Starting
-
-```bash
-# Pre-download a version for later use
-c8 cluster install 8.8
-c8 cluster install alpha
-```
-
-### Delete a Cached Version
-
-```bash
-# Remove a locally cached version to reclaim disk space
-c8 cluster delete 8.8
-```
-
-### Purge Cluster Data
-
-Wipe history and journal data while keeping the downloaded binary intact.
-The next `cluster start` begins with a fresh empty state without re-downloading anything.
-
-```bash
-# Purge data for a specific version (version required, like delete)
-c8 cluster purge 8.9
-c8 cluster purge 8.9.0-alpha5
-
-# Stop the running cluster and purge its data in one step
-c8 cluster stop --purge
-```
-
-If the target version is currently running, stop it first with `cluster stop`
-(or use `cluster stop --purge` to stop and purge in one step).
-
-`cluster stop --purge` is the recommended way to reset a running cluster:
-it captures the running version, stops it, then purges the data atomically.
-
-### Typical Local Development Workflow
-
-```bash
-# Start local cluster
-c8 cluster start
-
-# Set up a local profile
-c8 add profile local --baseUrl=http://localhost:8080
-c8 use profile local
-
-# Deploy and run a process
-c8 run ./my-process.bpmn
-
-# When done, stop the cluster
-c8 cluster stop
-```
-
----
-
-## Open Camunda Applications
-
-Open Camunda web applications directly from the command line. The URL is derived
-automatically from the active profile's base URL.
-
-### Open Camunda Operate
-
-```bash
-# Open Operate for the currently active profile
-c8 open operate
-
-# Open Operate using a specific profile
-c8 open operate --profile=prod
-```
-
-### Open Camunda Tasklist
-
-```bash
-c8 open tasklist
-c8 open tasklist --profile=staging
-```
-
-### Open Camunda Web Modeler
-
-```bash
-c8 open modeler
-```
-
-### Open Camunda Optimize
-
-```bash
-c8 open optimize
-```
-
-**URL derivation:** The command strips the API path suffix (e.g. `/v2`) from the
-profile's `baseUrl` and appends the application path.  
-Example: `baseUrl=http://localhost:8080/v2` → `http://localhost:8080/operate`
-
----
-
-## Plugin Management
-
-### Load Plugin
-
-```bash
-# Install a c8ctl plugin from npm registry
-c8 load plugin my-custom-plugin
-
-# Install a plugin from a URL (file, https, git, etc.)
-c8 load plugin --from https://github.com/user/my-plugin
-c8 load plugin --from file:///path/to/local/plugin
-c8 load plugin --from git://github.com/user/plugin.git
-
-# The plugin is now available
-# (assuming the plugin exports an 'analyze' command)
-c8 analyze
-```
-
-### Unload Plugin
-
-```bash
-# Remove a plugin
-c8 unload plugin my-custom-plugin
-```
-
-### List Plugins
-
-```bash
-# Show all installed c8ctl plugins with version and sync status
-c8 list plugins
-
-# Example output:
-# Name              | Version | Status          | Source                    | Installed At
-# ------------------+---------+-----------------+---------------------------+----------------------
-# my-custom-plugin  | 1.2.0   | ✓ Installed     | my-custom-plugin          | 1/30/2026, 6:00:00 PM
-# local-dev-plugin  | Unknown | ⚠ Not installed | file:///path/to/plugin    | 1/30/2026, 5:00:00 PM
-
-# If any plugins are out of sync, you'll see a hint to run sync
-```
-
-### Sync Plugins
-
-```bash
-# Synchronize plugins from the registry
-# - Rebuilds installed plugins
-# - Reinstalls missing plugins
-c8 sync plugins
-
-# Example output showing detailed sync progress:
-# Starting plugin synchronization...
-# 
-# Found 2 registered plugin(s):
-#   - my-custom-plugin (my-custom-plugin)
-#   - local-dev-plugin (file:///path/to/plugin)
-# 
-# Syncing my-custom-plugin...
-#   ✓ my-custom-plugin is already installed, attempting rebuild...
-# ✓   ✓ my-custom-plugin rebuilt successfully
-# 
-# Syncing local-dev-plugin...
-#   ⚠ local-dev-plugin not found, installing...
-# ✓   ✓ local-dev-plugin installed successfully
-# 
-# Synchronization complete:
-#   ✓ Synced: 2 plugin(s)
-# ✓ All plugins synced successfully!
-```
-
-### Downgrade Plugin
-
-```bash
-# Downgrade a plugin by version
-c8 downgrade plugin my-custom-plugin 1.0.0
-
-# Downgrade is source-aware:
-# - npm source: installs my-custom-plugin@1.0.0
-# - git/URL source: installs <source>#1.0.0
-# - file:// source: version downgrade is not supported
-```
-
-### Upgrade Plugin
-
-```bash
-# Upgrade a plugin to latest
-c8 upgrade plugin my-custom-plugin
-
-# Upgrade a plugin to a specific version
-c8 upgrade plugin my-custom-plugin 1.2.3
-
-# Versioned upgrade is source-aware:
-# - npm source: installs my-custom-plugin@1.2.3
-# - git/URL source: installs <source>#1.2.3
-# - file:// source: version upgrade is not supported
-```
-
-**Plugin Development:**
-
-Plugins must be regular Node.js modules with a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory. The plugin file must export a `commands` object. The `c8ctl` runtime object provides environment information:
-
-When bootstrapping with `c8ctl init plugin <name>`, the generated project also includes an `AGENTS.md` file with an implementation workflow and runtime API reference for coding agents.
-
-```typescript
-// c8ctl-plugin.ts
-
-// Use import type for TypeScript autocomplete only (not a runtime import)
-import type { C8ctlPluginRuntime } from '@camunda8/cli/runtime';
-
-// Access the injected runtime via globalThis
-const c8ctl = globalThis.c8ctl as C8ctlPluginRuntime;
-
-export const commands = {
-  analyze: async (args: string[]) => {
-    console.log(`Running on Node ${c8ctl.nodeVersion}`);
-    console.log(`Platform: ${c8ctl.platform}`);
-    // Custom analysis logic here
-  }
-};
-```
-
-**Plugin Registry:**
-
-Plugins are tracked in a registry file (`~/.config/c8ctl/plugins.json` on Linux) independently of `package.json`. This ensures plugins persist across npm operations and can be synchronized when moving between environments or after npm operations.
-
----
-
-## Combined Examples
-
-### Complete Workflow
-
-```bash
-# 1. Configure environment
-c8 add profile prod --baseUrl=https://camunda.example.com --clientId=xxx --clientSecret=yyy
-c8 use profile prod
-c8 use tenant production
-
-# 2. Deploy process
-c8 deploy ./processes/
-
-# 3. Create and monitor instance
-c8 create pi --id=order-process --variables='{"orderId":"12345"}'
-# ✓ Process instance created [Key: 2251799813685249]
-
-c8 get pi 2251799813685249
-
-# 4. Search for related resources
-c8 search pi --id=order-process --state=ACTIVE
-c8 search variables --processInstanceKey=2251799813685249
-
-# 5. Complete user task
-c8 search ut --state=CREATED --processInstanceKey=2251799813685249
-c8 complete ut 2251799813685250 --variables='{"approved":true}'
-
-# 6. Handle incidents if any
-c8 search inc --state=ACTIVE --processInstanceKey=2251799813685249
-c8 resolve inc 2251799813685251
-```
-
-### Testing Workflow
-
-```bash
-# 1. Use local environment
-c8 use profile local
-c8 output json  # For automated testing
-
-# 2. Deploy and run
-c8 run ./test-process.bpmn --variables='{"testData":"value"}'
-
-# 3. Verify
-c8 list pi --id=test-process
-```
-
-### Multi-Tenant Management
-
-```bash
-# Deploy to multiple tenants
-c8 use tenant tenant-A
-c8 deploy ./shared-processes/
-
-c8 use tenant tenant-B
-c8 deploy ./shared-processes/
-
-# List instances per tenant
-c8 use tenant tenant-A
-c8 list pi
-
-c8 use tenant tenant-B
-c8 list pi
-```
-
----
-
-## Tips
-
-1. **Use Aliases**: Save typing with resource aliases (pi, ut, inc, msg)
-2. **Search vs List**: Use `search` for fine-grained filtering, `list` for simple overviews
-3. **Profile Override**: Use `--profile` flag for one-off commands without changing session
-4. **JSON Output**: Use `c8 output json` for scripting and automation
-5. **Building Blocks**: Organize reusable processes in `_bb-*` folders for deployment priority
-6. **Session State**: Set profile and tenant once, use everywhere
-7. **Full Values**: Use `--fullValue` with `search variables` to see non-truncated values
-8. **Help**: Run `c8 <verb>` without resource to see available resources for that verb
-
----
-
-## Environment Variables
-
-Instead of profiles, you can use environment variables:
-
-```bash
-export CAMUNDA_BASE_URL=https://camunda.example.com
-export CAMUNDA_CLIENT_ID=your-client-id
-export CAMUNDA_CLIENT_SECRET=your-client-secret
-export CAMUNDA_DEFAULT_TENANT_ID=my-tenant
-
-# Now commands use these credentials
-c8 list pi
-```
-
-
----
-
-## Agent / Programmatic Consumption
-
-These examples use flags designed specifically for AI agents and programmatic consumers.
-See [`CONTEXT.md`](./CONTEXT.md) for the complete agent reference.
-
-### `--fields` — Reduce Context Window Size
-
-```bash
-# List process instances with only Key and State
-c8 output json
-c8 list pi --fields Key,State
-
-# Search with selected fields (case-insensitive field names)
-c8 search pd --fields Key,processDefinitionId,name | jq .
-
-# Works with any list/search/get command
-c8 list ut --fields Key,State,Assignee
-c8 search inc --state=ACTIVE --fields Key,Type,processInstanceKey
-c8 get pi 2251799813685249 --fields processInstanceKey,state,processDefinitionId
-```
-
-### `--dry-run` — Preview Mutations Without Executing
-
-```bash
-# Preview creating a process instance
-c8 create pi --id=my-process --dry-run
-# Output: {"dryRun":true,"command":"create process-instance","method":"POST","url":"...","body":{...}}
-
-# Preview deploying resources
-c8 deploy ./my-process.bpmn --dry-run
-
-# Preview cancelling a process instance
-c8 cancel pi 2251799813685249 --dry-run
-
-# Preview completing a user task
-c8 complete ut 2251799813685250 --variables='{"approved":true}' --dry-run
-
-# Preview publishing a message
-c8 publish msg order-received --correlationKey=order-123 --dry-run
-
-# Recommended agent workflow:
-# 1. Run with --dry-run, show user the would-be API call
-c8 create pi --id=my-process --variables='{"key":"value"}' --dry-run
-# 2. After user confirmation, execute
-c8 create pi --id=my-process --variables='{"key":"value"}'
-```
-
-### Machine-Readable Help (JSON Mode)
-
-```bash
-c8 output json
-c8 help          # → structured JSON command reference
-c8 help list     # → JSON for list command
-c8 help search   # → JSON for search command
-```
-
----
-
-## Feedback
-
-```bash
-# Open the issue tracker to report bugs or request features
-c8 feedback
-```
+> **Moved.** The comprehensive, task-oriented examples that used to live here are now
+> maintained in the documentation under [`docs/`](docs/), which is the single source of
+> truth and is published (and kept in sync) on
+> [docs.camunda.io](https://docs.camunda.io/docs/next/apis-tools/c8ctl/getting-started/).
+
+Find examples for each area here:
+
+| Task area | Documentation page |
+| --- | --- |
+| Install, local cluster, credentials, profiles, output modes, shell completion | [Getting started](docs/getting-started.md) |
+| Process instances, user tasks, incidents, jobs, variables, search, messages, forms | [Cluster inspection and process management](docs/cluster-inspection.md) |
+| Users, roles, groups, tenants, authorizations, mapping rules | [Identity management](docs/identity-management.md) |
+| Deploy, run, watch, profiles, sessions, MCP proxy, opening web apps | [Development workflows](docs/development-workflows.md) |
+| Scaffold, install, and manage plugins | [Plugins](docs/plugins.md) |
+| Every command, flag, resource, and alias | [Command reference](docs/command-reference.md) |
+
+When adding or changing a command, document it in the relevant page under [`docs/`](docs/)
+rather than here.