fix(init): stop specify init hanging on arrow-key pickers in agent harnesses

Agent harnesses often allocate a PTY so isatty is true, but they cannot send
arrow keys. Fail fast when stdin is not a TTY, and add --non-interactive so
scripted init applies defaults instead of hanging.

Fixes #4152.

Author: lllakshit

README.md

@@ -70,6 +70,13 @@ specify init my-project --integration copilot
 cd my-project
 ```
 
+For CI or AI agent harnesses (no keyboard, or a PTY that cannot send arrow keys), pass `--non-interactive` so init never hangs on a picker. Combine with `--force` when initializing into a non-empty directory:
+
+```bash
+specify init my-project --non-interactive --ignore-agent-tools
+specify init --here --force --non-interactive --integration claude
+```
+
 To check for updates or upgrade the installed CLI, use the self-management commands. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options.
 
 ```bash

docs/local-development.md

@@ -2,7 +2,7 @@
 
 This guide shows how to iterate on the `specify` CLI locally without publishing a release or committing to `main` first.
 
-> Scripts are available as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly.
+> Scripts are available as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs (no TTY, or `--non-interactive`) default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly.
 
 ## 1. Clone and Switch Branches
 

docs/quickstart.md

@@ -3,7 +3,7 @@
 This guide will help you get started with Spec-Driven Development using Spec Kit. Throughout, we illustrate each step with a running example: **Taskify**, a small team productivity platform.
 
 > [!NOTE]
-> Automation scripts are provided as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly.
+> Automation scripts are provided as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs (no TTY, or `--non-interactive`) default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly.
 
 Commands are shown here in `/speckit.*` form, but the exact invocation depends on your agent. Some skills-based agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). Use whichever form your agent exposes — the steps are otherwise identical.
 
