can1357/oh-my-pi · error · CliUsageError

setup --check/--json requires a COMPONENT (python|speech)

Error message

setup --check/--json requires a COMPONENT (python|speech)

What it means

omp setup's --check and --json flags interrogate a specific COMPONENT (python or speech). Without a component there is nothing to probe, so the command throws a CliUsageError (exiting 1 to stderr) rather than printing help at exit 0 — this keeps scripted --json health checks from silently 'succeeding'.

Source

Thrown at packages/coding-agent/src/commands/setup.ts:55

			description: "Optional component to install",
			required: false,
			options: COMPONENTS,
		}),
	};

	static flags = {
		check: Flags.boolean({ char: "c", description: "Check if dependencies are installed" }),
		json: Flags.boolean({ description: "Output status as JSON" }),
	};

	async run(): Promise<void> {
		const { args, flags } = await this.parse(Setup);
		if (!args.component) {
			if (flags.check || flags.json) {
				// A check/JSON request with no COMPONENT has nothing to probe. Emit a
				// usage error on stderr (exit 1) rather than printing help to stdout at
				// exit 0, which would mask failures in scripted `--json` health checks.
				throw new CliUsageError("setup --check/--json requires a COMPONENT (python|speech)");
			}
			await runOnboardingSetup();
			return;
		}
		const cmd: SetupCommandArgs = {
			component: args.component as SetupComponent,
			flags: {
				json: flags.json,
				check: flags.check,
			},
		};
		await initTheme();
		await runSetupCommand(cmd);
	}
}

View on GitHub (pinned to 9690622007)

Solutions

Specify the component: omp setup --check python or omp setup --json speech
Fix the CI/script variable that supplies COMPONENT so it is non-empty
If you only wanted interactive setup, run plain 'omp setup' with no flags

Example fix

// before
omp setup --check
// after
omp setup --check python

Defensive patterns

Strategy: validation

Validate before calling

if ((flags.check || flags.json) && !component) {
  throw new Error('setup --check/--json requires a COMPONENT (python|speech)');
}

Type guard

function isSetupComponent(c) { return c === 'python' || c === 'speech'; }

Try / catch

try {
  await Setup.run(rawArgs);
} catch (err) {
  if (err instanceof CliUsageError && err.message.includes('requires a COMPONENT')) {
    console.error('Usage: omp setup --check|--json <python|speech>');
    process.exitCode = 1;
  } else throw err;
}

Prevention

Always pass the component with --check/--json in scripts
Fail fast on empty component variables in CI templates
Use plain 'omp setup' for interactive onboarding, flags only for scripted checks

When it happens

Trigger: Running 'omp setup --check' or 'omp setup --json' with no COMPONENT argument; CI scripts templated with an empty component variable.

Common situations: Health-check scripts calling setup --json expecting machine output but forgetting which component to probe; shell variable for the component left empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/5fd94fedb65cc22d. Report an issue: GitHub.