carapace-bin

carapace-bin is a multi-shell multi-command argument completer based on carapace-sh/carapace.

Supported shells:

Installation

Manually

Download from releases and add carapace to PATH.

AUR

Install carapace-bin from AUR.

# e.g. with pamac
pamac install carapace-bin

DEB

Install from fury.io

# /etc/apt/sources.list.d/fury.list
deb [trusted=yes] https://apt.fury.io/rsteube/ /

apt-get update && apt-get install carapace-bin

Homebrew

Install from rsteube/homebrew-tap

brew tap rsteube/homebrew-tap
brew install rsteube/tap/carapace

Nix

Install from nixpkgs

nix-shell -p carapace

RPM

Install from fury.io

# /etc/yum.repos.d/fury.repo
[fury]
name=Gemfury Private Repo
baseurl=https://yum.fury.io/rsteube/
enabled=1
gpgcheck=0

yum install carapace-bin

Scoop

Install from ScoopInstaller/Extras (recommended)

scoop bucket add extras
scoop install extras/carapace-bin

Install from rsteube/scoop-bucket

scoop bucket add rsteube https://github.com/rsteube/scoop-bucket.git
scoop install carapace-bin

Winget

Install from winget-pkgs

winget install -e --id rsteube.Carapace

Setup

This registers all the available completers. It is also possible to load a single one by replacing _carapace with the completer name (e.g. carapace chmod).

Bash

# ~/.bashrc
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
source <(carapace _carapace)

Elvish

# ~/.config/elvish/rc.elv
set-env CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense' # optional
eval (carapace _carapace|slurp)

Fish

# ~/.config/fish/config.fish
set -Ux CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense' # optional
mkdir -p ~/.config/fish/completions
carapace --list | awk '{print $1}' | xargs -I{} touch ~/.config/fish/completions/{}.fish # disable auto-loaded completions (#185)
carapace _carapace | source

Nushell

## ~/.config/nushell/env.nu
$env.CARAPACE_BRIDGES = 'zsh,fish,bash,inshellisense' # optional
mkdir ~/.cache/carapace
carapace _carapace nushell | save --force ~/.cache/carapace/init.nu

#~/.config/nushell/config.nu
source ~/.cache/carapace/init.nu

Oil

# ~/.config/oil/oshrc
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
source <(carapace _carapace)

Powershell

# ~/.config/powershell/Microsoft.PowerShell_profile.ps1
$env:CARAPACE_BRIDGES = 'zsh,fish,bash,inshellisense' # optional
Set-PSReadLineOption -Colors @{ "Selection" = "`e[7m" }
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
carapace _carapace | Out-String | Invoke-Expression

Tcsh

# ~/.tcshrc
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
set autolist
eval `carapace _carapace`

Xonsh

# ~/.config/xonsh/rc.xsh
$CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
$COMPLETIONS_CONFIRM=True
exec($(carapace _carapace))

Zsh

# ~/.zshrc
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'
source <(carapace _carapace)

Order of groups can be configured with the zstyle group-order.

zstyle ':completion:*:git:*' group-order 'main commands' 'alias commands' 'external commands'

Environment

CARAPACE_BRIDGES

Which implicit bridges to enable.

CARAPACE_COVERDIR

Coverage directory for sandbox tests (internal).

CARAPACE_ENV

Whether to register get-env, set-env and unset-env functions.

  • 0 - disabled
  • 1 - enabled

CARAPACE_EXCLUDES

Which internal completers to exclude.

CARAPACE_HIDDEN

Whether to show hidden commands/flags.

  • 0 - disabled
  • 1 - enabled

CARAPACE_LENIENT

Whether to allow unknown flags.

  • 0 - disabled
  • 1 - enabled

CARAPACE_LOG

Whether to enable logging.

  • 0 - disabled
  • 1 - enabled

CARAPACE_MATCH

Whether to match case insensitive.

  • 0 - case sensitive
  • 1 - case insensitive

CARAPACE_SANDBOX

Mock context for sandbox tests (internal).

CARAPACE_ZSH_HASH_DIRS

Zsh hash directories (internal).

