oclif-carapace-spec-plugin

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

Supported features

• Commands
• Flags
  • Options
  • Exclusive relationships
• Re-generate spec automatically on plugin install/uninstall
• Completion overrides (see Macros section below)

Requirements

• carapace-spec: dowload the binary for your OS and put it in your PATH
• oclif CLI that supports installing plugins via plugins install

Install

plugins install @cristiand391/oclif-carapace-spec-plugin

Then run the carapace-gen command and follow the instructions to source the spec in your shell.

Macros

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.

Usage

1. Define a YAML file with completion definitions like in the example above.
2. Set the <BIN>_CARAPACE_SPEC_MACROS_FILE env var to the path to the YAML file.
3. Run sf carapace-gen --refresh-cache.

Note

The <BIN> part in the env var in step 2 refers to the 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 <BIN>_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.

Why should I use this instead of @oclif/plugin-autocomplete?

@oclif/plugin-autocomplete only supports bash, zsh and powershell while carapace-spec supports those + 6 additional shells: https://carapace-sh.github.io/carapace-spec/carapace-spec/usage.html

Except for flag exclusive relationships and completion overrides (macros), the completion experience is pretty much the same so if oclif/plugin-autocomplete works for you then you can ignore this.