DOCSEARCHbyAlgolia
Submit Docs

carapace

repository·master·Indexed 23 days ago

https://github.com/carapace-sh/carapace

A command argument completion generator for cobra-based CLI applications. It enables advanced shell completion capabilities across various environments, including Bash, Elvish, Fish, Nushell, Oil, PowerShell, Tcsh, Xonsh, and Zsh. The library provides a fluent API for defining completion actions, handling multi-part completions, caching results, and generating shell-specific completion snippets.

Tokens
243.4K
Snippets
584
Records
1.1K
Agent score
77%

What's inside carapace

  1. Overview of Elvish Shell internals and references

    master

    This skill provides a comprehensive reference for the Elvish shell internals. It is intended for developers working with Elvish's completion system, editor API, styling, language fundamentals, and configuration.

    Key areas covered include:

    • Completion System: Writing arg-completer functions, using edit:complex-candidate, configuring matchers, and understanding the completion pipeline.
    • Editor API: Managing modes (insert, command, navigation, history), configuring keybindings, customizing prompts (prompt and rprompt), and using editor hooks.
    • Styling: Using styled text, applying style transformers (ANSI, XTerm 256-color, TrueColor), and managing foreground/background colors.
    • Language Fundamentals: Working with value types (lists, maps, etc.), pipelines, namespaces, modules, and scoping.
    • Configuration: Setting up rc.elv, managing the module system, and understanding the startup order and environment variables.

    For specific integration with carapace (such as snippet generation, value formatting, or JSON output), refer to the carapace-dev skill in references/shell-elvish.md.

  3. Overview of carapace

    master

    carapace is a command argument completion generator designed specifically for use with cobra. It generates shell completion scripts for a wide variety of shells, allowing CLI tools built with cobra to provide rich, interactive argument completion.

    Supported shells include:

    • Bash
    • Cmd (experimental)
    • Elvish
    • Fish
    • Ion (experimental)
    • Nushell
    • Oil
    • Powershell
    • Tcsh (experimental)
    • Xonsh
    • Zsh

  4. Access Bash shell in-depth references

    master

    The bash skill provides specialized references for working with Bash shell internals. Depending on your task, you should load the specific sub-resource that matches your needs. If you are unsure, loading multiple references is recommended.

    Available reference categories:

    • Completion System: For writing completion functions, using complete, compgen, compopt, or understanding COMP_* variables and bash-completion helpers.
    • Readline & Input: For configuring .inputrc, key bindings (bind), editing modes (emacs/vi), and completion display behavior.
    • Quoting & Expansion: For understanding how quoting (single, double, ANSI-C), word splitting, IFS, and various expansions (globbing, brace, parameter, command, etc.) affect shell behavior.
    • Execution & Signals: For understanding subshells, pipelines, job control, signals (SIGINT, SIGHUP), traps (DEBUG, EXIT, ERR, RETURN), and prompt hooks (PROMPT_COMMAND).
    • Startup & Environment: For managing shell initialization via .bashrc, .bash_profile, /etc/profile, and understanding the differences between login, interactive, and non-interactive shells.

  5. Explore related Carapace shell integration concepts

    master

    For a deeper understanding of how Carapace interacts with different shells and its internal mechanics, refer to the following documentation topics:

    • Cross-shell feature comparison: See references/shell.md to understand how features are shared across different shells and how the shared dispatch mechanism works.
    • Completion engine internals: See references/traverse.md to learn how the engine produces Actions before they are formatted for the shell.
    • Styling and SGR sequences: See references/style.md to understand how styles are resolved and converted into shell-specific SGR sequences.
    • User-facing setup: For instructions on setting up shell integration via the binary, refer to the carapace-bin repository.

  6. Explore Ion Shell internals and references

    master

    The Ion shell documentation is organized into several specialized sub-resources depending on your development or configuration task. Use the following guide to locate the correct reference:

    • Completion System: For working with IonCompleter, IonFileCompleter, MultiCompleter, the Completer trait, CompletionType, CursorPosition, BeforeComplete events, and carapace integration.
    • Line Editing: For details on the Liner library (redox_liner), Editor context, KeyMap, KeyBindings (vi/emacs modes), autosuggestion, history, and the complete() or read_line() methods.
    • Language Syntax: For information on ion syntax, variables, sigils ($, @), type systems, string/array methods, quoting rules, brace expansion, and redirection (^>, ^|, &>, &|).
    • Execution Model: For understanding subshells, background jobs (fg, bg, jobs), signals, exit statuses, and job control.
    • Startup and Configuration: For managing initrc, XDG_CONFIG_HOME, startup files, keybindings, PROMPT hooks, aliases, and ion-plugins.

  7. Access Zsh Shell In-Depth Reference

    master

    The Zsh skill provides a comprehensive reference for Zsh shell internals. Depending on your task, you should load specific sub-resources to avoid overwhelming the context.

    Key areas covered include:

    • Completion System (compsys): Functions like compinit, compdef, _arguments, _describe, zstyle, and the tag system.
    • ZLE (Zsh Line Editor): Widgets, keymaps, bindkey, compstate, and buffer manipulation (LBUFFER, RBUFFER).
    • Expansion and Quoting: Parameter expansion, globbing, quoting rules, and brace expansion.
    • Startup and Configuration: Startup files (.zshrc, .zshenv), fpath, autoload, and compinit security.
    • Completion Capture: Using zpty or other methods to capture completions externally (e.g., for bridge tools).

  8. Understand Carapace per-shell output formatting

    master

    Carapace provides shell-specific completion output for 11 supported shells. Each shell package implements a Snippet(cmd *cobra.Command) string function that generates the integration script. This script registers the command, sets up the callback to invoke carapace, and handles retry logic for open-quote scenarios (e.g., appending '', ', or ").

    Supported Shells:

    • Bash: bash
    • Bash BLE: bash-ble
    • Oil: oil
    • Cmd (Clink): cmd-clink
    • Elvish: elvish
    • Fish: fish
    • Ion: ion
    • Nushell: nushell
    • PowerShell: powershell
    • Tcsh: tcsh
    • Xonsh: xonsh
    • Zsh: zsh

    Note: The export format is not a shell; it is a raw JSON output format used for bridging, embedding, and caching completions.

  9. Navigate the Bash BLE (ble.sh) Reference

    master

    The bash-ble skill provides a comprehensive reference for ble.sh internals. Use the following sub-resources to find information based on your specific task:

    • Completion System: For writing completion functions, understanding ble/complete, cand/yield, menu styles, menu-filter, and integration with bash programmable completion.
    • Syntax Highlighting: For configuring syntax parsers, ble-face, colors, and specific syntax types (e.g., syntax_command, syntax_varname).
    • Editor & Keybindings: For managing widgets, keymaps (ble-bind), Emacs/Vi modes, undo/redo, and terminal rendering.
    • Startup & Configuration: For installation, blerc configuration, bleopt settings, blehook usage, and ble-import.

  10. Use the PowerShell skill in carapace

    master

    The powershell skill is designed for working with PowerShell internals. It provides specialized knowledge for tasks involving tab completion, Register-ArgumentCompleter, PSReadLine, CompletionResult, CommandAst, argument passing to native commands, quoting rules, $PSStyle ANSI rendering, profiles/configuration, and the prediction plugin system.

    This skill is automatically triggered by carapace when it detects keywords such as:

    • powershell or pwsh
    • Register-ArgumentCompleter
    • PSReadLine
    • CompletionResult
    • CommandAst
    • TabExpansion2
    • MenuComplete
    • ArgumentCompleter
    • PSStyle
    • powershell profile
    • powershell completion
    • powershell quoting
    • powershell argument passing
    • IPredictor
    • predictive intellisense

  11. Use the Carapace Development Reference

    master

    The carapace-dev skill is intended for developers or AI agents working on the internal implementation of the carapace library. It provides deep technical details on the following core components:

    • Action API: Action types, modifiers, InvokedAction, Context, callbacks, and batching.
    • Traverse Engine: Argument classification, completion engine logic, pflagfork, and complete() dispatch.
    • Pflag Extensions: Handling non-POSIX flags, Nargs, ArgumentStyle, and custom flag prefixes.
    • Shell Formats: Detailed implementation details for specific shells (Bash, Zsh, Fish, Elvish, Nushell, PowerShell, Xonsh, Oil, etc.).
    • Internal Systems: Style system, Bridge, Global Storage, Sandbox, Batching, Caching, UID identifiers, and the Mock system.
    • Configuration & Export: styles.json loading, environment variables, and the JSON wire format for exports.

  12. Access Fish Shell In-Depth Reference

    master

    This skill provides a comprehensive reference for fish shell internals. Depending on your task, you should load specific sub-resources to get detailed information on completions, editor behavior, language fundamentals, execution, or startup configuration. If you are unsure which one to use, loading multiple references is recommended.

    Available Reference Categories

    • Completion System: Covers complete builtin, commandline builtin, completion functions, autoloading, wrapping, and completion output formats (e.g., NO_SPACE, REPLACES_TOKEN).
    • Editor & UI: Covers key bindings (bind), editing modes (emacs, vi), autosuggestions, syntax highlighting, abbreviations (abbr), and the pager.
    • Language Fundamentals: Covers quoting, variable expansion, scoping (global, local, universal), lists/arrays, control flow (if, switch, for), and builtins like string, math, and argparse.
    • Execution & Job Control: Covers pipelines, process groups, job lifecycle (fg, bg, jobs), signals (SIGINT, SIGHUP), and internal process types.
    • Startup & Configuration: Covers config.fish, conf.d, XDG directory paths, startup order, and environment variables.