What causes "cap-vite [vite args...] -- [cap run args...]" in moeru-ai/airi?

Use the documented form: `cap-vite [vite args] -- [cap args]`.

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

Error message

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

What it means

parseCapViteCliArgs requires the argv to contain a literal '--' separator that divides Vite args (left) from Capacitor args (right). When no '--' is present, the function throws the usage string. This is a deliberate contract: cap-vite wraps Vite and forwards extra args to `cap run`, so the boundary must be explicit.

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 27111382b4)

Solutions

Use the documented form: `cap-vite [vite args] -- <ios|android> [cap args]`.
When invoking through pnpm/npm, remember the package manager also consumes a `--`, so you may need two: `pnpm cap-vite -- -- ios`.
Print usage (argv[0] === '--help') when unsure rather than guessing.

Example fix

# before
cap-vite ios

# after
cap-vite -- ios
# or, via pnpm:
pnpm cap-vite -- -- ios

Defensive patterns

Strategy: validation

Validate before calling

if (!argv.includes('--')) {
  console.error('Usage: cap-vite [vite args...] -- <ios|android> [cap run args...]')
  process.exit(1)
}

Type guard

function hasSeparator(argv: string[]): argv is string[] & { __sep: true } {
  return argv.includes('--')
}

Try / catch

try {
  return parseCapViteCliArgs(argv)
}
catch (err) {
  if ((err as Error).message.startsWith('cap-vite')) {
    printHelp()
    process.exit(1)
  }
  throw err
}

Prevention

Always separate Vite args from Capacitor args with a literal '--'.
Remember pnpm/npm also consume a '--', so add an extra one when running through them.
Print --help when unsure of the syntax.

When it happens

Trigger: Running `cap-vite ios` (forgot the --); running `cap-vite build` with no separator because the user assumed Vite-style flags; argv sliced incorrectly before calling parseCapViteCliArgs so the separator was dropped.

Common situations: New users unfamiliar with the required `--` syntax; npm scripts that pass through arguments without preserving the separator; tooling that consumes `--` itself (npm/pnpm use -- to separate too, leading to double-separator confusion).

Related errors

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