angular/angular-cli · error · Error

`$SHELL` environment variable not set. Angular CLI autocompl

Error message

`$SHELL` environment variable not set. Angular CLI autocompletion only supports Bash or Zsh. If you're on Windows, Cmd and Powershell don't support command autocompletion, but Git Bash or Windows Subsystem for Linux should work, so please try again in one of those environments.

What it means

Angular CLI's `initializeAutocomplete` sets up shell autocompletion by first reading the `$SHELL` environment variable to determine which shell the user runs. If `$SHELL` is unset, the CLI cannot detect a supported shell (Bash or Zsh) and throws this error instead of guessing. The message also clarifies that Windows Cmd/PowerShell are unsupported and suggests Git Bash or WSL.

Source

Thrown at packages/angular/cli/src/utilities/completion.ts:207

      .join(' ')
      .trim(),
    true,
  );

  return autocomplete;
}

/**
 * Sets up autocompletion for the user's terminal. This attempts to find the configuration file for
 * the current shell (`.bashrc`, `.zshrc`, etc.) and append a command which enables autocompletion
 * for the Angular CLI. Supports only Bash and Zsh. Returns whether or not it was successful.
 * @return The full path of the configuration file modified.
 */
export async function initializeAutocomplete(): Promise<string> {
  // Get the currently active `$SHELL` and `$HOME` environment variables.
  const shell = env['SHELL'];
  if (!shell) {
    throw new Error(
      '`$SHELL` environment variable not set. Angular CLI autocompletion only supports Bash or' +
        " Zsh. If you're on Windows, Cmd and Powershell don't support command autocompletion," +
        ' but Git Bash or Windows Subsystem for Linux should work, so please try again in one of' +
        ' those environments.',
    );
  }
  const home = env['HOME'];
  if (!home) {
    throw new Error(
      '`$HOME` environment variable not set. Setting up autocompletion modifies configuration files' +
        ' in the home directory and must be set.',
    );
  }

  // Get all the files we can add `ng completion` to which apply to the user's `$SHELL`.
  const runCommandCandidates = getShellRunCommandCandidates(shell, home);
  if (!runCommandCandidates) {
    throw new Error(

View on GitHub (pinned to bb72145f9a)

Solutions

Run the command from Bash or Zsh where `$SHELL` is set (e.g. `bash -lc 'ng completion'`).
On Windows, use Git Bash or Windows Subsystem for Linux instead of Cmd/PowerShell.
Export the variable explicitly if your environment strips it: `export SHELL=$(which bash)` before invoking the CLI.
Skip autocompletion setup with `NG_CLI_COMPLETION=false` if you do not need it.

Example fix

// before (fails in sanitized env)
ng completion
// after
export SHELL=$(which bash)
ng completion

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.SHELL) {
  console.warn('Skipping ng completion: $SHELL is not set.');
} else {
  // safe to invoke ng completion
}

Type guard

function hasShellEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { SHELL: string } {
  return typeof env.SHELL === 'string' && env.SHELL.length > 0;
}

Try / catch

try {
  await ngCompletionSetup();
} catch (e) {
  if (e instanceof Error && e.message.includes('$SHELL` environment variable not set')) {
    // fall back: skip autocompletion setup
  } else { throw e; }
}

Prevention

Always invoke ng completion from an interactive Bash/Zsh session.
On Windows use Git Bash or WSL, never Cmd/PowerShell.
Set SHELL explicitly in CI containers (e.g. ENV SHELL=/bin/bash).
Set NG_CLI_COMPLETION=false in environments where completion setup is unwanted.

When it happens

Trigger: Calling `ng completion` (or code paths `run`/`considerSettingUpAutocompletion` that invoke `initializeAutocomplete`) in an environment where the `SHELL` environment variable is not defined in `process.env`.

Common situations: Windows Cmd or PowerShell sessions (which never set `$SHELL`), spawning the CLI from a GUI app or IDE terminal that strips environment variables, running via `env -i` or a sanitized CI container, or cron/systemd jobs with a minimal env.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/a064367d0d092518. Report an issue: GitHub.