zsh

Document Zsh completion utilities including compinit, _arguments, and ZLE integration.

1.4k|36|Updated Mar 17, 2020
One-click install
npx skills add https://github.com/carapace-sh/carapace --skill zsh-carapace-sh
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: zsh
Source: https://github.com/carapace-sh/carapace/tree/main/skills/zsh
Command: npx skills add https://github.com/carapace-sh/carapace --skill zsh-carapace-sh

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Provides a comprehensive reference to understand, implement, and troubleshoot Zsh command-line completions and related internals (compinit, _arguments, and ZLE) so developers can build robust, predictable user experiences.

Core Features & Use Cases

  • Detailed explanations of core utilities (compinit, compdef, _arguments, _describe, _values, _files, zstyle) and their interactions in the Zsh completion pipeline.
  • Practical usage scenarios showing how to customize completion behavior for commands, subcommands, and options across interactive shells.
  • Cross-reference guidance with related topics like startup files, fpath, and autoloading to streamline integration in real projects.

Quick Start

Create a minimal example showing how to implement a simple completion for a fictitious command using _arguments.

Frequently Asked Questions about zsh

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create custom zsh completions for a command using _arguments?

Zsh completions use _arguments to define command options and arguments. You specify flags, values, and help texts within this function, then register the script via compdef to enable interactive shell completion for your specific command.

What is compinit and how does it work with fpath in zsh?

Compinit initializes the zsh completion system by loading completion functions from directories listed in the fpath array. It associates commands with their corresponding completion scripts using compdef, making interactive completion available in your shell session.

How do I customize zsh completion behavior using zstyle?

Zstyle configures zsh completion behavior by defining context-specific patterns and styles. You set rules for menu selection, grouping, descriptions, and matching criteria, allowing fine-grained control over how completion candidates display and interact with user input.

Can I use _describe to generate completion lists for subcommands?

_describe generates completion candidates from predefined arrays of option names and descriptions. It is ideal for static command lists, providing labeled completion suggestions directly within the zsh completion pipeline for subcommands or fixed argument sets.

Why is my zsh completion script not loading on shell startup?

Zsh completion scripts require correct fpath configuration before compinit runs. Ensure the completion directory is added to fpath in your startup files, and that compinit is called afterward to properly autoload and register the completion functions.

How does ZLE integration affect zsh command-line completion?

ZLE integration allows custom widgets and key bindings to trigger or modify the completion process. By binding keys to zle completion widgets, you can control how completion candidates are displayed and inserted during interactive shell input.