casen CLI

casen is an interactive terminal UI (TUI) for managing Camunda 8. Navigate with arrow keys, no flags to memorize.

Installation

pnpm add -g @bpmnkit/cli

Quick Start

casen

The main menu appears. Use ↑ ↓ to navigate, Enter to select, Escape to go back.

Navigation Structure

casen
├── generate        — generate or modify BPMN files without the TUI (alias: gen)
│   ├── bpmn        — templates, CompactDiagram JSON, or patch existing files
│   └── types       — TypeScript types for job workers, generated from BPMN
├── view            — view BPMN, DMN, and form files in the browser
│   ├── open        — any mix of .bpmn/.dmn/.form files or folders (auto-detect)
│   ├── bpmn        — BPMN diagrams rendered as SVG
│   ├── dmn         — DMN decision tables
│   └── form        — Camunda form layouts
├── lint            — static analysis and auto-fix for BPMN files
│   ├── lint        — run all checks, report findings
│   └── improve     — AI-assisted improvement suggestions
├── story           — render a BPMN process as a narrative HTML page
├── migrate         — migrate models from other engines to Camunda 8
│   └── c7          — convert Camunda 7 models and report the manual work
├── ask             — ask an AI assistant about your process or cluster
├── connector       — generate element templates from OpenAPI specs
│   ├── generate    — generate templates from a spec file or catalog entry
│   └── catalog     — list built-in catalog entries
├── profile         — manage connection profiles
│   ├── list        — show all profiles
│   ├── add         — create a new profile
│   └── switch      — set the active profile
├── process
│   ├── list        — list deployed process definitions
│   ├── start       — start a new instance
│   ├── instances   — list running instances
│   └── cancel      — cancel an instance
├── job
│   ├── list        — list active jobs
│   ├── complete    — complete a job
│   └── fail        — fail a job with a message
├── incident
│   ├── list        — list open incidents
│   └── resolve     — resolve an incident
├── decision
│   ├── list        — list deployed DMN decision tables
│   └── evaluate    — evaluate a decision with test inputs
├── variable
│   ├── list        — list variables for an instance
│   └── update      — set a variable value
├── message
│   └── publish     — publish a message for correlation
├── worker          — run job workers
│   ├── <job-type>  — auto-complete worker for a job type
│   └── start       — start scaffolded workers from ./workers/
├── proxy           — start the local AI bridge server
└── plugin          — manage CLI plugins
    ├── search      — discover plugins on npm
    ├── install     — install a plugin from npm or a local path
    ├── list        — list installed plugins
    ├── update      — update one or all plugins
    ├── remove      — uninstall a plugin
    └── info        — show details for an installed plugin

Generate BPMN files

casen generate bpmn creates BPMN files from the command line — no interactive menu required. Choose a built-in template, supply a full CompactDiagram JSON definition, or patch an existing file.

casen generate bpmn --template approval --process-id leave-request
casen generate bpmn --input order.bpmn --dump-compact   # inspect as JSON for AI
casen generate bpmn --input order.bpmn --patch '{"elements":[...],"flows":[...]}'

casen gen types turns BPMN files into TypeScript types for job workers — job types, their variables, output and headers, message names and error codes — and can check that every job type has a worker:

casen gen types processes/ --out src/generated/bpmn-types.ts
casen gen types processes/ --check-workers "src/**/*.ts" --strict

See casen generate for full documentation.

Start from a gallery template

casen template writes one of the runnable templates from the gallery into your project. You get the .bpmn, a .bpmn.tests.json file with its scenarios, and any .dmn or .form files the process uses. The skeletons from casen generate bpmn --template are empty starting shapes. A gallery template is a complete process with its job types, mappings and tests.

casen template list --category approvals
casen template use expense-approval processes/   # --force overwrites existing files

See Process Templates for what each template contains and how to run its scenarios.

View BPMN, DMN, and Form files

casen view opens a local browser-based viewer. Accepts individual files, folders, or a mix.

casen view bpmn ./processes/     # all .bpmn files in a folder
casen view dmn routing.dmn       # DMN decision table
casen view open ./project/       # any mix of .bpmn/.dmn/.form

See casen view for full documentation.

Connection Profiles

A profile stores the connection details for a Camunda cluster:

# Add a new profile
casen profile add

# You'll be prompted for:
# Name: my-saas-cluster
# Base URL: https://api.cloud.camunda.io
# Auth type: oauth2 | bearer | none
# Client ID, Client Secret, Audience, Token URL (for oauth2)

Profiles are saved to ~/.casen/profiles.json.

Common Workflows

List process definitions

Navigate to: process → list → Enter

Result:
  bpmnProcessId                name                    ver
  ──────────────────────────────────────────────────────────
▶ invoice-approval              Invoice Approval          2
  order-fulfillment             Order Fulfillment         1
  customer-onboarding           Customer Onboarding       3