Completers

  • acpi Shows information from the /proc filesystem
  • acpid Advanced Configuration and Power Interface event daemon
  • adb Android Debug Bridge
  • age simple, modern, and secure file encryption
  • agg asciinema gif generator
  • alsamixer soundcard mixer for ALSA soundcard driver, with ncurses interface
  • ant software tool for automating software build processes
  • aplay command-line sound recorder and player for ALSA soundcard driver
  • apropos search the manual page names and descriptions
  • apt-cache query the APT cache
  • apt-get APT package handling utility
  • ar create, modify, and extract from archives
  • arecord command-line sound recorder and player for ALSA soundcard driver
  • asciinema Record and share your terminal sessions, the right way.
  • autoconf Generate a configuration script from a TEMPLATE-FILE
  • avdmanager create and manage Android Virtual Devices
  • awk pattern scanning and processing language
  • aws Universal Command Line Interface for Amazon Web Services
  • az Azure Command-Line Interface
  • baobab A graphical disk usage analyzer for the GNOME deskto
  • basename strip directory and suffix from filenames
  • bash-language-server A language server for Bash
  • bash GNU Bourne-Again SHell
  • bat a cat clone with syntax highlighting and Git integration
  • batdiff Diff a file against the current git index, or display the diff between two files
  • batgrep Quickly search through and highlight files using ripgrep
  • batman Read system manual pages (man) using bat
  • bats Bash Automated Testing System
  • bc An arbitrary precision calculator language
  • benthos A stream processor for mundane tasks
  • black The uncompromising code formatter
  • bluetoothctl Bluetooth Control Command Line Tool
  • boundary Boundary enables identity-based access management for dynamic infrastructure
  • brew The missing package manager for macOS
  • brotli compress or decompress files
  • bru Bruno CLI
  • bun a fast bundler, transpiler, JavaScript Runtime and package manager for web software
  • bunx bun package manager
  • calibre Comprehensive e-book software
  • capslock Capslock is a capability analysis CLI for Go packages
  • cargo-clippy Checks a package to catch common mistakes and improve your Rust code
  • cargo-fmt format all bin and lib files of the current crate
  • cargo-metadata Output the resolved dependencies of a package
  • cargo-rm Remove a dependency from a Cargo.toml manifest file
  • cargo-set-version Change a package's version in the local manifest file
  • cargo-upgrade Update dependencies as recorded in the local lock file
  • cargo-watch Watches over your Cargo project’s source
  • cargo Rust's package manager
  • cat concatenate files and print on the standard output
  • cfdisk display or manipulate a disk partition table
  • charm Do Charm stuff
  • cheese tool to take pictures and videos from your webcam
  • chgrp change group ownership
  • chmod change file mode bits
  • chown change file owner and group
  • chpasswd update passwords in batch mode
  • chroma Chroma is a general purpose syntax highlighter
  • chromium chromium browser
  • chroot run command or interactive shell with special root directory
  • chsh Change your login shell
  • circleci Use CircleCI from the command line
  • cksum checksum and count the bytes in a file
  • clamav-config clamav config
  • clamav-milter milter compatible scanner
  • clambc Bytecode Analysis and Testing Tool
  • clamconf Clam AntiVirus configuration utility
  • clamd an anti-virus daemon
  • clamdscan scan files and directories for viruses using Clam AntiVirus Daemon
  • clamdtop monitor the Clam AntiVirus Daemon
  • clamonacc an anti-virus on-access scanning daemon and clamd client
  • clamscan scan files and directories for viruses
  • clamsubmit File submission utility for ClamAV
  • cmus Curses based music player
  • code-insiders Visual Studio Code Insiders
  • code Visual Studio Code
  • codecov codecov uploader
  • comm compare two sorted files line by line
  • conda-content-trust Signing and verification tools for Conda
  • conda-env Manage conda environments
  • conda conda is a tool for managing and deploying applications, environments and packages
  • conky A system monitor for X originally based on the torsmo code
  • consul Consul automates networking for simple and secure application delivery
  • coredumpctl List or retrieve coredumps from the journal
  • cp copy files and directories
  • csplit split a file into sections determined by context lines
  • csview A high performance csv viewer with cjk/emoji support
  • cura Powerful, easy-to-use 3D printing software
  • curl transfer a URL
  • cut remove sections from each line of files
  • dagger The Dagger CLI provides a command-line interface to Dagger.
  • darktable-cli a command line darktable variant
  • darktable a digital photography workflow application
  • dart A command-line utility for Dart development
  • date print or set the system date and time
  • dbt An ELT tool for managing your SQL transformations and data models
  • dc an arbitrary precision calculator
  • dd convert and copy a file
  • deadcode The deadcode command reports unreachable functions in Go programs
  • delta A viewer for git and diff output
  • deno A modern JavaScript and TypeScript runtime
  • devbox Instant, easy, predictable shells and containers
  • df report file system disk space usage
  • dfc report file system space usage information with style
  • dict Query a dictd server for the definition of a word
  • diff3 compare three files line by line
  • diff compare files line by line
  • dig DNS lookup utility
  • dir list directory contents
  • dircolors color setup for ls
  • direnv unclutter your .profile
  • dirname strip last component from file name
  • dive Docker Image Visualizer & Explorer
  • dlv Delve is a debugger for the Go programming language.
  • dmenu dynamic menu
  • dmesg Display or control the kernel ring buffer
  • dms A UPnP DLNA Digital Media Server
  • dnsmasq A lightweight DHCP and caching DNS server
  • doas execute a command as another user
  • docker-buildx Docker Buildx
  • docker-compose Docker Compose
  • docker-scan A tool to scan your images
  • docker A self-sufficient runtime for containers
  • dockerd A self-sufficient runtime for containers
  • doctl doctl is a command line interface (CLI) for the DigitalOcean API
  • doing CLI for repository/issue workflow on Azure Devops
  • dos2unix DOS/Mac to Unix and vice versa text file format converter
  • downgrade Downgrade Arch Linux packages
  • dpkg package manager for Debian
  • du estimate file space usage
  • ebook-convert Convert an e-book from one format to another
  • egrep print lines that match patterns
  • electron Build cross platform desktop apps with JavaScript, HTML, and CSS
  • elvish expressive programming language and a versatile interactive shell
  • env run a program in a modified environment
  • envsubst Substitutes the values of environment variables
  • exa a modern replacement for ls
  • expand convert tabs to spaces
  • expr evaluate expressions
  • eza a modern replacement for ls
  • faas-cli Manage your OpenFaaS functions from the command line
  • factor factor numbers
  • fakechroot gives a fake chroot environment
  • fakeroot run a command in an environment faking root privileges for file manipulation
  • fastfetch A neofetch-like tool for fetching system information and displaying them in a pretty way
  • fc-cache Build font information caches
  • fc-cat read font information cache files
  • fc-conflist list the configuration files processed by Fontconfig
  • fc-list list available fonts
  • fd find entries in the filesystem
  • fdisk manipulate disk partition table
  • ffmpeg Hyper fast Audio and Video encoder
  • fgrep print lines that match patterns
  • file determine file type
  • find search for files in a directory hierarchy
  • firefox Firefox Browser
  • fish the friendly interactive shell
  • flatpak Linux application sandboxing and distribution framework
  • flutter Manage your Flutter app development
  • fmt simple optimal text formatter
  • fold wrap each input line to fit in specified width
  • foot A fast, lightweight and minimalistic Wayland terminal emulator
  • freeze Generate images of code and terminal output
  • ftp File Transfer Protocol client
  • ftpd File Transfer Protocol daemon
  • fury Command line interface to Gemfury API
  • fzf a command-line fuzzy finder
  • gatsby Build blazing fast, modern apps and websites with React
  • gcloud manage Google Cloud Platform resources and developer workflow
  • gdb This is the GNU debugger
  • gdu Pretty fast disk usage analyzer written in Go
  • get-env get environment variable
  • gftp file transfer client for *NIX based machines
  • gh-copilot Your AI command line copilot
  • gh-dash A beautiful CLI dashboard for GitHub
  • gh GitHub CLI
  • gimp an image manipulation and paint program
  • git-abort Abort current rebase, merge or cherry-pick, without the need to find exact command in history
  • git-alias Define, search and show aliases
  • git-archive-file Export the current HEAD of the git repository to an archive
  • git-authors Generate authors report
  • git-browse Opens the current git repository website in your default web browser
  • git-clang-format run clang-format on lines that differ
  • git-extras Awesome GIT utilities
  • git-info Returns information on current repository
  • git-standup Recall the commit history
  • git the stupid content tracker
  • gitk The Git repository browser
  • gitui blazing fast terminal-ui for git
  • glab A GitLab CLI tool.
  • glow Render markdown on the CLI, with pizzazz!
  • gnome-keyring-daemon The Gnome Keyring Daemon
  • gnome-keyring The gnome-keyring commandline tool
  • gnome-maps A map application for GNOME
  • gnome-terminal A terminal emulator for GNOME
  • go-carpet show test coverage for Go source files
  • go-tool-asm go assembler
  • go-tool-buildid Buildid displays or updates the build ID stored in a Go package or binary.
  • go-tool-cgo Cgo enables the creation of Go packages that call C code
  • go-tool-compile compiles a single Go packag
  • go-tool-covdata read and manipulate coverage data files
  • cover analyze coverage profiles
  • go-tool-dist Dist helps bootstrap, build, and test the Go distribution
  • go-tool-doc show documentation for package or symbol
  • fix Fix finds Go programs that use old APIs
  • go-tool-link go linker
  • nm Nm lists the symbols defined or used by an object file, archive, or executabl
  • go-tool-objdump Objdump disassembles executable files
  • go-tool-pack Pack is a simple version of the traditional Unix ar tool
  • go Go is a tool for managing Go source code
  • gocyclo Calculate cyclomatic complexities of Go functions
  • gofmt format Go source code
  • goimports updates your Go import lines
  • golangci-lint golangci-lint is a smart linters runner.
  • gonew Gonew starts a new Go module by copying a template module
  • google-chrome chrome browser
  • gopls gopls is a Go language server
  • goreleaser Deliver Go binaries as fast and easily as possible
  • goweight A tool to analyze and troubleshoot a Go binary size
  • gparted GNOME Partition Editor for manipulating disk partitions
  • gpasswd administer /etc/group and /etc/gshadow
  • gpg-agent Secret key management for GnuPG
  • gpg OpenPGP encryption and signing tool
  • gradle Gradle Build Tool
  • grep print lines that match patterns
  • groupadd create a new group
  • groupdel delete a group
  • groupmems administer members of a user's primary group
  • groupmod modify a group definition on the system
  • groups display current group names
  • grype A vulnerability scanner for container images, filesystems, and SBOMs
  • gulp Command Line Interface for gulp
  • gum A tool for glamorous shell scripts
  • gunzip Uncompress files
  • gzip Compress or uncompress files
  • halt halt the machine
  • head output the first part of files
  • helix A post-modern text editor
  • helm The Helm package manager for Kubernetes.
  • helmsman Helmsman is a Helm Charts as Code tool
  • hexchat IRC Client
  • hexdump Display file contents in hexadecimal, decimal, octal, or ascii
  • hostid print the numeric identifier for the current host
  • hostname show or set system host name
  • htop interactive process viewer
  • http command-line HTTP client for the API era
  • https command-line HTTP client for the API era
  • hugo hugo builds your site
  • hwinfo Probe for hardware
  • hx A post-modern text editor
  • i3-scrot simple screenshot script
  • i3 an improved dynamic, tiling window manager
  • i3exit exit-script for i3
  • i3lock improved screen locker
  • i3status-rs A feature-rich and resource-friendly replacement for i3status, written in Rust
  • i3status Generates a status line for i3bar, dzen2, xmobar or lemonbar
  • id Print user and group information
  • imv Image viewer for X11 and Wayland
  • inkscape an SVG (Scalable Vector Graphics) editing program
  • inshellisense IDE style command line auto complete
  • install copy files and set attributes
  • ion The Ion Shell
  • jar create an archive for classes and resources
  • java Launches a Java application
  • javac Reads Java class and interface definitions and compiles them into bytecode and class files
  • jj Jujutsu (An experimental VCS)
  • join join lines of two files on a common field
  • journalctl Query the journal
  • jq Command-line JSON processor
  • julia high-level, high-performance dynamic programming language for technical computing
  • just Just a command runner
  • kak-lsp Kakoune Language Server Protocol Client
  • kak a vim-inspired, selection oriented code editor
  • kill Forcibly terminate a process
  • killall kill processes by name
  • kmonad an onion of buttons
  • kompose A tool helping Docker Compose users move to Kubernetes
  • kotlin run Kotlin programs, scripts or REPL
  • kotlinc Kotlin command-line compiler
  • ktlint An anti-bikeshedding Kotlin linter with built-in formatter
  • kubeadm kubeadm: easily bootstrap a secure Kubernetes cluster
  • kubectl kubectl controls the Kubernetes cluster manager
  • last Show a listing of last logged in users
  • lastb Show a listing of last logged in users
  • lastlog reports the most recent login of all users or of a given user
  • lazygit simple terminal UI for git commands
  • lf terminal file manager
  • light a program to control backlight controllers
  • lightdm a display manager
  • link call the link function to create a link to a file
  • ln make links between files
  • lnav ncurses-based log file viewer
  • lncrawl Generate and download e-books from online sources
  • locale Get locale-specific information
  • localectl Query or change system locale and keyboard settings
  • logname print user's login name
  • ls list directory contents
  • lsb_release prints certain LSB (Linux Standard Base) and Distribution information
  • lsblk list block devices
  • lscpu display information about the CPU architecture
  • lslocks List local system locks
  • lslogins Display information about known users in the system
  • lsmem list the ranges of available memory with their online status
  • lsns List system namespaces
  • lsusb list USB devices
  • lua Lua interpreter
  • lzcat Compress or decompress .xz and .lzma files
  • lzma Compress or decompress .xz and .lzma files
  • make GNU make utility to maintain groups of programs
  • makepkg make packages compatible for use with pacman
  • man an interface to the system reference manuals
  • marp A CLI interface for Marp and Marpit based converters
  • mcomix GTK Comic Book Viewer
  • md5sum compute and check MD5 message digest
  • mdbook Creates a book from markdown files
  • meld Meld is a file and directory comparison tool
  • melt melt generates a seed phrase from an SSH key
  • micro A modern and intuitive terminal-based text editor
  • minikube minikube quickly sets up a local Kubernetes cluster
  • mitmproxy interactive, SSL/TLS-capable intercepting proxy
  • mkcert simple tool for making locally-trusted development certificates
  • mkdir make directories
  • mkfifo make FIFOs (named pipes)
  • mkfs Make a Linux filesystem
  • mknod make block or character special files
  • mkswap Set up a Linux swap area
  • mktemp create a temporary file or directory
  • modinfo Show information about a Linux Kernel module
  • modprobe Add and remove modules from the Linux Kernel
  • molecule Testing framework to aid in the development of Ansible roles
  • more file perusal filter for crt viewing
  • mosh mobile shell with roaming and intelligent local echo
  • mount mount a filesystem
  • mousepad Mousepad is a simple text editor for the Xfce desktop environment
  • mpv a media player
  • mv move (rename) files
  • mvn Apache Maven is a software project management and comprehension tool
  • nano Nano's ANOther editor, inspired by Pico
  • nc simple Unix utility which reads and writes data across network connections
  • ncdu NCurses Disk Usage
  • neomutt The NeoMutt Mail User Agent
  • netcat simple Unix utility which reads and writes data across network connections
  • newman Newman is a command-line collection runner for Postman
  • newrelic The New Relic CLI
  • nfpm Packages apps on RPM, Deb and APK formats based on a YAML configuration file
  • ng The Angular CLI
  • nice run a program with modified scheduling priority
  • nilaway Static Analysis tool to detect potential Nil panics in Go code
  • nix-build build a Nix expression
  • nix-channel manage Nix channels
  • nix-instantiate instantiate store derivations from Nix expression
  • nix-shell start an interactive shell based on a Nix expression
  • nix a tool for reproducible and declarative configuration management
  • nixos-rebuild reconfigure a NixOS machine
  • nl number lines of files
  • nmcli command-line tool for controlling NetworkManager
  • node server-side JavaScript runtime
  • nohup run a command immune to hangups, with output to a non-tty
  • nomad Nomad is an easy-to-use, flexible, and performant workload orchestrator
  • npm the package manager for JavaScript
  • ntpd NTP daemon program
  • nu Nushell
  • nvim edit text
  • od dump files in octal and other formats
  • ollama Large language model runner
  • openscad script file based graphical CAD environment
  • optipng Optimize Portable Network Graphics files
  • packer Create identical machine images for multiple platforms from a single source configuration.
  • pacman-conf query pacman's configuration file
  • pacman-db-upgrade Upgrade the local pacman database to a newer format
  • pacman-key Manage pacman's list of trusted keys
  • pacman-mirrors generate pacman mirrorlist
  • pacman package manager utility
  • palemoon Pale Moon browser
  • pamac package manager utility
  • pandoc general markup converter
  • paru Feature packed AUR helper
  • pass stores, retrieves, generates, and synchronizes passwords securely
  • passwd change user password
  • paste merge lines of files
  • patch appy a diff file to an original
  • pathchk check whether file names are valid or portable
  • pcmanfm A lightweight Gtk+ based file manager for X Window
  • pgrep look up processes based on name and other attributes
  • picard Picard is a cross-platform music tagger written in Python
  • ping send ICMP ECHO_REQUEST to network hosts
  • pinky lightweight finger
  • pip package manager for Python packages
  • pkg A tool for managing packages
  • pkgsite Pkgsite extracts and generates documentation for Go programs
  • pkill look up for processes based on name and other attributes
  • pnpm Fast, disk space efficient package manager
  • podman Simple management tool for pods, containers and images
  • poweroff poweroff the machine
  • powertop The Linux PowerTOP tool
  • pprof pprof is a tool for visualization and analysis of profiling data
  • pr convert text files for printing
  • present present implements parsing and rendering of present file
  • prettybat Pretty-print source code and highlight it with bat
  • prettyping This script is a wrapper around the system's "ping" tool
  • printenv print all or part of environment
  • ps report a snapshot of the current processes
  • ptx produce a permuted index of file contents
  • pulumi Pulumi command line
  • pwait wait for processes based on name and other attributes
  • pwd Print the full filename of the current working directory
  • python an interpreted, interactive, object-oriented programming language
  • qmk CLI wrapper for running QMK commands
  • qrencode Encode input data in a QR Code and save as a PNG or EPS image
  • qutebrowser a keyboard-driven, vim-like browser based on PyQt5
  • ranger visual file manager
  • readlink print resolved symbolic links or canonical file names
  • reboot reboot the machine
  • redis-cli Redis command line interface
  • restic Backup and restore files
  • resume-cli command line tool for JSON Resume
  • rg recursively search current directory for lines matching a pattern
  • rifle ranger's file opener
  • rm remove files or directories
  • rmdir remove empty directories
  • rmmod Simple program to remove a module from the Linux Kernel
  • rsync a fast, versatile, remote (and local) file-copying tool
  • rust-analyzer LSP server for the Rust programming language
  • rustc compiler for the Rust programming language
  • rustdoc generate documentation for Rust projects
  • rustup installer for the systems programming language Rust
  • scp OpenSSH secure file copy
  • scrot command line screen capture utility
  • sdkmanager Android SDK manager
  • sed stream editor for filtering and transforming text
  • semver A JavaScript implementation of the https://semver.org/ specification
  • seq print a sequence of numbers
  • set-env set environment variable
  • sftp OpenSSH secure file transfer
  • sha1sum compute and check SHA1 message digest
  • sha256sum compute and check SHA256 message digest
  • showkey examine the codes sent by the keyboard
  • shred overwrite a file to hide its contents, and optionally delete it
  • shutdown Shut down the system
  • sleep delay for a specified amount of time
  • slides Terminal based presentation tool
  • soft A self-hostable Git server for the command line
  • sort sort lines of text files
  • speedtest-cli Command line interface for testing internet bandwidth using speedtest.net
  • split split a file into pieces
  • ssh-agent OpenSSH authentication agent
  • ssh-copy-id use locally available keys to authorise logins on a remote machine
  • ssh-keygen OpenSSH authentication key utility
  • ssh OpenSSH remote login client
  • st simple terminal
  • starship The cross-shell prompt for astronauts
  • stat display file or file system status
  • staticcheck The advanced Go linter
  • strings print the sequences of printable characters in files
  • stty change and print terminal line settings
  • su run a command with substitute user and group ID
  • sudo execute a command as another user
  • sudoedit edit files as another user
  • sudoreplay replay sudo session logs
  • sulogin single-user login
  • sum checksum and count the blocks in a file
  • supervisorctl control applications run by supervisord from the cmd line
  • supervisord run a set of applications as daemons
  • svg-term Share terminal sessions as razor-sharp animated SVG everywhere
  • svgcleaner clean up your SVG files from the unnecessary data
  • sway An i3-compatible Wayland compositor
  • swaybar bar for swaywm
  • swaybg Background for Wayland
  • swayidle Idle manager for Wayland
  • swaylock Screen locker for Wayland
  • swaymsg Send messages to a running instance of sway over the IPC socket
  • swaynag Show a warning or error message with buttons
  • syft Generate a package SBOM
  • sync Synchronize cached writes to persistent storage
  • sysctl configure kernel parameters at runtime
  • systemctl Query or send control commands to the system manager
  • tac concatenate and print files in reverse
  • tail output the last part of files
  • tar tar - an archiving utility
  • task A task runner / simpler Make alternative written in Go
  • tea command line tool to interact with Gitea
  • tealdeer A fast TLDR client
  • tee read from standard input and write to standard output and files
  • telnet User interface to TELNET
  • templ A language for writing HTML user interfaces in Go
  • termux-apt-repo Create a repository with deb files
  • terraform-ls Terraform Language Server
  • terraform infrastructure as code software tool
  • terragrunt Terragrunt is a thin wrapper for Terraform
  • terramate A tool for managing terraform stacks
  • tesseract command-line OCR engine
  • tig text-mode interface for Git
  • tinygo TinyGo is a Go compiler for small places
  • tldr Python command line client for tldr
  • tmate Instant terminal sharing
  • tmux terminal multiplexer
  • tofu The open source infrastructure as code tool
  • toit.lsp start the lsp server
  • toit.pkg The Toit package manager
  • top display Linux processes
  • tor-browser Tor Browser
  • tor-gencert Generate certs and keys for Tor directory authorities
  • tor-print-ed-signing-cert print expiration date of ed25519 signing certificate
  • tor-resolve resolve a hostname to an IP address via tor
  • torsocks Shell wrapper to simplify the use of the torsocks(8) library to transparently torify an application
  • touch change file timestamps
  • tr translate or delete characters
  • traefik Traefik is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease
  • transmission-cli A fast and easy BitTorrent client
  • transmission-create A command-line utility to create .torrent files
  • transmission-daemon A daemon-based BitTorrent client
  • transmission-edit A command-line utility to modify .torrent files' announce URLs
  • transmission-remote A remote control utility for transmission-daemon and transmission
  • transmission-show A command-line utility to show .torrent file metadata
  • tree list contents of directories in a tree-like format
  • truncate Shrink or extend the size of each FILE to the specified size
  • ts timestamp input
  • tsc The TypeScript Compiler
  • tsh Teleport Command Line Client
  • tshark Dump and analyze network traffic
  • tsort perform topological sort
  • tty print the file name of the terminal connected to standard input
  • ttyd ttyd is a tool for sharing terminal over the web
  • turbo The build system that makes ship happen
  • umount Unmount filesystems
  • uname print system information
  • unbrotli compress or decompress files
  • unexpand convert spaces to tabs
  • uniq report or omit repeated lines
  • unlink call the unlink function to remove the specified file
  • unlzma Compress or decompress .xz and .lzma files
  • unset-env unset environment variable
  • unxz Compress or decompress .xz and .lzma files
  • unzip list, test and extract compressed files in a ZIP archive
  • upower UPower command line tool
  • uptime Tell how long the system has been running
  • upx compress or expand executable files
  • useradd create a new user or update default new user information
  • userdel delete a user account and related files
  • usermod modify a user account
  • users print the user names of users currently logged in to the current host
  • vagrant tool for building and managing virtual machine environments
  • vault A tool for secrets management
  • vdir list directory contents
  • vercel Develop. Preview. Ship.
  • vhs Run a given tape file and generates its outputs.
  • vi screen oriented (visual) display editor based on ex
  • viewnior simple, fast and elegant image viewer
  • visudo safely edit the sudoers file
  • viu View images right from the terminal
  • vivid LS_COLORS manager with multiple themes
  • vlc the VLC media player
  • volta The JavaScript Launcher
  • w Show who is logged on and what they are doing
  • watch execute a program periodically, showing output fullscreen
  • watchexec Execute commands when watched files change
  • watchgnupg Read and print logs from a socket
  • waypoint Easy application deployment for Kubernetes and Amazon ECS
  • wc print newline, word, and byte counts for each file
  • wezterm Wez's Terminal Emulator
  • wget a non-interactive network retriever
  • whereis Locate the binary, source, and manual-page files for a command
  • which Write the full path of COMMAND(s) to standard output
  • who show who is logged on
  • whoami print effective userid
  • wine run Windows programs on Unix
  • wineboot perform Wine initialization, startup, and shutdown task
  • winepath Tool to convert Unix paths to/from Win32 paths
  • wineserver the Wine server
  • winetricks manage virtual Windows environments using Wine
  • wire Compile-time Dependency Injection for Go
  • wireshark Interactively dump and analyze network traffic
  • wishlist The SSH Directory
  • wl-mirror a simple Wayland output mirror client
  • woeusb A Linux program to create a Windows USB stick installer
  • xargs build and execute command lines from standard input
  • xbacklight adjust backlight brightness using RandR extension
  • xclip command line interface to X selections
  • xdotool command-line X11 automation tool
  • xonsh Python-powered shell
  • xz Compress or decompress .xz and .lzma files
  • xzcat Compress or decompress .xz and .lzma files
  • yarn Yarn is a package manager that doubles down as project manager
  • yay An AUR Helper written in Go
  • yes output a string repeatedly until killed
  • yj Convert between YAML, TOML, JSON, and HCL
  • youtube-dl download videos from youtube.com or other video platforms
  • yt-dlp A youtube-dl fork with additional features and fixes
  • zathura a document viewer
  • zcat compress or expand files
  • zip package and compress (archive) files
  • zoxide A smarter cd command for your terminal

