Command reference

Global Flags

These flags are accepted by every command.

Flag	Type	Required	Description
--help / -h	boolean		Show help
--version / -v	string		Show CLI version, or filter by process definition version on supported commands
--profile	string		Use a specific profile
--dry-run	boolean		Preview the API request without executing
--verbose	boolean		Show verbose output
--fields	string		Comma-separated list of fields to display
--json	boolean		Force JSON output for this invocation (does not persist; overrides session state and C8CTL_OUTPUT_MODE)
--yes / -y	boolean		Skip confirmation prompts

Resource Aliases

Alias	Resource
auth	authorization
inc	incident
mr	mapping-rule
msg	message
pd	process-definition
pi	process-instance
ut	user-task
vars	variable
var	variable
ws	wait-state

Search Flags

These flags are available on list and search commands.

Flag	Type	Required	Description
--sortBy	string		Sort results by field
--asc	boolean		Sort ascending
--desc	boolean		Sort descending
--limit	string		Maximum number of results
--between	string		Date range filter (e.g. 2024-01-01..2024-12-31, ..2024-12-31, 2024-01-01..)
--dateField	string		Date field for --between filter

Commands

list

List resources

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)

Verb-level flags:

Flag	Type	Required	Description
--all	boolean		List all (disable pagination limit)

Resource-specific flags:

process-definition (pd)

Flag	Type	Required	Description
--bpmnProcessId	string		Filter by BPMN process ID
--id	string		Filter by BPMN process ID (alias)
--processDefinitionId	string		Filter by process definition ID
--name	string		Filter by name
--key	string		Filter by key
--iid	string		Case-insensitive filter by BPMN process ID
--iname	string		Case-insensitive filter by name

process-instance (pi)

Flag	Type	Required	Description
--businessId	string		Filter by Business ID (Camunda 8.9+)
--bpmnProcessId	string		Filter by BPMN process ID
--id	string		Filter by BPMN process ID (alias)
--processDefinitionId	string		Filter by process definition ID
--processDefinitionKey	string		Filter by process definition key
--state	string		Filter by state (ACTIVE, COMPLETED, etc)
--key	string		Filter by key
--parentProcessInstanceKey	string		Filter by parent process instance key
--iid	string		Case-insensitive filter by BPMN process ID

user-task (ut)

Flag	Type	Required	Description
--state	string		Filter by state
--assignee	string		Filter by assignee
--processInstanceKey	string		Filter by process instance key
--processDefinitionKey	string		Filter by process definition key
--elementId	string		Filter by element ID
--iassignee	string		Case-insensitive filter by assignee

incident (inc)

Flag	Type	Required	Description
--state	string		Filter by state
--processInstanceKey	string		Filter by process instance key
--processDefinitionKey	string		Filter by process definition key
--bpmnProcessId	string		Filter by BPMN process ID
--id	string		Filter by BPMN process ID (alias)
--processDefinitionId	string		Filter by process definition ID
--errorType	string		Filter by error type
--errorMessage	string		Filter by error message
--ierrorMessage	string		Case-insensitive filter by error message
--iid	string		Case-insensitive filter by BPMN process ID

jobs

Flag	Type	Required	Description
--state	string		Filter by state
--type	string		Filter by job type
--processInstanceKey	string		Filter by process instance key
--processDefinitionKey	string		Filter by process definition key
--itype	string		Case-insensitive filter by job type

user

Flag	Type	Required	Description
--username	string		Filter by username
--name	string		Filter by name
--email	string		Filter by email

role

Flag	Type	Required	Description
--roleId	string		Filter by role ID
--name	string		Filter by name

group

Flag	Type	Required	Description
--groupId	string		Filter by group ID
--name	string		Filter by name

tenant

Flag	Type	Required	Description
--tenantId	string		Filter by tenant ID
--name	string		Filter by name

authorization (auth)

Flag	Type	Required	Description
--ownerId	string		Filter by owner ID
--ownerType	string		Filter by owner type
--resourceType	string		Filter by resource type
--resourceId	string		Filter by resource ID

