CLI Auto-Completion

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/completion.ts
• src/lib/completion.ts
• tests/commands/completion.test.ts
• package.json
• skills/resend-cli/SKILL.md

CLI Auto-Completion provides shell-specific scripts that enable tab-completion for resend commands, aliases, and options. The system extracts the command hierarchy from the application's definition and formats it for various terminal environments.

Users can generate scripts manually for evaluation or use the --install flag to automate the configuration of their shell profiles.

Sources: src/commands/completion.ts:184-210, skills/resend-cli/SKILL.md:104

Supported Environments

The completion module supports four primary shell environments. It identifies the active shell by inspecting environment variables like $SHELL or $PSModulePath.

Shell	Detection Method	Profile Path (Unix/macOS)	Profile Path (Windows)
Bash	basename($SHELL) === 'bash'	~/.bashrc or ~/.bash_profile	N/A
Zsh	basename($SHELL) === 'zsh'	~/.zshrc	N/A
Fish	basename($SHELL) === 'fish'	~/.config/fish/completions/	N/A
PowerShell	$PSModulePath presence	~/.config/powershell/...	~/Documents/PowerShell/...

Sources: src/commands/completion.ts:21-39, src/commands/completion.ts:60-85

Architecture and Data Flow

The completion system follows a three-step process: tree collection, tree flattening, and script generation.

1. Collection: The collectCommandTree function traverses the commander program instance to build a recursive CommandNode structure.
2. Flattening: flattenTree converts the recursive structure into a flat list of command paths for easier lookup during completion.
3. Generation: Shell-specific functions transform the flattened data into script syntax unique to each shell.

Command Tree Processing Flow

The diagram shows how the internal CLI definition is transformed into various shell scripts. Sources: src/lib/completion.ts:28-100

Core Data Structures

The system represents the CLI structure using interfaces that capture names, descriptions, and value requirements.

OptionNode

Describes individual flags.

• long: The long-form flag (e.g., --api-key).
• short: The short-form flag (e.g., -p).
• takesValue: Boolean indicating if the flag requires an argument.
• choices: Optional array of permitted values.

CommandNode

Describes commands and their hierarchy.

• subcommands: Array of child CommandNode objects.
• aliases: Alternative names for the command (e.g., ls for list).
• options: Array of OptionNode objects specific to this command.

Sources: src/lib/completion.ts:3-26, tests/commands/completion.test.ts:70-98

Logic and Implementation

Command Extraction

The system filters out hidden commands and options during collection to ensure users only see public APIs in their completion suggestions.

Sources: src/lib/completion.ts:31-34, src/lib/completion.ts:42-44

Value Flag Handling

Generator functions identify "value flags" that require arguments. For flags without predefined choices, the scripts typically fall back to file completion.

This sequence illustrates how the generated script handles value flags during interactive use. Sources: src/lib/completion.ts:161-170, tests/commands/completion.test.ts:145-155

Installation Procedure

When you run resend completion --install, the CLI performs the following actions:

1. Detect Shell: Resolves the target shell from the environment or user prompt.
2. Generate Script: Builds the completion logic for the detected shell.
3. Write Files:
   • Zsh: Writes to ~/.zsh/completions/_resend and updates fpath in ~/.zshrc.
   • Fish: Writes directly to the fish completions directory.
   • Bash/PowerShell: Appends an eval or Invoke-Expression command to the user's profile.
4. Verification: Uses a # resend shell completion marker to prevent duplicate installations.

Sources: src/commands/completion.ts:105-182

Summary

The CLI Auto-Completion system ensures a seamless developer experience by providing intelligent tab-discovery for the resend command. By abstracting the complex command hierarchy into a portable CommandNode tree, the project maintains consistent completion logic across Bash, Zsh, Fish, and PowerShell.