github/spec-kit · error · ValueError

{env_name} is not parseable as a POSIX-quoted command line (

Error message

{env_name} is not parseable as a POSIX-quoted command line (value: {extra!r}). shlex reported: {exc}. Use single or double quotes to group multi-word values, e.g. {env_name}='--flag "value with spaces"'.

What it means

IntegrationBase reads per-integration extra CLI args from the environment variable SPECKIT_INTEGRATION_<KEY_UPPER>_EXTRA_ARGS (hyphens in the key become underscores) and parses it with shlex.split so quoted multi-word values work. If shlex raises ValueError — in practice an unbalanced single or double quote — the integration setup aborts with this message, echoing both the raw value and shlex's complaint.

Source

Thrown at src/specify_cli/integrations/base.py:304

        Useful in CI / non-interactive contexts where the spawned agent
        needs flags that change its prompt-handling behaviour.
        Default behaviour (env var unset or whitespace-only) is a no-op
        — *args* is unchanged. Multi-token values are parsed via
        `shlex.split`.

        See issue #2595.
        """
        env_name = (
            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXTRA_ARGS"
        )
        extra = os.environ.get(env_name, "").strip()
        if not extra:
            return
        try:
            tokens = shlex.split(extra)
        except ValueError as exc:
            raise ValueError(
                f"{env_name} is not parseable as a POSIX-quoted command line "
                f"(value: {extra!r}). shlex reported: {exc}. "
                f"Use single or double quotes to group multi-word values, e.g. "
                f'{env_name}=\'--flag "value with spaces"\'.'
            ) from exc
        args.extend(tokens)

    def build_command_invocation(self, command_name: str, args: str = "") -> str:
        """Build the native slash-command invocation for a Spec Kit command.

        The CLI tools discover and execute commands from installed files
        on disk.  This method builds the invocation string the CLI
        expects — e.g. ``"/speckit.specify my-feature"`` for markdown
        agents or ``"/speckit-specify my-feature"`` for skills agents.

        *command_name* may be a full dotted name like
        ``"speckit.specify"``, an extension command like
        ``"speckit.git.commit"``, or a bare stem like ``"specify"``.

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Balance the quotes in the variable value, grouping multi-word arguments: SPECKIT_INTEGRATION_X_EXTRA_ARGS="--flag 'value with spaces'".
2. Escape embedded quotes with the opposite quote type or backslashes per shlex rules.
3. Print the variable to inspect it: `echo "$SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS"` — the raw value appears in the error message (value: ...).

Example fix

# before
export SPECKIT_INTEGRATION_MY_AGENT_EXTRA_ARGS='--flag "unbalanced'
# after
export SPECKIT_INTEGRATION_MY_AGENT_EXTRA_ARGS='--flag "balanced value"'

import os, shlex

name = "SPECKIT_INTEGRATION_MY_AGENT_EXTRA_ARGS"
raw = os.environ.get(name, "")
if raw:
    try:
        shlex.split(raw)
    except ValueError as e:
        raise SystemExit(f"fix quoting in {name}: {e}") from None

try:
    integration.setup(...)
except ValueError as exc:
    if "EXTRA_ARGS" in str(exc) and "shlex" in str(exc):
        # surface the exact variable and value; fix the environment and retry
        raise SystemExit(str(exc)) from None
    raise

When it happens

Trigger: Setting e.g. SPECKIT_INTEGRATION_CLAUDE_AGENT_EXTRA_ARGS='--flag "value with spaces (missing close quote)' — any value where a quote opens but never closes; also unmatched quotes introduced by shell interpolation when the variable is exported unquoted.

Common situations: Passing JSON or parenthesized strings in EXTRA_ARGS without balancing quotes; CI pipelines that build the env var dynamically and drop a trailing quote; values containing apostrophes (e.g. don't) inside a single-quoted string.

Related errors

• {type(self).__name__}.config is not set.
• {type(self).__name__}.config is missing required 'folder' en
• Failed to parse preset manifest {manifest_path}: {exc}
• Unknown template composition strategy '{strategy}' in {path}
• AzureDevOpsAuth does not support auth scheme {auth_scheme!r}

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/156dc7b9c50f8cec. Report an issue: GitHub.