mapping-rule (mr)

Flag	Type	Required	Description
--mappingRuleId	string		Filter by mapping rule ID
--name	string		Filter by name
--claimName	string		Filter by claim name
--claimValue	string		Filter by claim value

Examples:

c8ctl list pi                                               # List process instances
c8ctl list pd                                               # List process definitions
c8ctl list users                                            # List users

---

search

Search resources with filters (wildcards, date ranges, case-insensitive)

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), ws (wait-state)

Resource-specific flags:

process-definition (pd)

Flag	Type	Required	Description
--bpmnProcessId	string		Filter by BPMN process ID
--id	string		Filter by BPMN process ID (alias)
--processDefinitionId	string		Filter by process definition ID
--name	string		Filter by name
--key	string		Filter by key
--iid	string		Case-insensitive filter by BPMN process ID
--iname	string		Case-insensitive filter by name

process-instance (pi)

Flag	Type	Required	Description
--businessId	string		Filter by Business ID (Camunda 8.9+)
--bpmnProcessId	string		Filter by BPMN process ID
--id	string		Filter by BPMN process ID (alias)
--processDefinitionId	string		Filter by process definition ID
--processDefinitionKey	string		Filter by process definition key
--state	string		Filter by state (ACTIVE, COMPLETED, etc)
--key	string		Filter by key
--parentProcessInstanceKey	string		Filter by parent process instance key
--iid	string		Case-insensitive filter by BPMN process ID

user-task (ut)

Flag	Type	Required	Description
--state	string		Filter by state
--assignee	string		Filter by assignee
--processInstanceKey	string		Filter by process instance key
--processDefinitionKey	string		Filter by process definition key
--elementId	string		Filter by element ID
--iassignee	string		Case-insensitive filter by assignee

incident (inc)

Flag	Type	Required	Description
--state	string		Filter by state
--processInstanceKey	string		Filter by process instance key
--processDefinitionKey	string		Filter by process definition key
--bpmnProcessId	string		Filter by BPMN process ID
--id	string		Filter by BPMN process ID (alias)
--processDefinitionId	string		Filter by process definition ID
--errorType	string		Filter by error type
--errorMessage	string		Filter by error message
--ierrorMessage	string		Case-insensitive filter by error message
--iid	string		Case-insensitive filter by BPMN process ID

jobs

Flag	Type	Required	Description
--state	string		Filter by state
--type	string		Filter by job type
--processInstanceKey	string		Filter by process instance key
--processDefinitionKey	string		Filter by process definition key
--itype	string		Case-insensitive filter by job type

variable (var, vars)

Flag	Type	Required	Description
--name	string		Filter by variable name
--value	string		Filter by value
--processInstanceKey	string		Filter by process instance key
--scopeKey	string		Filter by scope key
--fullValue	boolean		Return full variable values (not truncated)
--iname	string		Case-insensitive filter by name
--ivalue	string		Case-insensitive filter by value

user

Flag	Type	Required	Description
--username	string		Filter by username
--name	string		Filter by name
--email	string		Filter by email

role

Flag	Type	Required	Description
--roleId	string		Filter by role ID
--name	string		Filter by name

group

Flag	Type	Required	Description
--groupId	string		Filter by group ID
--name	string		Filter by name

tenant

Flag	Type	Required	Description
--tenantId	string		Filter by tenant ID
--name	string		Filter by name

authorization (auth)

Flag	Type	Required	Description
--ownerId	string		Filter by owner ID
--ownerType	string		Filter by owner type
--resourceType	string		Filter by resource type
--resourceId	string		Filter by resource ID

mapping-rule (mr)

Flag	Type	Required	Description
--mappingRuleId	string		Filter by mapping rule ID
--name	string		Filter by name
--claimName	string		Filter by claim name
--claimValue	string		Filter by claim value

wait-state (ws)