Style

Transformations can be applied to files and specific values.

This is only supported in elvish, nushell, powershell, xonsh and zsh.

File

Files can be styled with the LS_COLORS environment variable (e.g. using vivid):

# elvish
set-env LS_COLORS (vivid generate dracula)

# powershell
$env:LS_COLORS = (vivid generate dracula)

# zsh
export LS_COLORS=$(vivid generate dracula)

Value

Values can be styled with a comma separated list of transformations:

# set
carapace --style 'carapace.Value=bold,magenta'

# clear
carapace --style 'carapace.Description='

Generic configuration like default value and description style can be found under carapace.{key}

Scheme

How the default colors look depends on your terminal color scheme.

It is recommended to choose one with a high contrast so that every color is well readable.

Transformations

Transformations are adopted from elvish:

Each $style-transformer can be one of the following:

  • A boolean attribute name:
    • One of bold, dim, italic, underlined, blink and inverse for setting the corresponding attribute.
    • An attribute name prefixed by no- for unsetting the attribute.
    • An attribute name prefixed by toggle- for toggling the attribute between set and unset.
  • A color name for setting the text color, which may be one of the following:
    • One of the 8 basic ANSI colors: black, red, green, yellow, blue, magenta, cyan and white.
    • The bright variant of the 8 basic ANSI colors, with a bright- prefix.
    • Any color from the xterm 256-color palette, as colorX (such as color12).
    • A 24-bit RGB color written as #RRGGBB (such as '#778899'). Note: You need to quote such values, since an unquoted # introduces a comment (e.g. use 'bg-#778899' instead of bg-#778899).
  • A color name prefixed by fg- to set the foreground color. This has the same effect as specifying the color name without the fg- prefix.
  • A color name prefixed by bg- to set the background color.

