{"record":{"id":"156dc7b9c50f8cec","repo":"github/spec-kit","slug":"env-name-is-not-parseable-as-a-posix-quoted-comm","errorCode":null,"errorMessage":"{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\"'.","messagePattern":"(.+?) is not parseable as a POSIX-quoted command line \\(value: (.+?)\\)\\. shlex reported: (.+?)\\. Use single or double quotes to group multi-word values, e\\.g\\. (.+?)='--flag \"value with spaces\"'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/integrations/base.py","lineNumber":304,"sourceCode":"\n        Useful in CI / non-interactive contexts where the spawned agent\n        needs flags that change its prompt-handling behaviour.\n        Default behaviour (env var unset or whitespace-only) is a no-op\n        — *args* is unchanged. Multi-token values are parsed via\n        `shlex.split`.\n\n        See issue #2595.\n        \"\"\"\n        env_name = (\n            f\"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXTRA_ARGS\"\n        )\n        extra = os.environ.get(env_name, \"\").strip()\n        if not extra:\n            return\n        try:\n            tokens = shlex.split(extra)\n        except ValueError as exc:\n            raise ValueError(\n                f\"{env_name} is not parseable as a POSIX-quoted command line \"\n                f\"(value: {extra!r}). shlex reported: {exc}. \"\n                f\"Use single or double quotes to group multi-word values, e.g. \"\n                f'{env_name}=\\'--flag \"value with spaces\"\\'.'\n            ) from exc\n        args.extend(tokens)\n\n    def build_command_invocation(self, command_name: str, args: str = \"\") -> str:\n        \"\"\"Build the native slash-command invocation for a Spec Kit command.\n\n        The CLI tools discover and execute commands from installed files\n        on disk.  This method builds the invocation string the CLI\n        expects — e.g. ``\"/speckit.specify my-feature\"`` for markdown\n        agents or ``\"/speckit-specify my-feature\"`` for skills agents.\n\n        *command_name* may be a full dotted name like\n        ``\"speckit.specify\"``, an extension command like\n        ``\"speckit.git.commit\"``, or a bare stem like ``\"specify\"``.","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/integrations/base.py#L286-L322","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Balance the quotes in the variable value, grouping multi-word arguments: SPECKIT_INTEGRATION_X_EXTRA_ARGS=\"--flag 'value with spaces'\".","Escape embedded quotes with the opposite quote type or backslashes per shlex rules.","Print the variable to inspect it: `echo \"$SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS\"` — the raw value appears in the error message (value: ...)."],"exampleFix":"# before\nexport SPECKIT_INTEGRATION_MY_AGENT_EXTRA_ARGS='--flag \"unbalanced'\n# after\nexport SPECKIT_INTEGRATION_MY_AGENT_EXTRA_ARGS='--flag \"balanced value\"'","handlingStrategy":"validation","validationCode":"import os, shlex\n\nname = \"SPECKIT_INTEGRATION_MY_AGENT_EXTRA_ARGS\"\nraw = os.environ.get(name, \"\")\nif raw:\n    try:\n        shlex.split(raw)\n    except ValueError as e:\n        raise SystemExit(f\"fix quoting in {name}: {e}\") from None","typeGuard":null,"tryCatchPattern":"try:\n    integration.setup(...)\nexcept ValueError as exc:\n    if \"EXTRA_ARGS\" in str(exc) and \"shlex\" in str(exc):\n        # surface the exact variable and value; fix the environment and retry\n        raise SystemExit(str(exc)) from None\n    raise","preventionTips":["Pre-validate EXTRA_ARGS values with shlex.split before running specify.","Build the variable in scripts with shell arrays or argparse-style lists instead of string concatenation.","Remember hyphens in the integration key become underscores in the variable name."],"tags":["environment","configuration","shell-quoting","developer-error"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}