Flag	Type	Required	Description
--processInstanceKey / -k	string		Filter by process instance key
--rootProcessInstanceKey / -r	string		Filter by root process instance key
--elementInstanceKey / -e	string		Filter by element instance key
--elementId	string		Filter by element ID (supports wildcards, e.g. *Task*)
--elementType	string		Filter by BPMN element type (e.g. SERVICE_TASK, USER_TASK, CALL_ACTIVITY)
--waitStateType	string		Filter by wait state type (JOB, MESSAGE, TIMER, CONDITION, USER_TASK, SIGNAL)

Examples:

c8ctl search pi --state=ACTIVE                              # Search for active process instances
c8ctl search pd --bpmnProcessId=myProcess                   # Search process definitions by ID
c8ctl search pd --name='*main*'                             # Search process definitions with wildcard
c8ctl search ut --assignee=john                             # Search user tasks assigned to john
c8ctl search inc --state=ACTIVE                             # Search for active incidents
c8ctl search jobs --type=myJobType                          # Search jobs by type
c8ctl search jobs --type='*service*'                        # Search jobs with type containing "service"
c8ctl search variables --name=myVar                         # Search for variables by name
c8ctl search variables --value=foo                          # Search for variables by value
c8ctl search variables --processInstanceKey=123 --fullValue  # Search variables with full values
c8ctl search pd --iname='*order*'                           # Case-insensitive search by name
c8ctl search ut --iassignee=John                            # Case-insensitive search by assignee
c8ctl search ws --waitStateType=JOB                         # Search wait states of type JOB
c8ctl search ws --elementType=SERVICE_TASK                  # Search wait states on service tasks

---

get

Get a resource by key

Resources: pi (process-instance), pd (process-definition), inc (incident), topology, form, user, role, group, tenant, auth (authorization), mapping-rule

Positional arguments:

• process-definition: <key> (required)
• process-instance: <key> (required)
• incident: <key> (required)
• user: <username> (required)
• role: <roleId> (required)
• group: <groupId> (required)
• tenant: <tenantId> (required)
• authorization: <authorizationKey> (required)
• mapping-rule: <mappingRuleId> (required)
• form: <key> (required)

Resource-specific flags:

process-definition (pd)

Flag	Type	Required	Description
--xml	boolean		Get BPMN XML (process definitions)

form

Flag	Type	Required	Description
--userTask	boolean		Get form for user task
--ut	boolean		Alias for --userTask
--processDefinition	boolean		Get form for process definition
--pd	boolean		Alias for --processDefinition

process-instance (pi)

Flag	Type	Required	Description
--variables	boolean		Include variables in output

Examples:

c8ctl get pi 123456                                         # Get process instance by key
c8ctl get pi 123456 --variables                             # Get process instance with variables
c8ctl get pd 123456                                         # Get process definition by key
c8ctl get pd 123456 --xml                                   # Get process definition XML
c8ctl get form 123456                                       # Get form (searches both user task and process definition)
c8ctl get form 123456 --ut                                  # Get form for user task only
c8ctl get form 123456 --pd                                  # Get start form for process definition only
c8ctl get user john                                         # Get user by username

---

create

Create a resource (process instance, identity)

Resources: pi (process-instance), user, role, group, tenant, auth (authorization), mapping-rule

Resource-specific flags:

process-instance (pi)

Flag	Type	Required	Description
--processDefinitionId	string		Process definition ID (BPMN process ID)
--id	string		Process definition ID (alias for --processDefinitionId)
--bpmnProcessId	string		BPMN process ID (alias for --processDefinitionId)
--businessId	string		Business ID for the process instance (Camunda 8.9+)
--variables	string		JSON variables
--awaitCompletion	boolean		Wait for process to complete
--fetchVariables	boolean		Fetch result variables on completion
--requestTimeout	string		Await timeout in milliseconds

user

Flag	Type	Required	Description
--username	string		Username
--name	string		Display name
--email	string		Email address
--password	string		Password

role

Flag	Type	Required	Description
--roleId	string		Role ID
--name	string		Display name

group

Flag	Type	Required	Description
--groupId	string		Group ID
--name	string		Display name

tenant

Flag	Type	Required	Description
--tenantId	string		Tenant ID
--name	string		Display name

mapping-rule (mr)

