affaan-m/ECC · error · Error

Invalid terminal name; use a simple adapter name such as…

Error message

Invalid terminal name; use a simple adapter name such as wezterm.

What it means

validateTerminalName enforces that the --terminal CLI value is a simple adapter identifier matching /^[A-Za-z0-9][A-Za-z0-9_.-]*$/. It must start with an alphanumeric and contain only letters, digits, underscore, dot, or hyphen. Anything containing slashes, spaces, or other characters is rejected to prevent path injection into adapter lookup.

Solutions

1. Pass only the adapter name, e.g. `--terminal wezterm`.
2. Move the full command to the executable/args position after `--` instead of embedding it in --terminal.
3. Remove illegal characters (slashes, spaces, quotes) from the value.

Example fix

// before
node open-terminal.js --terminal "/usr/local/bin/wezterm start"
// after
node open-terminal.js --terminal wezterm -- /usr/local/bin/wezterm start

const isValidTerminal = (v) => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(v);
if (!isValidTerminal(args.terminal)) throw new Error('terminal must be a simple adapter name');

function isSimpleAdapterName(v) {
  return typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(v);
}

try {
  parseArgs(process.argv);
} catch (e) {
  if (/Invalid terminal name/.test(e.message)) {
    console.error('Usage: --terminal accepts only a simple adapter name, e.g. wezterm');
  } else throw e;
}

When it happens

Trigger: Passing `--terminal "/usr/bin/wezterm"`, `--terminal "my terminal"`, `--terminal "wezterm --class foo"`, or an empty/leading-dash value to open-terminal.js.

Common situations: Users pasting a full executable path or command line into --terminal when they should pass a simple name like `wezterm` and use `--executable`/positional args after `--` for the command.

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

• all overlays must be readable local files
• all takes must be readable local files
• Arguments must not contain NUL bytes.
• asset name must be a simple filename stem (letters, digits…
• At least one guided harness must be selected

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/d98435d929947e3a. Report an issue: GitHub.

Appendix: source

Thrown at skills/terminal-opener/scripts/open-terminal.js:42

  --standalone       Alias for --recover.
  --detect           Check whether the selected terminal can be launched.
  --launch           Explicitly open the terminal (the default only prints a plan).
  --dry-run          Explicitly print the launch plan without opening a terminal.
  --json             Emit the plan, capability, or launch result as JSON.
  --help, -h         Show this help.

Always pass the executable and arguments as separate entries after --.
Shell command strings are not accepted.
`;
}

function isAbsolutePath(value) {
  return path.isAbsolute(value) || path.win32.isAbsolute(value);
}

function validateTerminalName(value) {
  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value)) {
    throw new Error('Invalid terminal name; use a simple adapter name such as wezterm.');
  }
}

function validateCwd(value) {
  if (value.includes('\0')) throw new Error('--cwd must not contain a NUL byte.');
  if (!isAbsolutePath(value)) throw new Error('--cwd must be an absolute path.');
}

function validateExecutable(value) {
  if (!value || /[\0\r\n]/.test(value)) {
    throw new Error('Executable must be a non-empty argv entry without control bytes.');
  }

  const whitespaceIndex = value.search(/\s/);
  const separatorIndexes = [value.indexOf('/'), value.indexOf('\\')].filter(index => index >= 0);
  const firstSeparatorIndex = separatorIndexes.length > 0 ? Math.min(...separatorIndexes) : -1;
  const resemblesExecutablePath = isAbsolutePath(value)
    || (firstSeparatorIndex >= 0 && (whitespaceIndex < 0 || firstSeparatorIndex < whitespaceIndex));

View on GitHub (pinned to 8321021c54)