google-gemini/gemini-cli · error

Invalid scope: ${argv.scope}. Please use one of ${Object.val

Error message

Invalid scope: ${argv.scope}. Please use one of ${Object.values(SettingScope).map((s) => s.toLowerCase()).join(', ')}.

What it means

The 'gemini extensions enable' command's --scope option is validated identically to disable: against lowercased SettingScope enum values (user, workspace, system, systemdefaults, session). An unrecognized value fails the yargs .check() before the handler runs. Unlike disable, enable has no default scope (if omitted, it enables in all scopes).

Source

Thrown at packages/cli/src/commands/extensions/enable.ts:96

  builder: (yargs) =>
    yargs
      .positional('name', {
        describe: 'The name of the extension to enable.',
        type: 'string',
      })
      .option('scope', {
        describe:
          'The scope to enable the extension in. If not set, will be enabled in all scopes.',
        type: 'string',
      })
      .check((argv) => {
        if (
          argv.scope &&
          !Object.values(SettingScope)
            .map((s) => s.toLowerCase())
            .includes(argv.scope.toLowerCase())
        ) {
          throw new Error(
            `Invalid scope: ${argv.scope}. Please use one of ${Object.values(
              SettingScope,
            )
              .map((s) => s.toLowerCase())
              .join(', ')}.`,
          );
        }
        return true;
      }),
  handler: async (argv) => {
    await handleEnable({
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
      name: argv['name'] as string,
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
      scope: argv['scope'] as string,
    });
    await exitCli();
  },

View on GitHub (pinned to 5024443c72)

Solutions

1. Use one of the valid scope values (case-insensitive): user, workspace, system, systemdefaults, session.
2. Omit --scope to enable in all scopes.
3. Run 'gemini extensions enable --help' to see accepted values.

Example fix

// before
gemini extensions enable my-ext --scope global  // invalid

// after
gemini extensions enable my-ext --scope user  // valid

import { SettingScope } from '../../config/settings.js';

function isValidScope(scope: string): boolean {
  return Object.values(SettingScope)
    .map((s) => s.toLowerCase())
    .includes(scope.toLowerCase());
}

// Before calling enable:
if (scope && !isValidScope(scope)) {
  throw new Error(`Use one of: ${Object.values(SettingScope).map((s) => s.toLowerCase()).join(', ')}`);
}

import { SettingScope } from '../../config/settings.js';

function isValidSettingScope(value: string): value is string {
  return Object.values(SettingScope)
    .map((s) => s.toLowerCase())
    .includes(value.toLowerCase());
}

When it happens

Trigger: Running 'gemini extensions enable <name> --scope foo' where 'foo' is not a valid SettingScope value. The check is case-insensitive.

Common situations: Typo in scope name; passing an unsupported scope; confusion between scope names and other identifiers.

Related errors

• Invalid scope: ${argv.scope}. Please use one of ${Object.val
• The source argument must be provided.
• Please include at least one extension name to uninstall as a
• Either an extension name or --all must be provided
• The source argument must be provided.

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/4e007a1f94c9cea9. Report an issue: GitHub.