Flag	Type	Required	Description
--mappingRuleId	string		Mapping rule ID
--name	string		Display name
--claimName	string		Claim name
--claimValue	string		Claim value

authorization (auth)

Flag	Type	Required	Description
--ownerId	string	Yes	Authorization owner ID
--ownerType	string	Yes	Authorization owner type
--resourceType	string	Yes	Authorization resource type
--resourceId	string	Yes	Authorization resource ID
--permissions	string	Yes	Comma-separated permissions

Examples:

c8ctl create pi --id=myProcess --businessId=order-123       # Create a process instance with a Business ID
c8ctl create pi --id=myProcess --awaitCompletion            # Create and await completion
c8ctl create user --username=john --name='John Doe' --email=john@example.com --password=secret  # Create a user

---

delete

Delete a resource by key

Usage: c8ctl delete <resource> <key>

Resources: user, role, group, tenant, auth (authorization), mapping-rule

Positional arguments:

• user: <username> (required)
• role: <roleId> (required)
• group: <groupId> (required)
• tenant: <tenantId> (required)
• authorization: <authorizationKey> (required)
• mapping-rule: <mappingRuleId> (required)

Examples:

c8ctl delete user john                                      # Delete user

---

cancel

Cancel a process instance

Usage: c8ctl cancel <resource> <key>

Resources: pi (process-instance)

Positional arguments:

• process-instance: <key> (required)

---

await

Create and await process instance completion (server-side waiting)

Usage: c8ctl await <resource>

Resources: pi (process-instance)

Flags:

Flag	Type	Required	Description
--processDefinitionId	string		Process definition ID (BPMN process ID)
--id	string		Process definition ID (alias for --processDefinitionId)
--bpmnProcessId	string		BPMN process ID (alias for --processDefinitionId)
--businessId	string		Business ID for the process instance (Camunda 8.9+)
--variables	string		JSON variables
--fetchVariables	boolean		Fetch result variables on completion
--requestTimeout	string		Await timeout in milliseconds

Examples:

c8ctl await pi --id=myProcess --businessId=claim-456        # Create with a Business ID and wait for completion

---

complete

Complete a user task or job

Usage: c8ctl complete <resource> <key>

Resources: ut (user-task), job

Positional arguments:

• user-task: <key> (required)
• job: <key> (required)

Flags:

Flag	Type	Required	Description
--variables	string		JSON variables

---

fail

Mark a job as failed with optional error message and retry count

Resources: job

Positional arguments:

• job: <key> (required)

Flags:

Flag	Type	Required	Description
--retries	string		Remaining retries
--errorMessage	string		Error message

---

update

Update the retries or timeout of a job. At least one of --retries or --timeout must be provided.

Resources: job

Positional arguments:

• job: <key> (required)

Flags:

Flag	Type	Required	Description
--retries	string		New number of retries for the job
--timeout	string		New job timeout in milliseconds
--operationReference	string		Optional operation reference (long integer)

Examples:

c8ctl update job 12345 --retries 3                          # Set the retry count for a job
c8ctl update job 12345 --timeout 60000                      # Set the job timeout to 60 seconds

---

activate

Activate jobs of a specific type for processing

Resources: jobs

Positional arguments:

• jobs: <type> (required)

Flags:

Flag	Type	Required	Description
--maxJobsToActivate	string		Maximum number of jobs to activate
--timeout	string		Job timeout in milliseconds
--worker	string		Worker name
--customHeaders	boolean		Include custom headers in output
--fetchVariable	string		Comma-separated variable names to fetch from the server and include in output

---

resolve

Resolve an incident (marks resolved, allows process to continue)

Resources: inc (incident)

Positional arguments:

• incident: <key> (required)

---

publish

Publish a message for message correlation

Resources: msg (message)

Positional arguments:

• message: <name> (required)

Flags:

Flag	Type	Required	Description
--correlationKey	string		Correlation key
--variables	string		JSON variables
--timeToLive	string		Time to live in milliseconds

---

correlate

Correlate a message to a specific process instance

Resources: msg (message)