Bridges

With ~/.config/carapace/bridges.yaml generic bridges can be configured for commands.

gh: cobra
opentofu: complete
tsh: kingpin

bridges.yaml is a simpler alternative to Spec/Bridge. It has a higher precedence than CARAPACES_BRIDGES but lower than internal completers and specs. So disable an internal completer with CARAPACES_EXCLUDES if you want to replace it with a bridge.

Currently available bridges:

Bridging frameworks should be preferred to shells (e.g. zsh) as these generally work better and have less overhead.

Cache

The list of completers is cached to not impact shell startup time. Clear the cache with carapace --clear-cache if your system changes.

Spec

Custom completions can be defined using yaml files.

see carapace-spec for more documentation

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: mycmd
description: my command
flags:
  --optarg?: optarg flag
  -r, --repeatable*: repeatable flag
  -v=: flag with value
persistentflags:
  --help: bool flag
completion:
  flag:
    optarg: ["one", "two\twith description", "three\twith style\tblue"]
    v: ["$files"]
commands:
- name: sub
  description: subcommand
  completion:
    positional:
      - ["$list(,)", "1", "2", "3"]
      - ["$directories"]

Custom Macros

Carapace provides a range of custom macros:

carapace --macro                       # list macros
carapace --macro color.HexColors       # show macro details
carapace --macro color.HexColors <TAB> # test macro

User

User defined Specs are automatically loaded by carapace _carapace from ${UserConfigDir}/carapace/specs.

Added files initially need a new shell to be started for it to be registered with carapace _carapace. Afterwards any change to it has an immediate effect.

It is mandatory that the file name matches the name defined in the spec (e.g. myspec.yaml for name: myspec).

Override

Specs override an internal completer with the same name. E.g. if the internal kubectl completer does not work as expected it can be bridged instead:

name: kubectl
description: kubectl controls the Kubernetes cluster manager
completion:
  positionalany: ["$carapace.bridge.Cobra([kubectl])"]

JSON Schema

