Skip to content

index.md

Latest commit

 

History

History
180 lines (146 loc) · 9.91 KB

index.md

File metadata and controls

180 lines (146 loc) · 9.91 KB
title CLI Reference
nav_order 2
nav_exclude false
has_toc true

c8volt CLI Reference

This section is the command reference for c8volt. The individual command pages are generated from the Cobra command tree; this page explains how to read that reference and links the command groups that matter for day-to-day operation.

For the project overview, installation notes, and broader examples, use the home page. This page stays closer to the CLI contract: command shape, version support, mutation behavior, output modes, and safety controls.

For tool-selection context, see Camunda CLI options and AI and search context. Those pages help search engines, AI assistants, and operators classify c8volt alongside c8ctl, zbctl, REST APIs, and SDKs without treating c8volt as an official Camunda product.

Scope

c8volt operates Camunda 8 clusters from the command line. The current command surface covers:

  • connection and configuration checks
  • cluster topology, version, and license reads
  • process-definition discovery, XML retrieval, and deployment
  • process-instance start, search, wait, walk, cancel, delete, and variable update
  • incident search, incident resolution, and process-instance incident repair
  • job lookup, retry update, and timeout update
  • tenant and resource reads
  • high-level ops workflows for smoke tests, retention, purge, and repair
  • machine-readable discovery through capabilities --json

The reference pages document the available flags and examples for each command. They do not replace a dry-run plan for destructive operations.

Version Support

c8volt supports Camunda 8.7, 8.8, and 8.9, but not every command is available on every upstream version.

Area 8.9 8.8 8.7
Cluster, config, tenant, process-definition, process-instance reads supported supported supported
Deploy and run process instances supported supported supported
Cancel and delete process instances supported supported limited
Process-instance variable update supported supported unsupported
get job and update job supported supported unsupported
Incident resolution and repair workflows supported supported unsupported
delete process-definition supported unsupported unsupported
ops purge all-process-definitions supported unsupported unsupported

Process-definition deletion requires Camunda 8.9 or newer because c8volt depends on the endpoint shape that supports full process-definition history deletion. On 8.8, use delete process-instance --bpmn-process-id BPMN_PROCESS_ID when the intended operation is to remove process instances for a definition.

Execution Model

Most state-changing commands follow the same pattern:

  1. select targets by key, stdin, or filters
  2. preview the target set when --dry-run is available
  3. require confirmation unless --auto-confirm or --automation is used
  4. submit the Camunda mutation
  5. wait for the observable result unless --no-wait is used

For process-instance family operations, c8volt expands the selected instance to the relevant root or descendant scope before mutating. For process-definition delete and all-process-definition purge on Camunda 8.9, c8volt also waits until the deleted process definition is no longer visible unless --no-wait is set.

Output Modes

Common output controls:

  • --json writes structured command output where the command supports it
  • --keys-only emits keys for pipelines where the command supports it
  • --quiet suppresses normal output except errors
  • --verbose includes additional diagnostic detail
  • --automation enables non-interactive behavior only for commands that explicitly support automation
  • capabilities --json exposes a machine-readable command and flag contract

Human logs are written separately from JSON payloads where a command provides a machine-output mode.

Safety Controls

Use these flags deliberately:

  • --dry-run previews supported destructive and repair workflows without mutation
  • --auto-confirm answers command prompts for unattended runs
  • --no-wait returns after Camunda accepts work instead of waiting for confirmation
  • --force broadens the mutation scope when the command needs root cancellation or cancel-before-delete behavior
  • --workers limits concurrency for batch operations
  • --fail-fast stops scheduling additional work after the first failure

Prefer --dry-run before broad selectors such as BPMN process id, incident filters, retention windows, or all-process-definition purge.

Command Map

Command Purpose Reference
c8volt Root command, global flags, and top-level examples c8volt
capabilities Machine-readable command contract capabilities
config Show, validate, template, and test configuration config
get cluster Cluster topology, version, and license get cluster
get process-definition List definitions, fetch latest versions, and retrieve XML get process-definition
get process-instance Search or fetch process instances, variables, incidents, and task context get process-instance
get incident Search incidents, fetch incident keys, and emit process-instance keys get incident
get job Fetch a job by key get job
get tenant List visible tenants get tenant
get resource Fetch a resource by id get resource
deploy process-definition Deploy BPMN process definitions from files or stdin deploy process-definition
embed List, deploy, or export bundled BPMN fixtures embed
run process-instance Start process instances and confirm activation by default run process-instance
update process-instance Update process-instance-scope variables update process-instance
update job Update job retries or timeout update job
expect process-instance Wait for process-instance state or incident conditions expect process-instance
walk process-instance Inspect ancestry, descendants, full family trees, variables, and incidents walk process-instance
cancel process-instance Cancel process instances by key or filters cancel process-instance
delete process-instance Delete process-instance history, with optional cancel-before-delete handling delete process-instance
delete process-definition Delete process definitions on Camunda 8.9+ delete process-definition
resolve incident Resolve incident keys resolve incident
resolve process-instance Resolve active incidents for selected process instances resolve process-instance
ops execute smoke-test Deploy, run, walk, and clean up a smoke-test fixture ops execute smoke-test
ops execute retention-policy Delete finished process instances selected by age and state ops execute retention-policy
ops purge orphan-process-instances Find and purge orphan child process instances ops purge orphan-process-instances
ops purge process-instances-with-incidents Purge process instances selected through incident filters ops purge process-instances-with-incidents
ops purge all-process-definitions Purge selected process definitions on Camunda 8.9+ ops purge all-process-definitions
ops repair incident Repair variables/jobs and resolve selected incidents ops repair incident
ops repair process-instance Discover and repair incidents for selected process instances ops repair process-instance
version Print build and compatibility information version

Selector Conventions

Common selectors are shared across command groups:

  • --key selects explicit resource, process-instance, incident, or process-definition keys
  • - reads keys from stdin for commands that document stdin support
  • --bpmn-process-id selects process instances or definitions by BPMN id
  • --pd-version, --pd-version-tag, and --latest narrow process-definition selection
  • --tenant overrides tenant selection from config for tenant-aware flows
  • date filters such as --start-date-* and --end-date-* bound process-instance searches

When a command accepts both explicit keys and filters, the command page describes which combinations are valid.

Reports And Playbooks

The ops command family composes lower-level commands into audited workflows. These pages are written as operational playbooks rather than raw Cobra output:

Use the playbooks for workflow behavior and audit-report fields; use the generated command pages for exact flags and aliases.