Positional arguments:

• message: <name> (required)

Flags:

Flag	Type	Required	Description
--correlationKey	string	Yes	Correlation key
--variables	string		JSON variables
--timeToLive	string		Time to live in milliseconds

---

set

Set 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.

Usage: c8ctl set variable <key>

Resources: variable

Positional arguments:

• variable: <key> (required)

Flags:

Flag	Type	Required	Description
--variables	string	Yes	JSON object of variables to set (required)
--local	boolean		Set variables in local scope only (default: propagate to outermost scope)

Examples:

c8ctl set variable 2251799813685249 --variables='{"status":"approved"}'  # Set variables on a process instance
c8ctl set variable 2251799813685249 --variables='{"x":1}' --local  # Set variables in local scope only

---

deploy

Deploy 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.

Usage: c8ctl deploy [path...]

Flags:

Flag	Type	Required	Description
--force	boolean		Deploy any file type, ignoring the default extension allow-list
--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.
--all-extensions	boolean		Include all server-supported file extensions during directory discovery

Examples:

c8ctl deploy ./my-process.bpmn                              # Deploy a BPMN file
c8ctl deploy                                                # Deploy from current directory (detects process application root)

---

run

Deploy and start a process instance from a BPMN file

Usage: c8ctl run <path>

Flags:

Flag	Type	Required	Description
--businessId	string		Business ID for the process instance (Camunda 8.9+)
--variables	string		JSON variables
--force	boolean		Deploy any file type, ignoring the default extension allow-list

Examples:

c8ctl run ./my-process.bpmn --businessId=order-123          # Deploy and start a process with a Business ID

---

assign

Assign a resource to a target (--to-user, --to-group, etc.)

Usage: c8ctl assign <resource> <id>

Resources: role, user, group, mapping-rule

Positional arguments:

• role: <roleId> (required)
• user: <username> (required)
• group: <groupId> (required)
• mapping-rule: <mappingRuleId> (required)

Flags:

Flag	Type	Required	Description
--to-user	string		Target user ID
--to-group	string		Target group ID
--to-tenant	string		Target tenant ID
--to-mapping-rule	string		Target mapping rule ID

Examples:

c8ctl assign role admin --to-user=john                      # Assign role to user

---

unassign

Unassign a resource from a target (--from-user, --from-group, etc.)

Usage: c8ctl unassign <resource> <id>

Resources: role, user, group, mapping-rule

Positional arguments:

• role: <roleId> (required)
• user: <username> (required)
• group: <groupId> (required)
• mapping-rule: <mappingRuleId> (required)

Flags:

Flag	Type	Required	Description
--from-user	string		Source user ID
--from-group	string		Source group ID
--from-tenant	string		Source tenant ID
--from-mapping-rule	string		Source mapping rule ID

Examples:

c8ctl unassign role admin --from-user=john                  # Unassign role from user

---

watch

Watch files for changes and auto-deploy

Usage: c8ctl watch [path...]

Aliases: w

Flags:

Flag	Type	Required	Description
--force	boolean		Continue watching after all deployment errors
--extensions	string		Comma-separated list of additional file extensions to watch (merged with defaults, e.g. .md,.txt)
--all-extensions	boolean		Watch all server-supported file extensions
--process-application	boolean		Watch and deploy the entire process application (requires .process-application marker)
--pa	boolean		Alias for --process-application

Examples:

c8ctl watch ./src                                           # Watch directory for changes

---

open

Open Camunda web app in browser

Usage: c8ctl open <app>

Resources: operate, tasklist, modeler, optimize

Examples:

c8ctl open operate                                          # Open Camunda Operate in browser
c8ctl open tasklist                                         # Open Camunda Tasklist in browser
c8ctl open operate --profile=prod                           # Open Operate using a specific profile

---

add

Add a profile

Resources: profile

Positional arguments:

• profile: <name> (required)

Flags:

