Skip to content

Commit 8b21de3

Browse files
Copilotvobu
Copilot
and
vobu
authored
chore: add detailed help commands and streamline documentation (#35)
* Initial plan * feat: add detailed help commands for list, get, create, and complete - Add showCommandHelp function to display resource-specific flags - Support 'c8ctl help <command>' syntax (e.g., 'c8ctl help list') - Add detailed help for list command showing all resources and their flags - Add detailed help for get, create, and complete commands - Add unit tests for new help functionality Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * docs: improve README with concise examples and help references - Add "Getting Help" section highlighting new detailed help commands - Make "Basic Commands" section more concise - Add reference to EXAMPLES.md for comprehensive examples - Update "Command Structure" with complete verb list - Add tip about using 'c8ctl help <command>' for detailed help - Update main help output to show 'help [command]' syntax Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * feat: update shell completion for new help commands and sync verb - Add completion for 'c8ctl help <command>' to show available commands - Add 'sync' verb to bash, zsh, and fish completions - Add process-definition (pd) resource to get command completions - Update help command descriptions in all shells - Add help resources completion for bash, zsh, and fish Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * fix: limit help command completion to implemented commands only - Reduce help_resources to only list, get, create, complete - Remove unimplemented help commands from shell completion - Align completion suggestions with actual functionality Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * docs: clarify help command supports only list, get, create, complete - Update help output to explicitly state which commands have detailed help - Set accurate user expectations about available detailed help Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>
1 parent 179eed3 commit 8b21de3

File tree

6 files changed

+333
-51
lines changed

6 files changed

+333
-51
lines changed

‎README.md‎

Lines changed: 51 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -64,56 +64,44 @@ After installation, the CLI is available as `c8ctl` (or its alias `c8`).
6464

6565
## Usage
6666

67-
### Basic Commands
67+
### Getting Help
6868

6969
```bash
70-
# Show help
70+
# Show general help
7171
c8ctl help
7272

73+
# Show detailed help for specific commands with all flags
74+
c8ctl help list # Shows all list resources and their flags
75+
c8ctl help get # Shows all get resources and their flags
76+
c8ctl help create # Shows all create resources and their flags
77+
c8ctl help complete # Shows all complete resources and their flags
78+
7379
# Show version
7480
c8ctl --version
81+
```
7582

76-
# List process instances (using alias 'pi')
77-
c8ctl list pi
78-
# Or using full command name
79-
c8ctl list process-instances
80-
81-
# List process definitions (using alias 'pd')
82-
c8ctl list pd
83-
c8ctl list process-definitions
84-
85-
# Get process instance by key
86-
c8ctl get pi 123456
87-
c8ctl get process-instance 123456
88-
89-
# Get process definition by key
90-
c8ctl get pd 123456
91-
c8ctl get process-definition 123456
83+
### Basic Commands
9284

93-
# Get process definition XML
94-
c8ctl get pd 123456 --xml
85+
```bash
86+
# List and get resources (use aliases pi, pd, ut, inc for convenience)
87+
c8ctl list pi # List process instances
88+
c8ctl list pd # List process definitions
89+
c8ctl get pi 123456 # Get process instance by key
90+
c8ctl get pd 123456 --xml # Get process definition as XML
9591

96-
# Create process instance
92+
# Create and manage process instances
9793
c8ctl create pi --bpmnProcessId=myProcess
98-
c8ctl create process-instance --bpmnProcessId=myProcess
99-
100-
# Deploy BPMN file
101-
c8ctl deploy ./my-process.bpmn
102-
103-
# Deploy current directory
104-
c8ctl deploy
105-
106-
# Deploy from multiple paths
107-
c8ctl deploy ./processes ./forms ./building-blocks
94+
c8ctl cancel pi 123456
10895

109-
# Watch mode (using alias 'w')
110-
c8ctl w
111-
c8ctl watch
112-
113-
# Deploy and start process (run)
114-
c8ctl run ./my-process.bpmn
96+
# Deploy and run
97+
c8ctl deploy ./my-process.bpmn # Deploy a single file
98+
c8ctl deploy # Deploy current directory
99+
c8ctl run ./my-process.bpmn # Deploy and start process
100+
c8ctl watch # Watch for changes and auto-deploy
115101
```
116102

103+
For comprehensive examples of all commands and their flags, see [EXAMPLES.md](EXAMPLES.md).
104+
117105
### Shell Completion
118106

119107
c8ctl supports shell completion for `bash`, `zsh`, and `fish`. To enable completion:
@@ -358,9 +346,32 @@ When plugins are loaded, their commands automatically appear in `c8ctl help` out
358346
c8ctl <verb> <resource> [arguments] [flags]
359347
```
360348

361-
**Verbs**: list, get, create, cancel, complete, fail, activate, resolve, publish, correlate, deploy, run, add, remove, use, output
362-
363-
**Resources**: process-instance, process-definition, user-task, incident, job, message, topology, profile, tenant
349+
**Verbs**:
350+
- `list` - List resources
351+
- `get` - Get resource by key
352+
- `create` - Create resource
353+
- `cancel` - Cancel resource
354+
- `complete` - Complete resource
355+
- `fail` - Fail a job
356+
- `activate` - Activate jobs
357+
- `resolve` - Resolve incident
358+
- `publish` - Publish message
359+
- `correlate` - Correlate message
360+
- `deploy` - Deploy BPMN/DMN/forms
361+
- `run` - Deploy and start process
362+
- `watch` (alias: `w`) - Watch for changes and auto-deploy
363+
- `add` - Add a profile
364+
- `remove` (alias: `rm`) - Remove a profile
365+
- `load` - Load a plugin
366+
- `unload` - Unload a plugin
367+
- `sync` - Synchronize plugins
368+
- `use` - Set active profile or tenant
369+
- `output` - Set output format
370+
- `completion` - Generate shell completion script
371+
372+
**Resources**: process-instance (pi), process-definition (pd), user-task (ut), incident (inc), job, jobs, message (msg), topology, profile, tenant, plugin
373+
374+
**Tip**: Run `c8ctl help <command>` to see detailed help for specific commands with all available flags.
364375

365376
## Testing
366377

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/commands/completion.ts‎

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,11 @@ _c8ctl_completions() {
2020
cword=\${COMP_CWORD}
2121
2222
# Commands (verbs)
23-
local verbs="list get create cancel complete fail activate resolve publish correlate deploy run watch add remove rm load unload use output completion help"
23+
local verbs="list get create cancel complete fail activate resolve publish correlate deploy run watch add remove rm load unload sync use output completion help"
2424
2525
# Resources by verb
2626
local list_resources="process-instances process-instance pi user-tasks user-task ut incidents incident inc jobs profiles profile plugins plugin"
27-
local get_resources="process-instance pi topology"
27+
local get_resources="process-instance pi process-definition pd topology"
2828
local create_resources="process-instance pi"
2929
local cancel_resources="process-instance pi"
3030
local complete_resources="user-task ut job"
@@ -37,9 +37,11 @@ _c8ctl_completions() {
3737
local remove_resources="profile"
3838
local load_resources="plugin"
3939
local unload_resources="plugin"
40+
local sync_resources="plugin plugins"
4041
local use_resources="profile tenant"
4142
local output_resources="json text"
4243
local completion_resources="bash zsh fish"
44+
local help_resources="list get create complete"
4345
4446
# Global flags
4547
local flags="--help --version --profile --from --all --bpmnProcessId --processInstanceKey --variables --state --assignee --type --correlationKey --timeToLive --maxJobsToActivate --timeout --worker --retries --errorMessage --baseUrl --clientId --clientSecret --audience --oAuthUrl --defaultTenantId --version_num"
@@ -95,6 +97,9 @@ _c8ctl_completions() {
9597
unload)
9698
COMPREPLY=( \$(compgen -W "\${unload_resources}" -- "\${cur}") )
9799
;;
100+
sync)
101+
COMPREPLY=( \$(compgen -W "\${sync_resources}" -- "\${cur}") )
102+
;;
98103
use)
99104
COMPREPLY=( \$(compgen -W "\${use_resources}" -- "\${cur}") )
100105
;;
@@ -104,6 +109,9 @@ _c8ctl_completions() {
104109
completion)
105110
COMPREPLY=( \$(compgen -W "\${completion_resources}" -- "\${cur}") )
106111
;;
112+
help)
113+
COMPREPLY=( \$(compgen -W "\${help_resources}" -- "\${cur}") )
114+
;;
107115
deploy|run|watch)
108116
# Complete with files
109117
COMPREPLY=( \$(compgen -f -- "\${cur}") )
@@ -154,10 +162,11 @@ _c8ctl() {
154162
'rm:Remove a profile'
155163
'load:Load a c8ctl plugin'
156164
'unload:Unload a c8ctl plugin'
165+
'sync:Synchronize plugins from registry'
157166
'use:Set active profile or tenant'
158167
'output:Set output format'
159168
'completion:Generate shell completion script'
160-
'help:Show help'
169+
'help:Show help or detailed help for a command'
161170
)
162171
163172
flags=(
@@ -219,6 +228,8 @@ _c8ctl() {
219228
resources=(
220229
'process-instance:Get process instance'
221230
'pi:Get process instance'
231+
'process-definition:Get process definition'
232+
'pd:Get process definition'
222233
'topology:Get cluster topology'
223234
)
224235
_describe 'resource' resources
@@ -302,6 +313,13 @@ _c8ctl() {
302313
)
303314
_describe 'resource' resources
304315
;;
316+
sync)
317+
resources=(
318+
'plugin:Synchronize plugin'
319+
'plugins:Synchronize plugins'
320+
)
321+
_describe 'resource' resources
322+
;;
305323
use)
306324
resources=(
307325
'profile:Set active profile'
@@ -324,6 +342,15 @@ _c8ctl() {
324342
)
325343
_describe 'resource' resources
326344
;;
345+
help)
346+
resources=(
347+
'list:Show list command help'
348+
'get:Show get command help'
349+
'create:Show create command help'
350+
'complete:Show complete command help'
351+
)
352+
_describe 'resource' resources
353+
;;
327354
deploy|run|watch)
328355
_files
329356
;;
@@ -438,12 +465,14 @@ complete -c c8ctl -n '__fish_use_subcommand' -a 'load' -d 'Load a c8ctl plugin'
438465
complete -c c8 -n '__fish_use_subcommand' -a 'load' -d 'Load a c8ctl plugin'
439466
complete -c c8ctl -n '__fish_use_subcommand' -a 'unload' -d 'Unload a c8ctl plugin'
440467
complete -c c8 -n '__fish_use_subcommand' -a 'unload' -d 'Unload a c8ctl plugin'
468+
complete -c c8ctl -n '__fish_use_subcommand' -a 'sync' -d 'Synchronize plugins from registry'
469+
complete -c c8 -n '__fish_use_subcommand' -a 'sync' -d 'Synchronize plugins from registry'
441470
complete -c c8ctl -n '__fish_use_subcommand' -a 'use' -d 'Set active profile or tenant'
442471
complete -c c8 -n '__fish_use_subcommand' -a 'use' -d 'Set active profile or tenant'
443472
complete -c c8ctl -n '__fish_use_subcommand' -a 'output' -d 'Set output format'
444473
complete -c c8 -n '__fish_use_subcommand' -a 'output' -d 'Set output format'
445-
complete -c c8ctl -n '__fish_use_subcommand' -a 'help' -d 'Show help'
446-
complete -c c8 -n '__fish_use_subcommand' -a 'help' -d 'Show help'
474+
complete -c c8ctl -n '__fish_use_subcommand' -a 'help' -d 'Show help or detailed help for a command'
475+
complete -c c8 -n '__fish_use_subcommand' -a 'help' -d 'Show help or detailed help for a command'
447476
complete -c c8ctl -n '__fish_use_subcommand' -a 'completion' -d 'Generate shell completion script'
448477
complete -c c8 -n '__fish_use_subcommand' -a 'completion' -d 'Generate shell completion script'
449478
@@ -482,6 +511,10 @@ complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'process-instance' -d
482511
complete -c c8 -n '__fish_seen_subcommand_from get' -a 'process-instance' -d 'Get process instance'
483512
complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'pi' -d 'Get process instance'
484513
complete -c c8 -n '__fish_seen_subcommand_from get' -a 'pi' -d 'Get process instance'
514+
complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'process-definition' -d 'Get process definition'
515+
complete -c c8 -n '__fish_seen_subcommand_from get' -a 'process-definition' -d 'Get process definition'
516+
complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'pd' -d 'Get process definition'
517+
complete -c c8 -n '__fish_seen_subcommand_from get' -a 'pd' -d 'Get process definition'
485518
complete -c c8ctl -n '__fish_seen_subcommand_from get' -a 'topology' -d 'Get cluster topology'
486519
complete -c c8 -n '__fish_seen_subcommand_from get' -a 'topology' -d 'Get cluster topology'
487520
@@ -549,6 +582,12 @@ complete -c c8 -n '__fish_seen_subcommand_from load' -a 'plugin' -d 'Load plugin
549582
complete -c c8ctl -n '__fish_seen_subcommand_from unload' -a 'plugin' -d 'Unload plugin'
550583
complete -c c8 -n '__fish_seen_subcommand_from unload' -a 'plugin' -d 'Unload plugin'
551584
585+
# Resources for 'sync' command
586+
complete -c c8ctl -n '__fish_seen_subcommand_from sync' -a 'plugin' -d 'Synchronize plugin'
587+
complete -c c8 -n '__fish_seen_subcommand_from sync' -a 'plugin' -d 'Synchronize plugin'
588+
complete -c c8ctl -n '__fish_seen_subcommand_from sync' -a 'plugins' -d 'Synchronize plugins'
589+
complete -c c8 -n '__fish_seen_subcommand_from sync' -a 'plugins' -d 'Synchronize plugins'
590+
552591
# Resources for 'use' command
553592
complete -c c8ctl -n '__fish_seen_subcommand_from use' -a 'profile' -d 'Set active profile'
554593
complete -c c8 -n '__fish_seen_subcommand_from use' -a 'profile' -d 'Set active profile'
@@ -568,6 +607,16 @@ complete -c c8ctl -n '__fish_seen_subcommand_from completion' -a 'zsh' -d 'Gener
568607
complete -c c8 -n '__fish_seen_subcommand_from completion' -a 'zsh' -d 'Generate zsh completion'
569608
complete -c c8ctl -n '__fish_seen_subcommand_from completion' -a 'fish' -d 'Generate fish completion'
570609
complete -c c8 -n '__fish_seen_subcommand_from completion' -a 'fish' -d 'Generate fish completion'
610+
611+
# Resources for 'help' command
612+
complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'list' -d 'Show list command help'
613+
complete -c c8 -n '__fish_seen_subcommand_from help' -a 'list' -d 'Show list command help'
614+
complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'get' -d 'Show get command help'
615+
complete -c c8 -n '__fish_seen_subcommand_from help' -a 'get' -d 'Show get command help'
616+
complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'create' -d 'Show create command help'
617+
complete -c c8 -n '__fish_seen_subcommand_from help' -a 'create' -d 'Show create command help'
618+
complete -c c8ctl -n '__fish_seen_subcommand_from help' -a 'complete' -d 'Show complete command help'
619+
complete -c c8 -n '__fish_seen_subcommand_from help' -a 'complete' -d 'Show complete command help'
571620
`;
572621
}
573622

0 commit comments

Comments
 (0)