@camunda8/cli 2.6.0-alpha.1 → 2.6.0-alpha.2
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.
- package/CONTEXT.md +124 -0
- package/EXAMPLES.md +1097 -0
- package/PLUGIN-HELP.md +333 -0
- package/README.md +7 -25
- package/dist/commands/watch.d.ts +1 -0
- package/dist/commands/watch.d.ts.map +1 -1
- package/dist/commands/watch.js +32 -21
- package/dist/commands/watch.js.map +1 -1
- package/package.json +5 -2
package/CONTEXT.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# c8ctl Agent Context
|
|
2
|
+
|
|
3
|
+
This file encodes invariants and conventions for AI agents consuming c8ctl
|
|
4
|
+
programmatically. See README.md for general usage.
|
|
5
|
+
|
|
6
|
+
## Quick Setup
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
c8ctl output json # switch to machine-readable output (session-persistent)
|
|
10
|
+
c8ctl help # get structured JSON command reference
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Authentication & Profiles
|
|
14
|
+
|
|
15
|
+
- Config lives in `~/.config/c8ctl/` (or `$C8CTL_DATA_DIR` override)
|
|
16
|
+
- Set active profile: `c8ctl use profile <name>`
|
|
17
|
+
- One-off override: append `--profile <name>` to any command
|
|
18
|
+
- Modeler profiles: use `modeler:` prefix, e.g. `--profile=modeler:Local Dev`
|
|
19
|
+
- Show active profile: `c8ctl which profile`
|
|
20
|
+
- Add profile: `c8ctl add profile <name> --baseUrl=<url>`
|
|
21
|
+
|
|
22
|
+
## Output Mode
|
|
23
|
+
|
|
24
|
+
- Output mode is session-global, not per-command
|
|
25
|
+
- `c8ctl output json` → all subsequent commands emit JSON to stdout
|
|
26
|
+
- `c8ctl output text` → human-readable table output
|
|
27
|
+
- In JSON mode: operational messages (info/warn/success/error) go to **stderr**;
|
|
28
|
+
data output goes to **stdout**
|
|
29
|
+
- Exit code 1 + JSON error on stderr on failure
|
|
30
|
+
|
|
31
|
+
## Resource Aliases
|
|
32
|
+
|
|
33
|
+
| Alias | Full Name |
|
|
34
|
+
|-------|----------------------|
|
|
35
|
+
| `pi` | process-instance(s) |
|
|
36
|
+
| `pd` | process-definition(s)|
|
|
37
|
+
| `ut` | user-task(s) |
|
|
38
|
+
| `inc` | incident(s) |
|
|
39
|
+
| `msg` | message |
|
|
40
|
+
| `vars`| variable(s) |
|
|
41
|
+
|
|
42
|
+
## Agent Flags
|
|
43
|
+
|
|
44
|
+
These flags exist specifically for agent/programmatic use. They are listed
|
|
45
|
+
separately in help output and are distinct from human-use flags.
|
|
46
|
+
|
|
47
|
+
### `--fields <comma-separated>`
|
|
48
|
+
|
|
49
|
+
Filters output to only the specified keys. Applies to all `list`, `search`,
|
|
50
|
+
and `get` commands at the logger level — works in both text and JSON mode.
|
|
51
|
+
Field matching is **case-insensitive**.
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
c8ctl list pi --fields Key,State,processDefinitionId
|
|
55
|
+
c8ctl search pd --fields Key,processDefinitionId,name | jq .
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Use this to reduce context window size when parsing output programmatically.
|
|
59
|
+
|
|
60
|
+
### `--dry-run`
|
|
61
|
+
|
|
62
|
+
Applies to all **mutating** commands: `create`, `cancel`, `deploy`,
|
|
63
|
+
`complete`, `fail`, `activate`, `resolve`, `publish`, `correlate`.
|
|
64
|
+
|
|
65
|
+
In dry-run mode:
|
|
66
|
+
- All inputs are validated
|
|
67
|
+
- The target profile/client is resolved
|
|
68
|
+
- The equivalent API request is emitted as JSON to stdout:
|
|
69
|
+
`{ "dryRun": true, "command": "...", "method": "POST", "url": "...", "body": {...} }`
|
|
70
|
+
- The actual API call is **not** executed
|
|
71
|
+
- Exits 0
|
|
72
|
+
|
|
73
|
+
**Recommended workflow for mutating operations:**
|
|
74
|
+
1. Run the command with `--dry-run` and inspect the JSON output
|
|
75
|
+
2. Confirm the request with the user (or validate programmatically)
|
|
76
|
+
3. Re-run without `--dry-run` to execute
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
c8ctl create pi --id=my-process --dry-run
|
|
80
|
+
c8ctl deploy ./my-process.bpmn --dry-run
|
|
81
|
+
c8ctl cancel pi 2251799813685249 --dry-run
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## JSON Mode Help
|
|
85
|
+
|
|
86
|
+
In JSON output mode, help commands return structured data instead of text:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
c8ctl output json
|
|
90
|
+
c8ctl help # returns full command tree as JSON
|
|
91
|
+
c8ctl help list # returns list command details as JSON
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The JSON help structure contains: `commands`, `globalFlags`, `searchFlags`,
|
|
95
|
+
`agentFlags`, `resourceAliases`.
|
|
96
|
+
|
|
97
|
+
## MCP Proxy
|
|
98
|
+
|
|
99
|
+
An MCP (Model Context Protocol) proxy is available:
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
c8ctl mcp-proxy # start STDIO→HTTP MCP proxy (default endpoint)
|
|
103
|
+
c8ctl mcp-proxy <mcp-path> # custom MCP server path
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Use `c8ctl help mcp-proxy` for full setup and configuration details.
|
|
107
|
+
|
|
108
|
+
## Pagination & Limits
|
|
109
|
+
|
|
110
|
+
- Default: fetches up to 1,000,000 results (all pages)
|
|
111
|
+
- Use `--limit <n>` to cap results
|
|
112
|
+
- Use `--fields` together with `--limit` to minimize payload size
|
|
113
|
+
|
|
114
|
+
## Error Handling
|
|
115
|
+
|
|
116
|
+
- In JSON mode, errors emit `{"status":"error","message":"..."}` to stderr
|
|
117
|
+
- Exit code 1 on error, 0 on success (including `--dry-run`)
|
|
118
|
+
- Warnings emit `{"status":"warning","message":"..."}` to stderr
|
|
119
|
+
|
|
120
|
+
## Notes for Plugin Development
|
|
121
|
+
|
|
122
|
+
This file is for **agent consumption of c8ctl** as a CLI tool.
|
|
123
|
+
For **developing c8ctl plugins**, see `PLUGIN-HELP.md` and the plugin
|
|
124
|
+
template at `src/templates/AGENTS.md`.
|