A JSON Schema can be used by adding the following header to the Specs:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json

Bridge

Bridging completions from another engine for shells not natively supported by it is possible with the corresponding Macro.

Even when the command supports your current shell it is still beneficial to bridge it as this enables embedding like sudo [spec.name] <TAB>.

It also avoids the issue of shell startup delay when sourcing the completion in init scripts otherwise circumvented with lazycomplete.

However, bridging is limited to supported commands/frameworks and how well it actually works.

Frameworks

Argcomplete

kislyuk/argcomplete based commands can be bridged with the bridge.Argcomplete macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: az
description: Azure Command-Line Interface
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Argcomplete([az])"]

Carapace

carapace-sh/carapace based commands can be bridged with the bridge.Carapace macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: freckles
description: simple dotfile manager
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Carapace([freckles])"]

CarapaceBin

Completers and Specs registered in carapace-sh/carapace-bin can be bridged with the bridge.CarapaceBin macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: github-cli
description: Work seamlessly with GitHub from the command line
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.CarapaceBin([gh])"]

Clap

clap-rs/clap based commands can be bridged with the bridge.Clap macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: dyamic
description: clap dynamic example
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Clap([dynamic])"]

Click

pallets/click based commands can be bridged with the bridge.Click macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: watson
description: Watson is a tool aimed at helping you monitoring your time
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Click([watson])"]

Cobra

spf13/cobra based commands can be bridged with the bridge.Cobra macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: kubectl
description: kubectl controls the Kubernetes cluster manager
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Cobra([kubectl])"]

Complete

posener/complete based commands can be bridged with the bridge.Complete macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: vault
description: Manage Secrets & Protect Sensitive Data
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Complete([vault])"]

Inshellisense

Commands provided by microsoft/inshellisense can be bridged with the bridge.Inshellisense macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: node
description: Run the node interpreter
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Inshellisense([node])"]

Kingpin

alecthomas/kingpin based commands can be bridged with the bridge.Kingpin macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: tsh
description: Teleport Command Line Client
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Kingpin([tsh])"]

Urfavecli

urfave/cli based commands can be bridged with the bridge.Urfavecli macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: tea
description: command line tool to interact with Gitea
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Urfavecli([tea])"]

Yargs

yargs/yargs based commands can be bridged with the bridge.Yargs macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: ng
description: CLI tool for Angular
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Yargs([ng])"]

Shells

For shells custom configurations are loaded from ${UserConfigDir}/carapace/bridge. Invoking completion in shells is quite tricky though and edge cases are likely to fail.

Bash

Commands registered in bash can be bridged with the bridge.Bash macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name:  tail
description: output the last part of files
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Bash([tail])"]

Fish

Commands registered in fish-shell/fish-shell can be bridged with the bridge.Fish macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name:  git
description: the stupid content tracker
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Fish([git])"]

Powershell

Commands registered in powershell can be bridged with the bridge.Powershell macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name:  ConvertTo-Json
description: convert to json
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Powershell([ConvertTo-Json])"]

Zsh

Commands registered in zsh can be bridged with the bridge.Zsh macro:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name:  git
description: the stupid content tracker
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Zsh([git])"]

Embed

The bridged completion can also be embedded as subcommand.

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: embed
commands:
  - name: git
    completion:
      positionalany: ["$carapace.bridge.CarapaceBin([git]) ||| $chdir(~/.password-store)"]

Plugin

Embedding is also internally used to enable plugin completion for tools like cargo-[plugin], gh-[plugin], git-[plugin]. Simply add a Spec with the corresponding name.

E.g. the gh-repo-collab extension for GitHub CLI:

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: gh-repo-collab
description: manage repository collaborators
commands:
  -
    name: list
    completion:
      positional:
        - ["$carapace.tools.gh.OwnerRepositories"]
  -
    name: add
    flags:
      --permission=: set permission
    completion:
      flag:
        permission: ["pull", "triage", "push", "maintain", "admin\t\tred"]
      positional:
        - ["$carapace.tools.gh.OwnerRepositories"]
        - ["$carapace.tools.gh.Users"]
  -
    name: remove
    completion:
      positional:
        - ["$carapace.tools.gh.OwnerRepositories"]
        - ["$carapace.tools.gh.Users"]

Run

Specs containing a run field can be executed using Shims.

Alias

Alias bridges a command while retaining the argument completion.

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: log-by-author
run: "[git, log, --author]"

Script

Script macro is executed with sh on unix systems and pwsh on windows. Flags are used for environment substitution and positional arguments are passed to the script.

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: ls-remote
run: "$(git ls-remote --sort='${C_FLAG_SORT:-HEAD}' $@)"
flags:
  --sort=: field name to sort on
completion:
  flag:
    sort: [version:refname, authordate]
  positional:
    - ["$carapace.tools.git.RepositorySearch"]
  positionalany: ["$carapace.tools.git.LsRemoteRefs({url: '${C_ARG0}', branches: true, tags: true})"]

Shim

When carapace _carapace is invoked it creates shims in ${UserConfigDir}/carapace/bin for runnable specs.

For unix systems this is a simple shell script, but for windows an embedded binary is used.

#!/bin/sh
carapace --run "/home/carapace-sh/.config/carapace/specs/runnable.yaml" "$@"

Scrape

Command structure from various tools can be scraped to Specs.

Clap

For clap use carapace-spec-clap.

Cobra

For cobra use carapace.

Kingpin

For kingpin use carapace-spec-kingpin.

Kong

For kong use carapace-spec-kong.

Man

For manpages use carapace-spec-man.

Urfavecli

For urfavecli use carapce-spec-urfavecli.

Codegen

Specs can be used to generate go code.

carapace --codegen [spec]

Examples

github.yaml

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: github
completion:
  positional:
    - ["$carapace.tools.gh.OwnerRepositories"]  # ${C_ARG0}
    - ["$carapace.tools.git.LsRemoteRefs({url: 'https://github.com/${C_ARG0}', branches: true, tags: true})"]

zipfile.yaml

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: zipfile
completion:
  positional:
    - ["$files([.zip])"] # ${C_ARG0}
  positionalany: ["$carapace.fs.ZipFileContents(${C_ARG0})"] # ${C_ARG1},${C_ARG2},...

refs.yaml

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: refs
flags:
  -t, --tags: include tags # ${C_FLAG_TAGS}
  --localbranches: include local branches # ${C_FLAG_LOCALBRANCHES}
  --c=: amount of commits # ${C_FLAG_C}
completion:
  positional:
    - ["$carapace.tools.git.Refs({tags: ${C_FLAG_TAGS:-false}, localbranches: ${C_FLAG_LOCALBRANCHES:-false}, commits: ${C_FLAG_C:-0}})"]
    - ["$carapace.tools.git.Refs"] # default

g.yaml

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: g
commands:
  - name: log
    description: Show commit logs
    group: git
    run: "[git, log]"

  - name: issue
    description: Manage issues
    group: gh
    run: "[gh, issue]"
    commands:
      - name: bugs
        description: List bugs
        run: "[gh, issue, list, --label, bug]"

  - name: edit
    description: Edit changed files
    run: "$(hx $@)"
    flags:
      -s, --staged: include staged files
    completion:
      positionalany: ["$carapace.tools.git.Changes({staged: ${C_FLAG_STAGED:-false}, unstaged: true})"]

Macros

Overlay

Overlays are essentially Spec files placed in ${UserConfigDir}/carapace/overlays that provide additional completions. These are merged with the existing completion and provide a workaround for issues that have yet to be fixed in upstream.

Overlays implicitly set CARAPACE_LENIENT to allow unknown flags.

Flag

# ~/.config/carapace/overlays/doctl.yaml
name: doctl
persistentflags:
  --output=: Desired output format [text|json]
completion:
  flag:
    output: [text, json]
commands:
  - name: compute
    description: Display commands that manage infrastructure
    commands:
      - name: region
        description: Display commands to list datacenter regions
        commands:
          - name: list
            description: List datacenter regions
            flags:
              --format=: Columns for output in a comma-separated list
            completion:
              flag:
                format: ["$uniquelist(,)", Slug, Name, Available]

Command

# ~/.config/carapace/overlays/doctl.yaml
name: doctl
commands:
  - name: auth
    description: Display commands for authenticating doctl with an account
    group: management

  - name: compute
    description: Display commands that manage infrastructure
    group: core

  - name: custom
    description: custom command
    group: custom
    flags:
      -h, --help: show help
    completion:
      positional:
        - [one, two, three]

Variable

Complex environment variable completion is provided with get-env, set-env and unset-env.

In elvish the completion is simply overridden. For other shells custom functions are added.