Start a process instance

Navigate to: process → start → Enter

Select process: invoice-approval
Variables (JSON): {"invoiceId": "inv-001", "amount": 5000}

Resolve an incident

Navigate to: incident → list → Enter

Select the incident with Enter, choose “Resolve” from the action menu.

Publish a message

Navigate to: message → publish → Enter

Message name: payment-confirmed
Correlation key: ord-456
Variables (JSON): {"method": "card"}

Plugins

casen’s plugin system lets you extend the CLI with new command groups — your own organisation’s workflows, third-party integrations, or community-built tools.

Discover plugins

# Browse all published casen plugins
casen plugin search

# Search by keyword
casen plugin search deploy
casen plugin search slack

Results are fetched live from the npm registry. Any package tagged with the casen-plugin keyword appears here.

Install a plugin

# Install from npm
casen plugin install casen-deploy

# Install a local plugin during development
casen plugin install ./my-plugin

Plugins are installed into ~/.casen/plugins/ and loaded automatically the next time casen starts.

Manage installed plugins

# List installed plugins
casen plugin list

# Show full details for one plugin
casen plugin info casen-deploy

# Update a single plugin to the latest version
casen plugin update casen-deploy

# Update all installed plugins
casen plugin update

# Remove a plugin
casen plugin remove casen-deploy

Once installed, plugin commands appear in the main TUI and in tab-completion alongside built-in commands.

To build your own plugin, see Plugin Authoring.

BPMN generation pipeline

Every BPMN process is authored as a ProcessPlan JSON file — never hand-written XML — and compiled deterministically:

# Print the ProcessPlan JSON format reference (schema + field notes)
casen plan schema

# Compile a plan to laid-out, deployable BPMN
casen synth synth order-process.plan.json --output order-process.bpmn

# Extend an existing process: lift it back to plan form, then merge a delta plan into it
casen plan extract order-process.bpmn
casen synth synth delta.plan.json --merge order-process.bpmn --output order-process.bpmn

# Find and inspect a Camunda connector template
casen connector search slack
casen connector show io.camunda.connectors.Slack.v1

# Deploy-readiness gate, then deploy
# (a .bpmnlintrc in the diagram's folder or above is honoured; --no-bpmnlintrc ignores it)
casen lint lint order-process.bpmn --profile deploy
casen deploy deploy order-process.bpmn                   # local Reebe
casen deploy deploy order-process.bpmn --target camunda8 # active Camunda 8 profile

casen synth reports any problems keyed by JSON path in the plan (e.g. steps[2].connector.values.token) — fix the plan, never the XML, and re-run. If the plan has a tests array, casen synth also writes a <file>.bpmn.tests.json sidecar, runnable with casen test <file>.bpmn.

--check also proves the result runs:

• It dry-runs each process once, with every connector and job mocked.
• It lists the secrets the diagram reads, to create in the cluster before deploying.

A run that cannot reach its end fails the command:

$ casen synth synth order-process.plan.json --check
✓ Wrote order-process.plan.bpmn
✓ Dry run of order-validation-failed reaches "Ops notified" · 1 connector(s) mocked
Secrets to create in the cluster before deploying:
  SLACK_OAUTH_TOKEN — "Slack Outbound Connector"

With --json, the findings are in the output’s check field.

See Building Processes with AI and AI Agents for full walkthroughs.

casen lint reads a .bpmnlintrc if your project has one. See bpmnlint Compatibility for how the rules map and how to run your own bpmnlint-plugin-* rules.

AIKit Skills

casen ships four lightweight, CLI-only Claude Code slash commands (no MCP server, no proxy):

casen skills install

For the richer skill set (/bpmnkit:implement, :extend, :agent, :connect, plus generated reference docs), install the Claude Code plugin instead: /plugin marketplace add github:bpmnkit/bpmnkit then /plugin install bpmnkit. See AIKit Skills for full documentation.

Worker commands

# Run a simple auto-complete worker (for testing)
casen worker payment-service

# Start scaffolded workers from ./workers/
casen worker start

# Start a specific scaffolded worker
casen worker start send-invoice

Agent workforce

Hire coding-agent CLIs as durable job workers. They serve the .agent() steps of @bpmnkit/flow flows — any service task with job type agent:<role> or agent:<rank>:<role> and a prompt task header. See Durable Agent Flows.

# Hire: everything after -- is the command; the prompt goes on stdin unless an argument has {prompt}
casen agent hire claude --roles plan,pr-review --rank senior -- claude -p
casen agent hire copilot --roles feature --instances 3 -- copilot -p "{prompt}"

casen agent list            # hired agents and the job types they serve
casen agent fire copilot    # remove one
casen agent work            # run the workforce against the active profile until Ctrl+C

Local engine (Reebe)

