@miragon/pulse-cli 0.0.0-stage → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +173 -2
  3. package/dist/pulse-cli.js +147655 -0
  4. package/package.json +68 -3
  5. package/skills/pulse-cli/.claude-plugin/plugin.json +21 -0
  6. package/skills/pulse-cli/SKILL.md +168 -0
  7. package/skills/pulse-cli/commands/status.md +30 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Miragon GmbH
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,174 @@
1
- # Temporary Holding Version
1
+ # Pulse CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/@miragon/pulse-cli.svg)](https://www.npmjs.com/package/@miragon/pulse-cli)
4
+ [![CI](https://github.com/Miragon/pulse/actions/workflows/ci.yml/badge.svg)](https://github.com/Miragon/pulse/actions/workflows/ci.yml)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6
+ [![Documentation](https://img.shields.io/badge/docs-miragon.github.io%2Fpulse%2Fcli-blue.svg)](https://miragon.github.io/pulse/cli/)
7
+
8
+ A command line tool that lets an AI agent (or a human at a shell) **operate a Camunda 7 process
9
+ engine**: [Operaton](https://operaton.org), [CIB seven](https://cibseven.org) and Camunda 7. Deploy
10
+ processes and decisions, start and follow instances, work on tasks, fix incidents, migrate running
11
+ instances, look into the history and administer users and permissions. The agent says what should
12
+ happen, and the CLI talks to the REST API.
13
+
14
+ ![pulse-cli status finds five incidents at Charge payment, and pulse-cli inspect shows that order ORD-10130 waits there because the card expired, with the expiry date among its variables](https://raw.githubusercontent.com/Miragon/pulse/main/docs/assets/cli-triage.gif)
15
+
16
+ ## Why
17
+
18
+ A language model writes its answer token by token, so the time and the cost of a task grow with
19
+ the text it has to produce. Working with a process engine through its REST API is a lot of text.
20
+ Completing a single task takes one request to find the instance, one to see where it waits, one to
21
+ act and one to check the result, and each answer has to be read to build the next request. A
22
+ deployment, a migration or a search through the history is no different. An agent that works this
23
+ way is slow, and every id it copies is a chance to hit the wrong instance.
24
+
25
+ pulse-cli turns this around: the agent names what it means and what should happen, in one short
26
+ command, and the CLI sends the requests. What you get:
27
+
28
+ - One short command replaces a chain of requests, so the agent writes little and works fast.
29
+ - Answers contain what the next step needs, not everything the engine knows.
30
+ - The CLI lists its own commands and explains each one, so an agent looks things up instead of
31
+ inventing them.
32
+ - Every change can be previewed, deleting needs an explicit yes, and an engine can be marked as
33
+ look-only, so it is safe on real engines.
34
+ - Everything the REST API offers is a command: deployments, instances, tasks, incidents,
35
+ migrations, history, decisions, users and permissions.
36
+ - It never asks questions, and both its answers and its errors are easy for a program to read, so
37
+ scripts can use it too.
38
+
39
+ ## Install
40
+
41
+ Requires Node.js 22.12+, or use Homebrew, the standalone executable or the container image (see
42
+ below).
43
+
44
+ ```sh
45
+ npm install -g @miragon/pulse-cli # or, without Node.js: brew install miragon/tap/pulse-cli
46
+ pulse-cli guide
47
+ ```
48
+
49
+ ## Quick start
50
+
51
+ Start an engine, then deploy a process, start an instance and complete its first task.
52
+ `order.bpmn` is any process with a user task; the [walk-through](https://miragon.github.io/pulse/cli/quick-start) has one.
53
+
54
+ ```sh
55
+ docker run -d --name engine -p 8080:8080 operaton/operaton:2.1.5
56
+ pulse-cli ping
57
+ pulse-cli deploy order.bpmn --start --business-key ORD-1001 --var amount=250
58
+ pulse-cli advance --business-key ORD-1001 --var approved=true
59
+ ```
60
+
61
+ ```text
62
+ Advanced review (userTask) via POST /task/74ef8d30-c652-11f1-ac07-4a8ec87eee1e/complete
63
+
64
+ Process instance 74ef661b-c652-11f1-ac07-4a8ec87eee1e
65
+ State COMPLETED
66
+ Definition order v1 (Order)
67
+ Business key ORD-1001
68
+ Started 2026-10-12T15:34:47.666+0000
69
+ Ended 2026-10-12T15:34:47.916+0000
70
+
71
+ Variables:
72
+ NAME VALUE TYPE
73
+ amount 250
74
+ approved true
75
+ ```
76
+
77
+ On a terminal the answer is a table, as above; an agent or a script gets JSON.
78
+
79
+ ## Commands
80
+
81
+ | Task | Commands |
82
+ | ------------------------------ | ------------------------------------------------------------------------ |
83
+ | Deploy processes and decisions | `deploy`, `deployment`, `process-definition`, `decision-definition` |
84
+ | Start and follow instances | `inspect`, `wait`, `process-instance`, `message`, `signal` |
85
+ | Work on tasks | `advance`, `task`, `external-task` |
86
+ | Find and fix what failed | `status`, `retry`, `incident`, `job` |
87
+ | Change running instances | `migration`, `modification`, `batch` |
88
+ | Look into the history | `historic-process-instance`, `historic-task-instance`, 13 more groups |
89
+ | Administer the engine | `user`, `group`, `tenant`, `authorization`, `metrics`, `history-cleanup` |
90
+ | Call any other REST operation | `<group> <command>`, e.g. `filter list`; `api` for raw requests |
91
+ | Ask the CLI itself | `guide`, `commands`, `describe`, `--help` |
92
+ | Set up engines and logins | `config`, `auth`, `completion`, `ping` |
93
+
94
+ The six top-level commands (`inspect`, `wait`, `advance`, `retry`, `deploy`, `status`) combine
95
+ several requests; every other command is one operation of the REST API.
96
+
97
+ Details: [workflow commands](https://miragon.github.io/pulse/cli/workflow-commands),
98
+ [command structure](https://miragon.github.io/pulse/cli/commands), [recipes](https://miragon.github.io/pulse/cli/recipes).
99
+
100
+ ## AI agents and the Claude Code plugin
101
+
102
+ Everything an agent needs is in the CLI: `pulse-cli guide` prints the usage guide, and one line in
103
+ `AGENTS.md` or `CLAUDE.md` ("Run `pulse-cli guide` before using `pulse-cli`") is enough. The CLI
104
+ is also a Claude Code plugin in the plugin marketplace of this repository, whose skill makes Claude
105
+ use the CLI whenever a task touches an engine.
106
+
107
+ ```text
108
+ /plugin marketplace add Miragon/pulse
109
+ /plugin install pulse-cli@pulse
110
+ ```
111
+
112
+ Details: [using pulse-cli from AI agents](https://miragon.github.io/pulse/cli/agents).
113
+
114
+ ## Engines
115
+
116
+ pulse-cli works with Operaton, CIB seven and Camunda 7, and is tested against all three on every
117
+ change. Camunda 8 is not supported: it has a different API.
118
+
119
+ Details: [engines](https://miragon.github.io/pulse/cli/engines).
120
+
121
+ ## Without Node.js
122
+
123
+ Every release also has a standalone executable for Linux, macOS and Windows, and a container
124
+ image, `ghcr.io/miragon/pulse-cli`.
125
+
126
+ Details: [installation](https://miragon.github.io/pulse/cli/installation).
127
+
128
+ ## Documentation
129
+
130
+ The documentation is a website, [miragon.github.io/pulse/cli](https://miragon.github.io/pulse/cli/),
131
+ built from the pages in [`docs/cli/`](https://github.com/Miragon/pulse/tree/main/docs/cli):
132
+
133
+ - [Getting started](https://miragon.github.io/pulse/cli/getting-started): a first triage, then your own engine, Claude Code or CI
134
+ - [Installation](https://miragon.github.io/pulse/cli/installation): npm, Homebrew, standalone executable, container image, shell completion
135
+ - [Quick start](https://miragon.github.io/pulse/cli/quick-start): one process from an empty engine to a finished instance
136
+ - [Workflow commands](https://miragon.github.io/pulse/cli/workflow-commands): inspect, wait, advance, retry, deploy, status
137
+ - [Command structure](https://miragon.github.io/pulse/cli/commands): names, arguments, variables, request bodies, files, dates
138
+ - [Output and errors](https://miragon.github.io/pulse/cli/output-and-errors): formats, previews, error fields, exit codes
139
+ - [Configuration](https://miragon.github.io/pulse/cli/configuration): options, environment variables, config and project files, profiles
140
+ - [Authentication](https://miragon.github.io/pulse/cli/authentication): Basic auth, OAuth logins, bearer tokens, token commands, other headers
141
+ - [Safety](https://miragon.github.io/pulse/cli/safety): previews, confirmation, read-only mode
142
+ - [Recipes](https://miragon.github.io/pulse/cli/recipes): command lines for everyday tasks
143
+ - [Using pulse-cli from AI agents](https://miragon.github.io/pulse/cli/agents): the guide, the Claude Code plugin and skill
144
+ - [Engines](https://miragon.github.io/pulse/cli/engines): compatibility, choosing the engine, adding a difference or an engine
145
+ - [Architecture](https://miragon.github.io/pulse/cli/architecture): engine port, adapters, catalog generation; [decisions](https://miragon.github.io/pulse/cli/adr/)
146
+ - [Development](https://github.com/Miragon/pulse/blob/main/docs/cli/development.md): building and testing the CLI in the Pulse repository
147
+
148
+ ## Renamed from operate
149
+
150
+ Up to 0.10.0 this CLI was `@miragon/operate` with the command `operate`, released from
151
+ [Miragon/operate](https://github.com/Miragon/operate), which keeps its history and changelog.
152
+ Each old name has one new name:
153
+
154
+ - npm: `@miragon/operate` becomes `@miragon/pulse-cli` (command `pulse-cli`). The old package is
155
+ deprecated; it stays installable and keeps its own `operate`.
156
+ - Homebrew: `miragon/tap/operate` becomes `miragon/tap/pulse-cli`; `brew upgrade` switches, and
157
+ the formula keeps `operate` as an alias until the first release after 2027-01-31.
158
+ - Image: `ghcr.io/miragon/operate` becomes `ghcr.io/miragon/pulse-cli`.
159
+ - Variables: `OPERATE_URL`, `OPERATE_TOKEN` and the rest become `PULSE_CLI_URL`,
160
+ `PULSE_CLI_TOKEN` and so on.
161
+ - Files: the project file `.operate.json` becomes `.pulse-cli.json`, the config directory
162
+ `~/.config/operate` (Windows: `%APPDATA%\operate`) becomes `~/.config/pulse-cli`.
163
+
164
+ pulse-cli still reads the old variables and files, with one warning per run, until the first
165
+ release after 2027-01-31: [how](https://miragon.github.io/pulse/cli/installation#renamed-from-operate).
166
+
167
+ ## Contributing
168
+
169
+ See the [development guide](https://github.com/Miragon/pulse/blob/main/docs/cli/development.md).
170
+ Bugs and ideas go to the [issues](https://github.com/Miragon/pulse/issues).
171
+
172
+ ## License
173
+
174
+ [MIT](LICENSE) © Miragon GmbH