Setting CARAPACE_ENV=0 before sourcing carapace _carapace disables this behaviour.

Custom variables

Custom variables can be defined in ~/.config/carapace/variables/{group}.yaml

variables:
  CUSTOM_EXAMPLE: example environment variable
  CUSTOM_MACRO: macro example
  HTTPS_PROXY: override existing variable
completion:
  variable:
    CUSTOM_EXAMPLE: ["0\tdisabled\tred", "1\tenabled\tgreen"]
    CUSTOM_MACRO: ["$carapace.tools.gh.Labels({owner: rsteube, name: carapace}) ||| $uniquelist(,)"]
    HTTPS_PROXY: ["https://localhost:8443\tdevelopment", "https://proxy.company:443\tproduction"]

It is also possible to define conditions.

condition: ["$Parent([.git])"]
variables:
  CUSTOM_CONDITION: condition example
completion:
  variable:
    CUSTOM_CONDITION: ["within", "git", "repo"]

Conditions

  • Arch checks if the given names contain current runtime.GOARCH
  • Os checks if the given names contain current runtime.GOOS
  • Parent checks if any parent directory contains one of the given file/directory
  • Path checks if any of the given executables are in PATH

Development

Project Layout

.
├── cmd
│  ├── carapace # main application
│  ├── carapace-fmt # simple formatter
│  ├── carapace-generate # executed by `go generate`
│  ├── carapace-lint # simple linter
│  ├── carapace-parse # simple help output parser
│  └── carapace-shim # binary for runnable specs in windows
├── completers # completers
│  └── example_completer # completer for `example`
│    └── cmd
│      └── action # local (coupled) actions
├── completers_release # optimized completers
├── dist # goreleaser dist folder
├── docs # documentation
├── internal # internal packages
└── pkg # public packages
   ├── actions # shared actions that are also exposed as macros
   │  └── tools # shared actions specific to tools
   ├── conditions # conditions for environment variable completion
   ├── env # environment variables
   ├── styles # style configurations
   └── util # util functions

Build

Requirements

  • Go
  • Ensure PATH contains your ~/go/bin folder (see doc)

Development

cd cmd/carapace
go generate ./... # only needed once and when there are new completers or actions
go install

Release

A build with the release tag uses completers_release which optimizes startup times.

cd cmd/carapace
go generate ./... # always needed for `completers_release` to be updated
go install -ldflags="-s -w" -tags release

Separate

Completers can also be built (and thus maintained) separately.

cd completers/ln_completer
go install -ldflags="-s -w"

Docker

docker-compose run --rm build # build once (will be mounted from `cmd/carapace`)
docker-compose run --rm [bash|elvish|fish|ion|nushell|oil|powershell|tcsh|xonsh|zsh]
[ln|mkdir|chown...] <TAB>

Creating completers

Manually

  • Copy a basic completer for simplicity.
cp -r completers/ln_completer completers/manually_completer
  • Update the package name in main.go.
-import "github.com/carapace-sh/carapace-bin/completers/ln_completer/cmd"
+import "github.com/carapace-sh/carapace-bin/completers/manually_completer/cmd"
  • Create the root command.
echo | carapace-parse -n manually > root.go
  • Add subcommands.
echo | carapace-parse -n subcommand -p root > subcommand.go

Parsing

Scraping

Examples

Journalctl

asciicast

Updating Completers

Best Practices

Coupled Actions

Use coupled actions to avoid repetition.

Sometimes an Action depends on the same flag values for multiple subcommands. Since ActionCallback is needed to access these the code can become a bit cumbersome and bloated.

carapace.Gen(get_allCmd).PositionalCompletion(
	carapace.ActionCallback(func(c carapace.Context) carapace.Action {
		return helm.ActionReleases(helm.ReleasesOpts{
			Namespace:   rootCmd.Flag("namespace").Value.String(),
			KubeContext: rootCmd.Flag("kube-context").Value.String(),
		})
	}),
)

An alternative to this is creating a local Action that is coupled to the command. Meaning, passing it the command and expecting specific flags to be present.

// completers/helm_completer/cmd/action/release.go
func ActionReleases(cmd *cobra.Command) carapace.Action {
	return carapace.ActionCallback(func(c carapace.Context) carapace.Action {
		return helm.ActionReleases(helm.ReleasesOpts{
			Namespace:   cmd.Root().Flag("namespace").Value.String(),
			KubeContext: cmd.Root().Flag("kube-context").Value.String(),
		})
	})
}

Thus the call becomes quite compact.

carapace.Gen(get_allCmd).PositionalCompletion(
	action.ActionReleases(get_allCmd),
)

Tools

carapace-fmt

carapace-lint

carapace-parse

carapace-generate

Release Notes

v1.0 - Moving Day

Off to a shiny new home.

Organization

Moved repositories to carapace-sh.

import (
- "github.com/rsteube/carapace"
+ "github.com/carapace-sh/carapace"
)

Diff

Added --diff command[/bridge] ...args to track changes.

--- a/zsh/carapace --macro bridge.Zsh git log -
+++ b/carapace/carapace git export git log -
- -- (start file arguments)
  --abbrev (Show the shortest prefix that is at least <n> hexdigits long that uniquely refers)
  --abbrev-commit (Instead of showing the full 40-byte hexadecimal commit object name, show a prefix that names the object uniquely.)
  --after (Show commits more recent than a specific date.)
  --all (Pretend as if all the refs in refs/, along with HEAD, are listed on the command line as <commit>.)
  --all-match (Limit the commits output to ones that match all given --grep, instead of ones that match at least one.)
+ --alternate-refs (Pretend as if all objects mentioned as ref tips of alternate repositories were listed on the command line.)
  --ancestry-path (When given a range of commits to display, only display commits that exist directly on the ancestry chain.)
  --anchored (Generate a diff using the "anchored diff" algorithm.)
  --author (Limit the commits output to ones with author/committer header lines that match the specified pattern)
  --author-date-order (Show no parents before all of its children are shown, but otherwise show commits in the author timestamp order.)
+ --basic-regexp (Consider the limiting patterns to be basic regular expressions; this is the default.)
  --before (Show commits older than a specific date.)
  --binary (In addition to --full-index, output a binary diff that can be applied with git-apply. Implies --patch.)
  --bisect (Pretend as if the bad bisection ref refs/bisect/bad was listed and as if it was followed by --not and the good bisection refs refs/bisect/good-* on the command line.)
  --boundary (Output excluded boundary commits. Boundary commits are prefixed with -.)
  --branches (Pretend as if all the refs in refs/heads are listed on the command line as <commit>.)
  --break-rewrites (Break complete rewrite changes into pairs of delete and create.)
- --cc (combined diff format for merge commits)
  --check (Warn if changes introduce conflict markers or whitespace errors.)
  --cherry (A synonym for --right-only --cherry-mark --no-merges)

The diff simply compares inserted values between completions provided by a bridge with those provided by carapace. It is just an indicator as there can be good reasons why these vary.

Clear Cache

Added --clear-cache to remove cached completions.

Positional Arguments

Positional arguments can now be accessed as script parameters in exec macros .

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: positional
flags:
  -b, --bool: bool flag
completion:
  positionalany: ["$(echo \"$@\tall arguments\")", "$(echo \"$1\tfirst argument\")"]

v0.30 - Wire Tap

Tapping into other shells for additional completions.

Implicit Bridges

With CARAPACE_BRIDGES default bridges can be enabled for commands not provided by carapace.

set-env CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense'

Order defines the precedence (e.g. if zsh has a git completer it will be used instead of the one in fish).

Explicit Bridges

Additionally to user specs ~/.config/carapace/bridges.yaml provides a simpler configuration of bridges.

gh: cobra
opentofu: complete
tsh: kingpin

bridges.yaml has a higher precedence than Implicit Bridges but lower than internal completers and specs. So disable an internal completer with Excludes if you want to replace it with a bridge.

Currently available bridges:

Bridging frameworks should be preferred to shells (e.g. zsh) as these generally work better and have less overhead.

Excludes

With CARAPACE_EXCLUDES internal completers can be excluded.

Explicit Parsing Mode

So far flag parsing was implicitly disabled for bridge macros in specs. From now on this needs to be done explicitly.

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json
name: az
description: Azure Command-Line Interface
parsing: disabled
completion:
  positionalany: ["$carapace.bridge.Argcomplete([az])"]
  • interspersed - mixed flags and positional arguments (default)
  • non-interspersed - flag parsing stopped after first positional argument
  • disabled - flag parsing disabled

v0.29 - Art Exchange

One step further to exchange completions between commands.

carapace.sh

Registered the domain carapace.sh.

Root Command