Reebe is a dev/test workflow engine (~50 MB) that serves the Zeebe API locally, so you can deploy and run processes on your machine or in CI without a Camunda 8 cluster. It is Experimental and single-node: do not run it in production. Reebe is a clean-room implementation written from Camunda’s public documentation, and is not affiliated with or endorsed by Camunda. “Zeebe” and “Camunda” are trademarks of Camunda Services GmbH.

# Embedded SQLite, no external database
casen reebe start

# REST on 26500, where ZEEBE_ADDRESS points by default. The gRPC gateway uses 26500
# unless told otherwise, so move it out of the way.
casen reebe start --port 26500 --grpc-port 26501

# PostgreSQL instead of the embedded database
casen reebe start --database-url postgres://user:pass@localhost/reebe

casen reebe on its own is shorthand for casen reebe start. The command runs the reebe-server binary. If it is not on your PATH, build the embedded (SQLite) server with cargo install --path apps/reebe/crates/reebe-server --no-default-features --features embedded, or the PostgreSQL one — which needs --database-url — without the two feature flags.

Local proxy

casen proxy start (or casen proxy) starts the local proxy on port 3033. Studio, the bpmnkit.com editor and Operate page, and the desktop app use it for AI, deploys, Camunda API calls with your stored profiles, and Studio’s project folders.

casen proxy start

The same settings are read from BPMNKIT_PROXY_HOST, BPMNKIT_PROXY_ALLOWED_ORIGINS, BPMNKIT_PROXY_ALLOWED_HOSTS and BPMNKIT_PROXY_ROOTS, for example when you run the bpmn-ai-server binary directly. Flags add to the lists from the environment.

Who can use the proxy

The proxy acts with your Camunda credentials and reads and writes files. Any web page open in your browser can send requests to localhost, so the proxy checks every request:

• Origin. A browser request must come from https://bpmnkit.com, https://bpmnkit-studio.pages.dev, the desktop app (tauri://localhost, http(s)://tauri.localhost), any localhost, 127.0.0.1 or [::1] origin on any port, or an origin you allow with --allow-origin. Other origins get 403 and no CORS headers. Cross-site browser requests without an Origin header, such as an image tag, are also refused. Programs that send no Origin (the CLI, the MCP server, curl) are served.
• Host. A request must name the proxy as localhost, 127.0.0.1 or [::1], or as a host you allow with --allow-host. This stops DNS-rebinding pages.
• Files. The /fs/* routes and /element-templates work only inside workspace roots: folders you pass with --root, and project folders Studio opens. The proxy does not open the filesystem root, your home directory, a folder that contains your home directory, or a hidden folder such as ~/.ssh unless you pass it with --root. Inside a root, only .bpmn, .dmn, .form and .md files (and their .bpmnkit metadata) can be read, written, moved or deleted. Paths with .., and symlinks that lead out of the root, are refused.
• AI CLIs. The AI routes (/chat, /improve, /operate/chat, /operate/incident-assist, /operate/ai-search), the io.bpmnkit:llm:1 worker and casen ask start claude, copilot or gemini with permission checks on and no built-in tools: the model cannot run commands, read or write files, or open URLs. Each run starts in an empty temporary folder and loads none of your own MCP servers, settings, plugins or extensions. A /chat run that edits a diagram gets only the proxy’s diagram tools (get_diagram, compose_diagram, add_elements, remove_elements, update_element, set_condition, add_http_call, find_connectors, add_connector, replace_diagram); they change the diagram in the MCP server’s memory, and compose_diagram runs the model’s code in an isolated V8 isolate. The connector tools also read the bundled connector catalog and API index, and nothing else. Chat text, diagrams, incident details and variable values reach the model fenced as untrusted data.

To use the proxy from your own web app, allow its origin:

casen proxy start --allow-origin https://modeler.example.com

To reach the proxy from another machine, which gives that network your credentials and files, listen on all interfaces and name the host clients use:

casen proxy start --host 0.0.0.0 --allow-host devbox.lan

MCP Server Mode

casen proxy mcp starts BPMN Kit’s MCP (Model Context Protocol) server on stdio, so Claude Code, Claude Desktop, Cursor or any MCP client can create, validate, simulate and deploy processes, and call any Camunda 8 REST operation through camunda_search and camunda_execute:

casen proxy mcp

Configure it in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "bpmnkit": {
      "command": "casen",
      "args": ["proxy", "mcp"]
    }
  }
}

The server uses the active casen profile for cluster calls; set one with casen profile first, or pass ZEEBE_ADDRESS, ZEEBE_CLIENT_ID and ZEEBE_CLIENT_SECRET in env. The full tool list is in the AI guide.

Now you can ask Claude: “Show me the open incidents on the invoice-approval process” or “Resolve all incidents on process instance 2251799813685249”.