moeru-ai/airi · error · Error

cap-vite [vite args...] -- <ios|android> [cap run args...]

Error message

cap-vite [vite args...] -- <ios|android> [cap run args...]

What it means

The cap-vite CLI splits argv at a bare '--': Vite args go before it, `cap run` args after. parseCapViteCliArgs throws the usage string as the error message when argv contains no '--' at all, so the process exits showing exactly how to invoke it.

Solutions

1. Invoke with the separator: `cap-vite -- ios` or `cap-vite --host 0.0.0.0 --port 5173 -- android`
2. Run `cap-vite --help` to see the exact usage and examples
3. In npm scripts, keep the '--' literal: "cap-vite -- ios"

Example fix

# before
$ cap-vite ios   # Error: cap-vite [vite args...] -- <ios|android> [cap run args...]

# after
$ cap-vite -- ios

// Validate before spawning the CLI
if (!argv.includes('--')) {
  console.error(`Usage: ${getCapViteUsage()}`)
  process.exit(1)
}

try {
  const parsed = parseCapViteCliArgs(argv)
}
catch (err) {
  if (err instanceof Error && err.message.startsWith('cap-vite')) {
    console.error(getCapViteCliHelpText()) // message IS the usage line
    process.exit(1)
  }
  throw err
}

When it happens

Trigger: Running `cap-vite ios` or `cap-vite --host 0.0.0.0` — any invocation without a bare '--' token, e.g. because shell quoting or an npm script swallowed it.

Common situations: Muscle memory from `cap run ios` (no separator); npm scripts that forward "$@" when no extra args were passed; quoting the separator inside another string.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• Expected `cap run --list --json` to return a JSON array.
• Missing value for ` `.
• The first `cap run` argument must be `ios` or `android`.
• The first `cap run` argument must be `ios` or `android`.
• Unsupported capture format

AI-assisted analysis of moeru-ai/airi@677329427f (2026-08-18). Data as JSON: /api/errors/224f0776df9cea11. Report an issue: GitHub.

Appendix: source

Thrown at packages/cap-vite/src/cli.ts:44

}

export function getCapViteCliUsage(): string {
  return usage
}

// TODO: CLI and `cap run` argument handling are hand-rolled (see also `resolveCapRunArgs` /
// `hasCapacitorTargetArg` in native.ts). If parsing rules keep growing, adopt a dedicated argv
// library (cac is already a dependency—consider subcommands or a small wrapper) so flags like
// `--target` / `--target=`, env-based defaults, and validation stay in one maintainable layer.

export function parseCapViteCliArgs(argv: string[]): ParsedCapViteCliArgs | null {
  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) {
    return null
  }

  const separatorIndex = argv.indexOf('--')
  if (separatorIndex === -1) {
    throw new Error(usage)
  }

  const capArgs = argv.slice(separatorIndex + 1)
  if (capArgs.length === 0) {
    throw new Error(usage)
  }

  const platform = capArgs[0]
  if (platform !== 'android' && platform !== 'ios') {
    throw new Error(usage)
  }

  return {
    capArgs,
    viteArgs: argv.slice(0, separatorIndex),
  }
}

View on GitHub (pinned to 677329427f)