operate

Files (20)

• plugin.json · .claude-plugin/
• SKILL.md
• status.md · commands/
• answer.md · evals/bpmn-question/graders/
• no-skill.md · evals/bpmn-question/graders/
• prompt.md · evals/bpmn-question/
• answer.md · evals/camunda8-operate/graders/
• no-cli.md · evals/camunda8-operate/graders/
• no-skill.md · evals/camunda8-operate/graders/
• prompt.md · evals/camunda8-operate/
• deploy-command.md · evals/deploy-and-start/graders/
• skill-fired.md · evals/deploy-and-start/graders/
• variable.md · evals/deploy-and-start/graders/
• prompt.md · evals/deploy-and-start/
• operate-command.md · evals/open-incidents/graders/
• skill-fired.md · evals/open-incidents/graders/
• prompt.md · evals/open-incidents/
• answer.md · evals/unrelated-code/graders/
• no-skill.md · evals/unrelated-code/graders/
• prompt.md · evals/unrelated-code/

SKILL.md (first lines)

# operate: the Camunda 7 REST API from the command line

`operate` calls the REST API (`/engine-rest`) of Camunda 7 process engines: Operaton, CIB seven and
Camunda 7 CE/EE. Every REST operation is a command generated from the OpenAPI spec:
`operate <group> <command> [path-args...] [options]`; workflow commands such as `operate inspect`
combine several requests. It never prompts, prints JSON when stdout is not a terminal, reports
errors as one JSON line on stderr and uses stable exit codes. This core guide covers everyday use;
`operate guide <topic>` prints the details of a topic (see Topics at the end).

## Setup

If `operate` is missing, run `npx -y @miragon/operate` in its place or ask the user to install it
with `npm i -g @miragon/operate` (Node.js 22.12+). The REST API root defaults to
`http://localhost:8080/engine-rest`. Set it per shell, then check the connection:

```sh
export OPERATE_URL=http://localhost:8080/engine-rest
operate ping
```

A repository may ship its engines as profiles in a project file (`.operate.json`): check
`operate config list` first (scope `project`), a bare `operate ping` then uses its default.

Or keep each engine in a profile and pick one with `--profile`. `--url` and `OPERATE_URL` override
the URL of every profile (and its credentials go along), so unset `OPERATE_URL` first:

```sh
unset OPERATE_URL
operate config set local --url http://localhost:8080/engine-rest --default
operate config set prod --url https://camunda.example.com/engine-rest --read-only
operate ping --profile prod
```

- `operate ping` prints `{url, engine, reachable, version, engines, latencyMs, auth}` (`user` too).
- Precedence for every setting: flag > environment variable > profile > default.
- Links to Cockpit: take `values.cockpitUrl` from `operate config show -o json`; when it is null,
  ask the user for the Cockpit URL instead of guessing it from the engine URL.
- Profiles, project files, environment variables, named engines and headers:
  `operate guide config`. Basic auth, bearer tokens, token commands and OAuth logins:
  `operate guide auth`.

## Discover, describe, preview, run

Never guess commands or flags. Look them up, preview writes, then run:

```sh
operate commands
operate commands --search incident
operate describe process-definition start
operate process-definition start invoice --var amount=250 --dry-run
operate process-definition start invoice --var amount=250
```

- `operate commands` lists the groups (and `workflow`); `operate commands <group>` the commands of
  a group with method, path, effect and summary; `--search` finds commands whose command, alias,
  operationId, summary or path contain every word (`--search 'process instance'`); `--effect`
  filters by `read`, `write`, `delete` or `bulk`.
- `operate describe <group> <command>` (or an operationId or workflow command) shows arguments,
  options, the request body schema, responses and examples (JSON when piped, text with `-o table`).
- `operate <group> <command> --help` shows the options; `operate guide` prints this guide.

## Workflow commands

Top-level commands that combine requests, so no id passes through you. They select an instance by
id, `--business-key` or `--process-definition-key <key> --latest`; `next` lists follow-ups:

- `operate inspect`: where an instance waits and why: wait states, root incidents, variables.
- `operate wait`: until the instance is idle, or `--until ended|incident|task[:key]|activity:<id>`.
- `operate advance`: completes what it waits for: user or external task, message, timer, job.
- `operate retry`: sets the retries behind open incidents; `--now` executes the jobs.
- `operate deploy`: deploys changed files and directories, reports the versions in effect.
- `operate status`: grouped incidents with root cause, overdue jobs, external task workers.

```sh
operate deploy bpmn --start --business-key B-1 --var amount=250
operate inspect --business-key B-1
operate advance --business-key B-1 --var approved=true --wait
operate retry --business-key B-1 --now
operate wait --business-key B-1 --until ended
operate status
```

Use `operate wait` or `--wait` (advance, retry, deploy) instead of `sleep`; it fails on incidents
with exit code 9, which still prints the view. Options and rules: `operate guide workflow`.

## Invocation conventions

- Path parameters are positional arguments in path order; query parameters and body properties are
  kebab-case flags (`businessKey` → `--business-key`); global options work after the command.
- Variables: `--var name=value`, repeatable and auto typed; force a type with `name:Type=value`,
  e.g. `--var zip:String=01234`.
- `--body <json>`, `--body @file.json` or `--body -` (stdin) is the base JSON body for nested
  structures; flags are merged on top, and the body is validated against the API schema.
- List commands with `--max-results` also take `--all` to fetch every page.
- Booleans, arrays, dates, variable types, files and the global options: `operate guide input`.

## Output

- stdout carries exactly the engine response (workflow commands: their view): JSON, compact when
  piped, indented on a terminal or with `--pretty`, always ending with a newline.
- `--fields id,name,variables.amount` keeps only these properties; `-o table` prints a table.
- No content (HTTP 204): stdout stays empty, stderr gets `Done: <METHOD> <path> → 204 No Content`.
- XML, text and binary responses, `--out-file`, `--dry-run` and `--verbose`: `operate guide output`.

## Errors and exit codes

Errors are one JSON line on stderr (`-o table` prints readable text instead):

```text
{"error":{"code":"NOT_FOUND","exitCode":5,"message":"HTTP 404 Not Found: ...","status":404,"engineType":"InvalidRequestException","hint":"...","request":{"method":"GET","url":"..."}}}
```

| exit | meaning                                                                                                |
| ---- | ------------------------------------------------------------------------------------------------------ |
| 0    | success                                                                                                |
| 1    | internal error                                                                                         |
| 2    | usage error, invalid body (`VALIDATION`), `READ_ONLY`, `CONFIRMATION_REQUIRED`                         |
| 3    | configuration error, also an HTTP redirect (`HTTP_REDIRECT`, see below)                                |
| 4    | auth failed: 401, 403, `LOGIN_REQUIRED` (a person must log in), `LOGIN_FAILED`, `TOKEN_EXPIRED`        |

From Miragon/operate, MIT.