Flag	Type	Required	Description
--baseUrl	string		Cluster base URL
--clientId	string		OAuth client ID
--clientSecret	string		OAuth client secret
--audience	string		OAuth audience
--oAuthUrl	string		OAuth token URL
--scope	string		OAuth scope (space-separated)
--defaultTenantId	string		Default tenant ID
--username	string		Basic auth username
--password	string		Basic auth password
--from-file	string		Import from .env file
--from-env	boolean		Import from environment variables

---

remove

Remove a profile (alias: rm)

Usage: c8ctl remove profile <name>

Aliases: rm

Resources: profile

Positional arguments:

• profile: <name> (optional)

Flags:

Flag	Type	Required	Description
--none	boolean		Clear active profile

---

load

Load a c8ctl plugin (npm registry or URL)

Usage: c8ctl load plugin [name|--from url]

Resources: plugin

Positional arguments:

• plugin: <package> (optional)

Flags:

Flag	Type	Required	Description
--from	string		Load plugin from URL

Examples:

c8ctl load plugin my-plugin                                 # Load plugin from npm registry
c8ctl load plugin --from https://github.com/org/plugin      # Load plugin from URL

---

unload

Unload a c8ctl plugin (npm uninstall wrapper)

Usage: c8ctl unload plugin <name>

Aliases: rm

Resources: plugin

Positional arguments:

• plugin: <package> (required)

Flags:

Flag	Type	Required	Description
--force	boolean		Force unload without confirmation

---

upgrade

Upgrade a plugin (respects source type)

Usage: c8ctl upgrade plugin <name> [version]

Resources: plugin

Positional arguments:

• plugin: <package> (required), <version> (optional)

Examples:

c8ctl upgrade plugin my-plugin                              # Upgrade plugin to latest version
c8ctl upgrade plugin my-plugin 1.2.3                        # Upgrade plugin to a specific version (source-aware)

---

downgrade

Downgrade a plugin to a specific version

Usage: c8ctl downgrade plugin <name> <version>

Resources: plugin

Positional arguments:

• plugin: <package> (required), <version> (required)

---

sync

Synchronize plugins from registry (rebuild/reinstall)

Resources: plugin

Examples:

c8ctl sync plugin                                           # Synchronize plugins

---

init

Create a new plugin from TypeScript template

Resources: plugin

Positional arguments:

• plugin: <name> (optional)

Examples:

c8ctl init plugin my-plugin                                 # Create new plugin from template (c8ctl-plugin-my-plugin)

---

doctor

Surface 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).

Resources: plugin

Examples:

c8ctl doctor plugin                                         # List loaded plugins and any load-time collisions
c8ctl doctor plugin --json                                  # Machine-readable doctor output

---

use

Set active profile or tenant

Usage: c8ctl use profile|tenant

Resources: profile, tenant

Positional arguments:

• profile: <name> (optional)
• tenant: <tenantId> (required)

Flags:

Flag	Type	Required	Description
--none	boolean		Clear active profile/tenant

Examples:

c8ctl use profile prod                                      # Set active profile

---

output

Show or set output format

Usage: c8ctl output [json|text]

Resources: json, text

Examples:

c8ctl output json                                           # Switch to JSON output

---

completion

Generate shell completion script

Usage: c8ctl completion bash|zsh|fish|install

Resources: bash, zsh, fish, install

Resource-specific flags:

install

Flag	Type	Required	Description
--shell	string		Shell to install completions for (bash, zsh, fish)

Examples:

c8ctl completion bash                                       # Generate bash completion script
c8ctl completion install                                    # Auto-detect shell and install completions (auto-refreshes on upgrade)
c8ctl completion install --shell zsh                        # Install completions for a specific shell

---

mcp-proxy

Start a STDIO MCP proxy (bridges local MCP clients to remote Camunda 8)

Usage: c8ctl mcp-proxy [mcp-path]

---

feedback

Open the feedback page to report issues or request features

---

help

Show help (run 'c8ctl help <command>' for details)

Usage: c8ctl help [command]

Aliases: menu

---

which

Show active profile or output mode

Resources: profile, output

Examples:

c8ctl which profile                                         # Show currently active profile
c8ctl which output                                          # Show current output mode