@@ -43,7 +43,7 @@ uv tool install specify-cli
 specify init taskify   # or: specify init .   to use the current directory
 ```
 
-`init` lets you pick your coding agent interactively, or pass it explicitly with `--integration` (e.g. `--integration copilot`).
+`init` lets you pick your coding agent interactively, or pass it explicitly with `--integration` (e.g. `--integration copilot`). For CI and AI agent harnesses, add `--non-interactive` so unspecified choices use documented defaults instead of hanging on an arrow-key picker.
 
 > [!NOTE]
 > Prefer `pipx`, one-time `uvx` runs, a pinned release, or an offline/air-gapped setup? See the [Installation Guide](installation.md) for all supported methods.

src/specify_cli/_console.py

@@ -151,6 +151,8 @@ def select_with_arrows(
     options: dict[str, str],
     prompt_text: str = "Select an option",
     default_key: str | None = None,
+    *,
+    flag_hint: str | None = None,
 ) -> str:
     """
     Interactive selection using arrow keys with Rich Live display.
@@ -159,13 +161,30 @@ def select_with_arrows(
         options: Dict with keys as option keys and values as descriptions
         prompt_text: Text to show above the options
         default_key: Default option key to start with
+        flag_hint: CLI flag the caller can pass instead of answering this prompt.
+            Included in the error when stdin is not a TTY so the hang is replaced
+            by an actionable message.
 
     Returns:
         Selected option key
     """
     if not options:
         raise ValueError("select_with_arrows() requires at least one option.")
 
+    # readchar.readkey() blocks forever when stdin is not a TTY. Fail immediately
+    # instead of hanging CI jobs and agent harnesses with no keyboard.
+    if not sys.stdin.isatty():
+        console.print(
+            "[red]Error:[/red] Interactive selection requires a terminal "
+            "(stdin is not a TTY). Waiting for arrow keys would hang indefinitely."
+        )
+        if flag_hint:
+            console.print(
+                f"Re-run with [bold]{flag_hint}[/bold] to supply this choice "
+                "non-interactively."
+            )
+        raise typer.Exit(1)
+
     option_keys = list(options.keys())
     if default_key and default_key in option_keys:
         selected_index = option_keys.index(default_key)

src/specify_cli/commands/init.py

@@ -33,6 +33,16 @@ def _stdin_is_interactive() -> bool:
     return sys.stdin.isatty()
 
 
+def _prompts_allowed(non_interactive: bool) -> bool:
+    """Return True when interactive pickers and confirmations may be shown.
+
+    ``--non-interactive`` suppresses prompts even when stdin is a TTY. Agent
+    harnesses often allocate a PTY (so ``isatty()`` is True) but cannot send
+    arrow-key input, which previously hung in ``select_with_arrows``.
+    """
+    return not non_interactive and _stdin_is_interactive()
+
+
 def _ext_spec_is_url(ext_spec: str) -> bool:
     """Return True when *ext_spec* is an http(s) URL rather than a name/path."""
     from urllib.parse import urlparse
@@ -44,7 +54,10 @@ def _ext_spec_is_url(ext_spec: str) -> bool:
 
 
 def _confirm_extension_url_trust(
-    url_specs: list[str], *, trust_override: bool
+    url_specs: list[str],
+    *,
+    trust_override: bool,
+    allow_prompt: bool | None = None,
 ) -> dict[str, bool]:
     """Resolve trust for each URL-based extension before the Live display.
 
@@ -58,7 +71,7 @@ def _confirm_extension_url_trust(
     from rich.panel import Panel
 
     approvals: dict[str, bool] = {}
-    interactive = _stdin_is_interactive()
+    interactive = _stdin_is_interactive() if allow_prompt is None else allow_prompt
     for spec in url_specs:
         if trust_override:
             approvals[spec] = True
@@ -264,6 +277,16 @@ def init(
             "--force",
             help="Force merge/overwrite when using --here (skip confirmation)",
         ),
+        non_interactive: bool = typer.Option(
+            False,
+            "--non-interactive",
+            help=(
+                "Never prompt. Use documented defaults for unspecified "
+                "selections and fail instead of hanging when a choice has no "
+                "safe default. Required for agent harnesses that allocate a "
+                "PTY but cannot send arrow-key input."
+            ),
+        ),
         skip_tls: bool = typer.Option(
             False,
             "--skip-tls",
@@ -324,7 +347,7 @@ def init(
         This command will:
         1. Check that required tools are installed
         2. Let you choose your coding agent integration, or default to Copilot
-           in non-interactive sessions
+           in non-interactive sessions (no TTY, or --non-interactive)
         3. Install bundled Spec Kit templates, scripts, workflow, and shared
            project infrastructure
         4. Set up coding agent integration commands and optional presets
@@ -341,6 +364,8 @@ def init(
             specify init --here --integration vibe      # Initialize with Mistral Vibe support
             specify init --here
             specify init --here --force  # Skip confirmation when current directory not empty
+            specify init my-project --non-interactive  # CI/agent: defaults, no prompts
+            specify init --here --force --non-interactive --integration claude  # Scripted init, no hang
             specify init my-project --integration claude   # Claude installs skills by default
             specify init --here --integration gemini
             specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/"  # Bring your own agent; requires --commands-dir
@@ -416,6 +441,13 @@ def init(
                     console.print(
                         "[cyan]--force supplied: skipping confirmation and proceeding with merge[/cyan]"
                     )
+                elif non_interactive:
+                    console.print(
+                        "[red]Error:[/red] Current directory is not empty and "
+                        "--non-interactive was set. Re-run with "
+                        "[bold]--force[/bold] to merge into it."
+                    )
+                    raise typer.Exit(1)
                 else:
                     # Fold the merge risk into the confirmation prompt rather than
                     # printing it unconditionally first: on the EOF/no-input path
@@ -491,7 +523,7 @@ def init(
                 )
                 raise typer.Exit(1)
             selected_ai = integration
-        elif not _stdin_is_interactive():
+        elif not _prompts_allowed(non_interactive):
             default_integration = resolve_default_init_integration()
             console.print(
                 f"[dim]Non-interactive session detected: defaulting to '{default_integration}'. "
@@ -504,6 +536,7 @@ def init(
                 ai_choices,
                 "Choose your coding agent integration:",
                 resolve_default_init_integration(),
+                flag_hint="--integration <agent>",
             )
 
         if not integration:
@@ -567,11 +600,12 @@ def init(
         else:
             default_script = "ps" if os.name == "nt" else "sh"
 
-            if _stdin_is_interactive():
+            if _prompts_allowed(non_interactive):
                 selected_script = select_with_arrows(
                     SCRIPT_TYPE_CHOICES,
                     "Choose script type (or press Enter)",
                     default_script,
+                    flag_hint="--script sh|ps|py",
                 )
             else:
                 selected_script = default_script
@@ -615,7 +649,9 @@ def init(
             url_specs = [e for e in extensions if _ext_spec_is_url(e)]
             if url_specs:
                 extension_url_approvals = _confirm_extension_url_trust(
-                    url_specs, trust_override=trust_extension_urls
+                    url_specs,
+                    trust_override=trust_extension_urls,
+                    allow_prompt=_prompts_allowed(non_interactive),
                 )
 
         # Disable transient mode on Windows: PowerShell 5.1's legacy console

tests/integrations/test_cli.py

@@ -122,6 +122,127 @@ def fail_select(*_args, **_kwargs):
         data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
         assert data["integration"] == specify_cli.DEFAULT_INIT_INTEGRATION
 
+    def test_noninteractive_flag_skips_pickers_when_stdin_is_a_tty(
+        self, tmp_path, monkeypatch
+    ):
+        """Agent harnesses often allocate a PTY (isatty True) but cannot send
+        arrow keys. ``--non-interactive`` must still skip both pickers and apply
+        documented defaults — the hang reported in #4152.
+        """
+        from typer.testing import CliRunner
+        from specify_cli import app
+        import specify_cli
+        import specify_cli.commands.init as init_mod
+
+        monkeypatch.setattr(init_mod, "_stdin_is_interactive", lambda: True)
+
+        def fail_select(*_args, **_kwargs):
+            raise AssertionError(
+                "--non-interactive must not open select_with_arrows even on a TTY"
+            )
+
+        monkeypatch.setattr(init_mod, "select_with_arrows", fail_select)
+
+        runner = CliRunner()
+        project = tmp_path / "agent-pty"
+        result = runner.invoke(
+            app,
+            ["init", str(project), "--non-interactive", "--ignore-agent-tools"],
+            catch_exceptions=False,
+        )
+
+        assert result.exit_code == 0, result.output
+        assert f"defaulting to '{specify_cli.DEFAULT_INIT_INTEGRATION}'" in result.output
+
+        data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
+        assert data["integration"] == specify_cli.DEFAULT_INIT_INTEGRATION
+
+    def test_noninteractive_flag_here_nonempty_requires_force(
+        self, tmp_path, monkeypatch
+    ):
+        """``--non-interactive`` on a non-empty --here directory must fail fast
+        asking for --force, even when stdin looks like a TTY.
+        """
+        from typer.testing import CliRunner
+        from specify_cli import app
+        import specify_cli.commands.init as init_mod
+
+        monkeypatch.setattr(init_mod, "_stdin_is_interactive", lambda: True)
+
+        def fail_select(*_args, **_kwargs):
+            raise AssertionError("picker must not run under --non-interactive")
+
+        monkeypatch.setattr(init_mod, "select_with_arrows", fail_select)
+
+        project = tmp_path / "nonempty-here-flag"
+        project.mkdir()
+        (project / "existing.txt").write_text("keep me", encoding="utf-8")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(
+                app,
+                [
+                    "init",
+                    "--here",
+                    "--non-interactive",
+                    "--integration",
+                    "copilot",
+                    "--ignore-agent-tools",
+                ],
+                catch_exceptions=False,
+            )
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 1, result.output
+        assert "--force" in result.output
+        assert "--non-interactive" in result.output
+        assert (project / "existing.txt").read_text(encoding="utf-8") == "keep me"
+
+    def test_noninteractive_flag_here_force_completes_without_script_flag(
+        self, tmp_path, monkeypatch
+    ):
+        """The #4152 reproduction: ``--here --force --integration`` without
+        ``--script`` must not hang on the script picker when --non-interactive
+        is set, even if stdin is a TTY.
+        """
+        from typer.testing import CliRunner
+        from specify_cli import app
+        import specify_cli.commands.init as init_mod
+
+        monkeypatch.setattr(init_mod, "_stdin_is_interactive", lambda: True)
+
+        def fail_select(*_args, **_kwargs):
+            raise AssertionError("script picker must not run under --non-interactive")
+
+        monkeypatch.setattr(init_mod, "select_with_arrows", fail_select)
+
+        project = tmp_path / "here-force-agent"
+        project.mkdir()
+        (project / "existing.txt").write_text("keep me", encoding="utf-8")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = CliRunner().invoke(
+                app,
+                [
+                    "init",
+                    "--here",
+                    "--force",
+                    "--non-interactive",
+                    "--integration",
+                    "claude",
+                    "--ignore-agent-tools",
+                ],
+                catch_exceptions=False,
+            )
+        finally:
+            os.chdir(old_cwd)
+
+        assert result.exit_code == 0, result.output
+        assert (project / ".specify" / "init-options.json").exists()
+
     def test_noninteractive_init_honors_default_integration_env_var(
         self, tmp_path, monkeypatch
     ):
@@ -164,7 +285,7 @@ def test_interactive_init_picker_default_honors_env_var(
 
         captured = {}
 
-        def fake_select(options, prompt_text=None, default_key=None):
+        def fake_select(options, prompt_text=None, default_key=None, **_kwargs):
             # Only capture the integration picker (not the script picker).
             if "Choose your coding agent integration" in (prompt_text or ""):
                 captured["default_key"] = default_key

tests/test_console_imports.py

@@ -44,6 +44,51 @@ def test_select_with_arrows_raises_on_empty_options():
         select_with_arrows({})
 
 
+def test_select_with_arrows_fails_fast_when_stdin_is_not_a_tty(monkeypatch, capsys):
+    """Regression for #4152: a missing TTY must error, not block on readchar."""
+    import sys
+
+    import pytest
+    import typer
+
+    def fail_readkey():
+        raise AssertionError("readkey must not be called when stdin is not a TTY")
+
+    monkeypatch.setattr(sys.stdin, "isatty", lambda: False)
+    monkeypatch.setattr("specify_cli._console.readchar.readkey", fail_readkey)
+
+    with pytest.raises(typer.Exit) as exc:
+        select_with_arrows(
+            {"copilot": "GitHub Copilot"},
+            "Choose your coding agent integration:",
+            "copilot",
+            flag_hint="--integration <agent>",
+        )
+
+    assert exc.value.exit_code == 1
+    captured = capsys.readouterr().out
+    assert "stdin is not a TTY" in captured
+    assert "--integration <agent>" in captured
+
+
+def test_select_with_arrows_tty_check_does_not_call_readkey_without_hint(monkeypatch):
+    import sys
+
+    import pytest
+    import typer
+
+    def fail_readkey():
+        raise AssertionError("readkey must not be called when stdin is not a TTY")
+
+    monkeypatch.setattr(sys.stdin, "isatty", lambda: False)
+    monkeypatch.setattr("specify_cli._console.readchar.readkey", fail_readkey)
+
+    with pytest.raises(typer.Exit) as exc:
+        select_with_arrows({"a": "Option A"}, "Pick one")
+
+    assert exc.value.exit_code == 1
+
+
 def test_step_tracker_refresh_error_is_logged(caplog):
     """Regression: _maybe_refresh must log exceptions instead of silently swallowing."""
     tracker = StepTracker("test")