Restructured the carapace root command which was (and still is) a bit of a mess. Some flags (subcommands) were renamed/changed for consistency.

  • --list=json -> --list --format json
  • --macros -> --macro
  • --scrape [spec] -> --codegen [spec]

Specs

The JSON Schema is now hosted at https://carapace.sh/schemas/command.json.

# yaml-language-server: $schema=https://carapace.sh/schemas/command.json

~/.config/carapace/schema.json is now deprecated and can be removed.

Macro

$_ prefix in specs is now deprecated and needs to be replaced with $carapace.

If a macro name contains . the first segment is handled as command that will be invoked.

$carapace.color.HexColors
# invokes `carapace _carapace macro color.HexColors ""`

$carapace-spec.Spec(example.yaml)
# invokes `carapace-spec _carapace macro "Spec(example.yaml)" ""`

This behaviour will change slightly in the future to support custom macros.

With the --in-place flag of sed the specs can be updated directly.

sed 's/$_/$carapace./g' ~/.config/carapace/specs/*.yaml

Inshellisense

Added a bridge for inshellisense (which uses fig under the hood).

Nushell

Support for colored completion (requires nushell#11442).

Xonsh

Support for colored completion.

v0.28 - Greenwashing

This one is messing with your environment.

Variable

Complex environment variable completion is provided with get-env, set-env and unset-env.

In elvish the completion is simply overridden. For other shells custom functions are added.

Setting CARAPACE_ENV=0 before sourcing carapace _carapace disables this behaviour.

Custom variables

Custom variables can be defined in ~/.config/carapace/variables/{group}.yaml

variables:
  CUSTOM_EXAMPLE: example environment variable
  CUSTOM_MACRO: macro example
  HTTPS_PROXY: override existing variable
completion:
  variable:
    CUSTOM_EXAMPLE: ["0\tdisabled\tred", "1\tenabled\tgreen"]
    CUSTOM_MACRO: ["$_tools.gh.Labels({owner: carapace-sh, name: carapace}) ||| $uniquelist(,)"]
    HTTPS_PROXY: ["https://localhost:8443\tdevelopment", "https://proxy.company:443\tproduction"]

It is also possible to define conditions.

condition: ["$Parent([.git])"]
variables:
  CUSTOM_CONDITION: condition example
completion:
  variable:
    CUSTOM_CONDITION: ["within", "git", "repo"]

Specific modifiers

Specs now support specific modifiers using ||| as delimiter.

name: modifier
positionalany: ["$files ||| $chdir(/tmp)"]

Git

Full support for relative refs.

v0.27 - Hulk BASH!

Contains strong changes to the bash integration.

Redirects

Support for redirects. bash passes these to the completion function, so crazy stuff like this is possible:

example action >/tmp/stdout.txt embeddedPositional1 --styles 2>/tmp/stderr.txt red 'embeddedPositional2 with space'

To make this work carapace-shlex is now used to parse COMP_LINE when invoked from a bash completion function.

Wordbreaks

Better support for bash COMP_WORDBREAKS using carapace-shlex. This was originally intended to make multipart completion easier (e.g. colon separated list), but actually makes it very complicated and error-prone.

Case insensitive matching

Added (limited) case insensitive matching.

Set environment variable CARAPACE_MATCH to CASE_INSENSITIVE or 1 to activate it. You might also need to configure your shell, e.g. in elvish:

set-env CARAPACE_MATCH CASE_INSENSITIVE
set edit:completion:matcher[argument] = {|seed| edit:match-prefix $seed &ignore-case=$true }

v0.26 - Overly Attached Argument

Argument

Added support for various attached versions of passing non-optional flag arguments:

--longhand=arg
-l=arg
-larg
-abclarg

Lexer

Added a simple lexer for complex commands passed as single argument:

Nushell

Used the lexer to patch arguments as these are currently passed mostly unprocessed to the completion function. This is a workaround and has some edge cases but should overall improve the Nushell integration.

v0.25 - Window Shopping

Windows

Support for volume prefix in path completion.

v0.24 - Spring Cleaning

carapace-bridge

Moved bridge actions to carapace-bridge. The shell bridges now use custom configs at ${UserConfigDir}/carapace/bridge (e.g. ~/.config/carapace/bridge/fish/config.fish instead of ~/.config/fish/config.fish).

removed flags

Removed --bridge and --spec flags as user specs are preferred and there are carapace-bridge and carapace-spec as well.

v0.23 - First Amendment

Bridge Actions (BREAKING CHANGE)

Bridge actions now take multiple arguments. Analogue to Alias this enables embedding of subcommands in macros. Specs need to be updated though by adding [] brackets to the bridge macro arguments:

completion:
  # positionalany: ["$_bridge.CarapaceBin(git)"]  # OLD
  positionalany: ["$_bridge.CarapaceBin([git])"]  # NEW

Overlay

Overlays are essentially Spec files placed in ${UserConfigDir}/carapace/overlays that provide additional completions.

These are merged with the existing completion and provide a workaround for issues that have yet to be fixed in upstream.

Overlays implicitly set CARAPACE_LENIENT to allow unknown flags.

Flag

# ~/.config/carapace/overlays/doctl.yaml
name: doctl
persistentflags:
  --output=: Desired output format [text|json]
completion:
  flag:
    output: [text, json]
commands:
  - name: compute
    description: Display commands that manage infrastructure
    commands:
      - name: region
        description: Display commands to list datacenter regions
        commands:
          - name: list
            description: List datacenter regions
            flags:
              --format=: Columns for output in a comma-separated list
            completion:
              flag:
                format: ["$uniquelist(,)", Slug, Name, Available]

Windows

Using zip as archive for windows releases for winget compability.

v0.22 - Running Man

Specs now support a run field enabling cross shell aliases and simple nested custom commands.

Run

run can either contain an alias ([command, arg1, arg2]) which bridges completion or a shell macro ($(echo example)) with custom completions / flag parsing.

name: runnable
description: runnable spec
commands:
  -  name: sub1
     description: alias
     run: "[git, log]"

  -  name: sub2
     description: shell
     run: "$(git show $1)"
     completion:
       positional:
         - - "$(git branch --format '%(refname:short)\t%(subject)\tblue')"
           - "$(git tag --format '%(refname:short)\t\tyellow')"

  -  name: sub3
     description: shell with flags
     run: "$(git log --author \"${C_FLAG_AUTHOR}\" $1)"
     flags:
       -a, --author=: limit to author
     completion:
       flag:
         author: ["$(git shortlog --summary --email HEAD | sed -e 's/^.*\t//' -e 's/ </\t</')"]
       positional:
         - - "$(git branch --format '%(refname:short)\t%(subject)\tblue')"
           - "$(git tag --format '%(refname:short)\t\tyellow')"

PATH

carapace _carapace now prepends ${UserConfigDir}/carapace/bin to PATH unless it already exists.

In nushell this needs to be done manually (see output of carapace _carapace nushell):

let-env PATH = ($env.PATH | prepend "/home/rsteube/.config/carapace/bin")

Shim

It also creates Shims in ${UserConfigDir}/carapace/bin to execute the specs. For unix systems this is a simple shell script, but for windows an embedded binary is used.

#!/bin/sh
carapace --run "/home/rsteube/.config/carapace/specs/runnable.yaml" "$@"

The ${UserConfigDir}/carapace/bin directory is fully managed by carapace and unrelated files within it are removed.

Nargs

Initial support for flags consuming multiple arguments as seen in argparse and various nix commands.

XDG

XDG base directories for XDG_CACHE_HOME and XDG_CONFIG_HOME are now supported.

v0.21 - Heart Transplant

Replaced command traversal with a full rewrite. This provides more fine-grained control and improved logging. It is a complex core component though and while tests are looking good so far some edge cases are likely to fail.

Logging

Improved logging output (export CARAPACE_LOG=1):

// /tmp/carapace/carapace.log
2023/01/29 11:46:28.310133 elvish []string{"/home/rsteube/go/bin/carapace", "_carapace", "elvish", "git", "-C", "../carapace-bin/", "log", "--author", ""}
2023/01/29 11:46:28.310165 elvish traverse called for "git" with args []string{"-C", "../carapace-bin/", "log", "--author", ""}
2023/01/29 11:46:28.310167 elvish executing PreRun for "git" with args []string{"-C", "../carapace-bin/", "log", "--author", ""}
2023/01/29 11:46:28.310185 elvish arg "-C" is a flag
2023/01/29 11:46:28.310207 elvish arg "../carapace-bin/" is a flag argument
2023/01/29 11:46:28.310210 elvish arg "log" is a subcommand
2023/01/29 11:46:28.310211 elvish parsing flags for "git" with args []string{"-C", "../carapace-bin/"}
2023/01/29 11:46:28.310215 elvish traverse called for "log" with args []string{"--author", ""}
2023/01/29 11:46:28.310247 elvish arg "--author" is a flag
2023/01/29 11:46:28.310259 elvish removing arg "--author" since it is a flag missing its argument
2023/01/29 11:46:28.310260 elvish parsing flags for "log" with args []string{}
2023/01/29 11:46:28.310262 elvish completing flag argument of "author" for arg ""

Yargs

Added bridge for yargs:

name: ng
description: CLI tool for Angular
completion:
  positionalany: ["$_bridge.Yargs(ng)"]

v0.20 - Blinkers

Export

Contains breaking changes on the export format. Since there is no backward compability any embedded external carapace based completion must be >= v0.31.0.

Lenient

When environment variable CARAPACE_LENIENT is set (e.g. export CARAPACE_LENIENT=1) unknown flags are ignored. Completers are supposed to be aware of all existing flags but can out of date or not yet working correctly. This can be used to suppress the errors until issues are fixed.

v0.19 - Group Therapy

Error messages

Multiple error message are now supported. In elvish and zsh these are shown separate from the completion values.

Usage message

Added Usage message which defaults to flag description / command usage. This is only supported in elvish and zsh. Since notifications are persistent in elvish it is only shown when there are no values to complete.

Tags

Completion values can now be tagged. Based on this they are grouped in zsh.

Command groups

Subcommands can now be grouped and will be highlighted in different colors.

Group names

Group names can be shown in zsh with the following zstyle.

zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'

Group ordering

Order of the groups can be configured in zsh with the following zstyle.

zstyle ':completion:*:git:*' group-order 'main commands' 'alias commands' 'external commands'

_describe

_describe is now used in zsh which enables the grouping of tags. With this aliased commands and flags are now also arranged side by side.

v0.18 - Spec Galore

Generate

Specs can now be generated from clap based commands with carapace-spec-clap.

Scrape

For advanced completion these can further be converted to Go code with carapace --scrape [spec].

Json Schema

A JSON Schema is now written to ${UserConfigDir}/carapace/schema.json.

It can be used by adding the following header to a user spec:

# yaml-language-server: $schema=../schema.json

Windows

$(shell command) is now executed in Powershell on windows.

v0.17 - Spec-tacular Citizen

Specs are now first-class citizens in carapace. They are integrated on root level and should behave similar to the existing completers (carapace [spec.name] <TAB>).

List

Completers based on Specs are highlighted in shells that support colors (details: carapace --list=json):

Bridge

Using Specs for bridging is from now on the recommended approach. As these are auto-loaded with carapace _carapace and provide support for embedded completion like sudo [spec.name] <TAB>.

Existing completers with the same name will also be overridden. E.g. kubectl (which is currently a bit outdated) can be configured to use the official completer:

# ${UserConfigDir}/carapace/specs/kubectl.yaml
name: kubectl
description: kubectl controls the Kubernetes cluster manager
completion:
  positionalany: ["$_bridge.Cobra(kubectl)"]

Note that bridging adds a slight overhead (~7-9ms?) for each invocation and is limited to supported frameworks / commands.

Plugin

Taking this one step further plugin completion like cargo-[plugin], gh-[plugin], git-[plugin] can now also be defined by Specs.

E.g. the gh-repo-collab extension for github-cli:

# ${UserConfigDir}/carapace/specs/gh-repo-collab.yaml
name: gh-repo-collab
description: manage repository collaborators
commands:
  -
    name: list
    completion:
      positional:
        - ["$_tools.gh.OwnerRepositories"]
  -
    name: add
    flags:
      --permission=: set permission
    completion:
      flag:
        permission: ["pull", "triage", "push", "maintain", "admin\t\tred"]
      positional:
        - ["$_tools.gh.OwnerRepositories"]
        - ["$_tools.gh.Users"]
  -
    name: remove
    completion:
      positional:
        - ["$_tools.gh.OwnerRepositories"]
        - ["$_tools.gh.Users"]

Nushell

With https://github.com/nushell/nushell/pull/6652 (upcoming v0.70.0) the nushell integration is now working on positional arguments. The recommended configuration is equivalent to the example configuration in config.nu:

let carapace_completer = {|spans| 
  carapace $spans.0 nushell $spans | from json
}

let-env config = {
  external_completer: $carapace_completer
}

Be sure to remove the module completions example so that it won't override the carapace completion

v0.16 - Pandoras Box

Switched to a custom pflag fork with adaptions for non-posix variants like long shorthands (e.g. -shorthand).

So far this has been done by patching os.Args which was rather hacky. Modifications to the flag parser are quite complex though, so there might be some issues.

see #1293

Spec files support non-posix flags now as well:

flags:
  -np: non-posix shorthand
  -np, -nonposix:  non-posix shorthand and longhand
  -np, --nonposix: non-posix shorthand mixed with posix longhand

v0.15 - Porcelain Shop

ZSH (this might break some stuff)

Added support for homedir (~) and static named directories. These are not expanded by zsh for the completion function are thus now handled by carapace. Quoting of special characters is now also done in carapace instead of compadd to skip ~ at appropriate times. Edge cases where this doesn't work and some initial bugs regarding special characters not yet being handled correctly are expected.

see #1277

v0.14 - In A Nutshell

Nushell

https://github.com/nushell/nushell/pull/6295 adds support for external completers to nushell. For this config.nu must be updated manually according to the snippet output of carapace. Here's an example with carapace as default completer and a couple custom completers:

let external_completer = {|spans| 
  {
    $spans.0: { carapace $spans.0 nushell $spans | from json } # default                                                             
    example: { example _carapace nushell $spans | from json }                                                                 
    pkill: { carapace --spec '/home/rsteube/.config/carapace/specs/pkill.yaml' nushell $spans | from json }  
    vault: { carapace --bridge vault/posener nushell $spans | from json }
  } | get $spans.0 | each {|it| do $it}
}

let-env config = {
  external_completer: $external_completer
}

v0.13 - Furious

fury.io

DEB and RPM packages are now published to fury.io (Installation)

v0.12 - Preinfusion

Preinvoke

Generic alteration of completion before execution which enables features like directory change in git -C <DIR>:

Spec

Experimental support for simple completions using yaml spec files:

name: example
description:
flags:
  --dynamic=: dynamic value
  -o, --optarg?: optarg flag
  -s, --styled=: styled values
completion:
  flag:
    dynamic: ["$(git branch --all | cut -c 3- | sed 's/$/\t\tblue/')", "static value"]
    optarg: ["first", "second", "third"]
    styled:
    - "blue\tblue\tblue"
    - "cyan\tcyan\tcyan"
  positional:
  -  ["pos1-a", "pos1-b", "pos1-c"]
  -  ["$_files"]

Spec Autoloading

Specs placed in ${UserConfigDir}/carapace/specs/ (UserConfigDir) are now registered with carapace _carapace. File name must be the command to be completed and match ^[0-9a-zA-Z_\-.]+\.yaml$ (sanity check to avoid breakage in scripts).

Custom Macros

Exposed actions as custom macros (list with carapace --macros). Removed the _ prefix from core macros to avoid clashes (e.g. $files, $directories).

Macro Arguments

Arguments are parsed as yaml ($macro(yaml) - e.g.: $_tools.gh.Users({users: true})). Brackets are optional when no argument is passed ($files instead of $files()).

Variable Substitution

Variables are replaced using drone/envsubst for contextual completion:

name: myzip
completion:
  positional:
    - ["$files([.zip])"] # ${C_ARG0}
  positionalany: ["$_fs.ZipFileContents(${C_ARG0})"] # ${C_ARG1},${C_ARG2},...

Flags are only added to env when their value changed (thus: ${C_FLAG_FLAGNAME:-default}):

name: myrefs
flags:
  --tags: list tags # ${C_FLAG_TAGS}
  --localbranches: list local branches # ${C_FLAG_LOCALBRANCHES}
  --commits=: amount of commits # ${C_FLAG_COMMITS}
completion:
  positional:
    - ["$_tools.git.Refs({tags: ${C_FLAG_TAGS:-false}, localbranches: ${C_FLAG_LOCALBRANCHES:-false}, commits: ${C_FLAG_COMMITS:-0}})"] # refs based on flag values with defaults
    - ["$_tools.git.Refs"] # default refs
    - ["$(env)"] # env

v0.11 - Puking Rainbows

This release adds color support for zsh and elvish and thus raises elvish minimum version to v0.18.0.

LS_COLORS

LS_COLORS should now be working correctly - e.g with vivid in elvish:

set E:LS_COLORS = (vivid generate dracula)

Style Config

Styles can now be configured with carapace --style key=value (an empty value restores the default).

Powershell Style

Added color support for powershell.