An oclif plugin to generate a carapace spec!
carapace-spec allows to define CLI completions in a spec file, you can use it to get shell completion in all supported shells listed here:
https://carapace-sh.github.io/carapace-spec/carapace-spec/usage.html
- Commands
- Flags
- Options
- Exclusive relationships
- Re-generate spec automatically on plugin install/uninstall
- Completion overrides (see
Macrossection below)
carapace-spec: dowload the binary for your OS and put it in yourPATH- oclif CLI that supports installing plugins via
plugins install
<CLI> plugins install @cristiand391/oclif-carapace-spec-pluginThen run the carapace-gen command and follow the instructions to source the spec in your shell.
carapace-spec allows to use macros for customizing completion style and values:
https://carapace-sh.github.io/carapace-spec/carapace-spec/macros.html
You can use macros to define custom flag completion logic for dynamic flag values that can't be hard-coded in CLIs like usernames, IDs, etc.
Macros file example for the Salesforce CLI:
# this node applies to all commands, define here completion logic for flags that repeat themselves in multiple commands.
persistentFlagsCompletion:
target-org: ["$(sf org list auth --json | jq -r '.result[].username')"]
target-dev-hub: ["$(sf org list auth --json | jq -r '.result[] | select(.isDevHub) | .username')"]
definition-file: ["$files([.json])"]
manifest: ["$files([.xml])"]
file: ["$files"]
# override flag completion for specific commands.
# important: command ids need to separated by colons.
commandOverrides:
flags:
'project:deploy:start':
pre-destructive-changes: ["$files([.xml])"]
post-destructive-changes: ["$files([.xml])"]
'org:delete:scratch':
target-org: ["$(sf org list auth --json | jq -r '.result[] | select(.isScratchOrg) | .username')"]
'org:delete:sandbox':
target-org: ["$(sf org list auth --json | jq -r '.result[] | select(.isSandbox) | .username')"]
It uses the exec macro for --target-org and --target-dev-hub flags to get completion values from a command, and the files macro for XML/JSON file completion on specific flags.
- Define a YAML file with completion definitions like in the example above.
- Set the
<CLI>_CARAPACE_SPEC_MACROS_FILEenv var to the path to the YAML file. - Run
<CLI> carapace-gen --refresh-cache.
Note
The <CLI> part in the env var in step 2 refers to the executable name of your oclif CLI. For instance, for the Salesforce CLI (sf) the env var should be SF_CARAPACE_SPEC_MACROS_FILE.
Note
This plugin re-generates the carapace spec everytime you install/uninstall plugins via plugins install/uninstall, make sure to set the <CLI>_CARAPACE_SPEC_MACROS_FILE env var in your shell RC file so that you don't miss the custom completions when the automatic re-generation happens under the hood.