---
title: Shell completion
description: Enable tab completion for the varlock CLI in bash, zsh, fish, and PowerShell
---

import { Tabs, TabItem } from "@astrojs/starlight/components";
import ExecCommandWidget from "@/components/ExecCommandWidget.astro";

The varlock CLI supports tab completion for subcommands and flags. There are two ways to get it, depending on how varlock is installed:

- **`varlock` on your PATH** (standalone binary or global npm install): install varlock's own completion script. See [Setup](#setup) below.
- **varlock as a local project dependency** (run via `pnpm exec`, `npm exec`, `bun x`, scripts, etc.): completion comes from your package manager's completion instead. See [Local project installs](#local-project-installs).

## Setup

Use this when `varlock` is on your PATH, installed via the [standalone binary](/getting-started/installation/#as-a-standalone-binary) (Homebrew or cURL) or a global npm install (`npm install -g varlock`).

Generate a completion script with `varlock complete <shell>`, then install it using the instructions below for your shell.

After upgrading varlock, re-run `varlock complete <shell>` if new commands or flags were added.

<Tabs syncKey="shell">
  <TabItem label="Zsh">
    Zsh completion files must be named with a leading underscore:

    ```bash
    mkdir -p ~/.zsh/completions
    echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
    echo 'autoload -U compinit && compinit' >> ~/.zshrc
    varlock complete zsh > ~/.zsh/completions/_varlock
    source ~/.zshrc
    ```
  </TabItem>
  <TabItem label="Bash">
    ```bash
    mkdir -p ~/.local/share/bash-completion/completions
    varlock complete bash > ~/.local/share/bash-completion/completions/varlock
    source ~/.bashrc
    ```
  </TabItem>
  <TabItem label="Fish">
    ```bash
    mkdir -p ~/.config/fish/completions
    varlock complete fish > ~/.config/fish/completions/varlock.fish
    ```

    Fish loads completions automatically. Restart your shell or open a new terminal to pick them up.
  </TabItem>
  <TabItem label="PowerShell">
    ```powershell
    varlock complete powershell >> $PROFILE
    . $PROFILE
    ```
  </TabItem>
</Tabs>

## Local project installs

When varlock is only a local dependency (not on your PATH), you run it through your package manager: `pnpm exec varlock …`, `npm exec varlock …`, `bun x varlock …`, or a `package.json` script. In that case completion comes from **your package manager's** completion, which delegates to varlock automatically. You don't install anything varlock-specific; varlock already speaks the completion protocol that package-manager completion uses.

Set up completion for your package manager once, using [`@bomb.sh/tab`](https://bomb.sh/docs/tab/#package-manager-completions):

```bash
npm install -g @bomb.sh/tab

# zsh (swap in npm / yarn / bun and bash / fish / powershell as needed)
echo 'source <(tab pnpm zsh)' >> ~/.zshrc
source ~/.zshrc
```

Now `pnpm exec varlock <TAB>`, `pnpm dlx varlock <TAB>`, and bare `pnpm varlock <TAB>` complete varlock's subcommands and flags. The same works for `npm exec`, `yarn`, and `bun x`.

:::caution[`npx` / `bunx` aren't covered]
Completion is registered against the package-manager binary (`npm`, `pnpm`, `yarn`, `bun`). `npx` and `bunx` are separate commands with no completion of their own, so `npx varlock <TAB>` / `bunx varlock <TAB>` won't complete. Use `npm exec varlock` / `bun x varlock` instead.
:::

## What gets completed

Tab completion covers varlock **subcommands** and **static flags** (including enum choices like `load --format`).

Dynamic values, such as env var names from your schema, are not completed yet.

## Troubleshooting

If completions stop working after an upgrade, regenerate the script:

<ExecCommandWidget command="varlock complete zsh > ~/.zsh/completions/_varlock" />

Replace `zsh` and the output path with your shell and install location.
