Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

feat: allow overriding default init integration via SPECKIT_INTEGRATION_DEFAULT (#3952)

Manfred Rieme9ffc9d8e7b4
diff --git a/docs/reference/core.md b/docs/reference/core.md
index fad62fc36..3318264b4 100644
--- a/docs/reference/core.md
+++ b/docs/reference/core.md
@@ -25,7 +25,7 @@ Creates a new Spec Kit project with the necessary directory structure, templates
Use `<project_name>` to create a new directory, or `--here` (or `.`) to initialize in the current directory. If the directory already has files, use `--force` to merge without confirmation.
-When `--integration` is omitted, interactive terminals prompt you to choose an integration. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot; pass `--integration <key>` to choose a different integration explicitly.
+When `--integration` is omitted, interactive terminals prompt you to choose an integration. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot; pass `--integration <key>` to choose a different integration explicitly, or set `SPECKIT_INTEGRATION_DEFAULT` to change the fallback (see [Environment Variables](#environment-variables)).
### Examples
@@ -50,6 +50,7 @@ specify init my-project --integration copilot --preset compliance
| Variable | Description |
| ----------------- | ------------------------------------------------------------------------ |
+| `SPECKIT_INTEGRATION_DEFAULT` | Override the fallback integration used by `specify init` when `--integration` is omitted (interactive prompt default and non-interactive fallback). Set it to any registered integration key (e.g. `gemini`, `claude`). An unrecognized value is ignored with a warning and the built-in default (`copilot`) is used. An explicit `--integration <key>` always takes precedence. |
| `SPECIFY_INIT_DIR` | Target a member project from outside its directory (e.g. a monorepo root) without `cd`, for non-interactive / CI use. Set it to the **project root** β€” the directory *containing* `.specify/` (relative paths resolve against the current directory). The path must exist and contain `.specify/`, otherwise the command errors and does **not** fall back to the current directory. Resolved once in the core root helper (`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell), so it is honored by the core feature scripts (`/speckit.plan`, `/speckit.tasks`, …) and the Git extension's feature-branch creation, which inherit it. The `specify` CLI applies the **same** validation rules to every project-scoped subcommand (`specify integration …`, `specify extension …`, `specify workflow …`, `specify preset …`, and the rest that operate on a `.specify/` project), so those can target a member project too. When unset, Bash/PowerShell helpers keep their existing upward search; the `specify` CLI keeps its project-scoped resolver cwd-only unless a command explicitly defines broader detection (for example, bundle commands). |
| `SPECIFY_FEATURE_DIRECTORY` | Override the active feature directory *within* the resolved project (takes precedence over `.specify/feature.json`). Relative paths resolve under the project root. Combine with `SPECIFY_INIT_DIR` to pick both the project and the feature non-interactively. |
| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches. Must be set in the context of the agent prior to using `/speckit.plan` or follow-up commands. |
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index 33bb8f5c2..f8afcf4f5 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -77,7 +77,9 @@ from ._version import (
from ._agent_config import (
AGENT_CONFIG as AGENT_CONFIG,
DEFAULT_INIT_INTEGRATION as DEFAULT_INIT_INTEGRATION,
+ DEFAULT_INIT_INTEGRATION_ENV_VAR as DEFAULT_INIT_INTEGRATION_ENV_VAR,
SCRIPT_TYPE_CHOICES as SCRIPT_TYPE_CHOICES,
+ resolve_default_init_integration as resolve_default_init_integration,
)
from ._init_options import (
INIT_OPTIONS_FILE as INIT_OPTIONS_FILE,
diff --git a/src/specify_cli/_agent_config.py b/src/specify_cli/_agent_config.py
index 3befc1964..0f8282427 100644
--- a/src/specify_cli/_agent_config.py
+++ b/src/specify_cli/_agent_config.py
@@ -1,6 +1,8 @@
"""Agent configuration constants derived from the integration registry."""
from __future__ import annotations
+import os
+import sys
from typing import Any
@@ -17,6 +19,36 @@ AGENT_CONFIG: dict[str, dict[str, Any]] = _build_agent_config()
DEFAULT_INIT_INTEGRATION = "copilot"
+#: Environment variable used to override the fallback integration that
+#: ``specify init`` selects in non-interactive sessions. Follows the existing
+#: ``SPECKIT_INTEGRATION_*`` namespace (see ``SPECKIT_INTEGRATION_<KEY>_EXECUTABLE``
+#: and ``SPECKIT_INTEGRATION_CATALOG_URL``).
+DEFAULT_INIT_INTEGRATION_ENV_VAR = "SPECKIT_INTEGRATION_DEFAULT"
+
+
+def resolve_default_init_integration() -> str:
+ """Return the default init integration, honoring an env-var override.
+
+ Reads :data:`DEFAULT_INIT_INTEGRATION_ENV_VAR`
+ (``SPECKIT_INTEGRATION_DEFAULT``). When it names a registered integration
+ key, that key is returned; otherwise the hardcoded
+ :data:`DEFAULT_INIT_INTEGRATION` (``"copilot"``) is used. An invalid value
+ emits a warning to stderr rather than silently falling back, so operators
+ can tell a typo from an intentional default.
+ """
+ override = (os.environ.get(DEFAULT_INIT_INTEGRATION_ENV_VAR) or "").strip()
+ if not override:
+ return DEFAULT_INIT_INTEGRATION
+ if override in AGENT_CONFIG:
+ return override
+ print(
+ f"Warning: {DEFAULT_INIT_INTEGRATION_ENV_VAR}='{override}' is not a "
+ f"recognized integration; falling back to '{DEFAULT_INIT_INTEGRATION}'. "
+ f"Choose from: {', '.join(sorted(AGENT_CONFIG.keys()))}.",
+ file=sys.stderr,
+ )
+ return DEFAULT_INIT_INTEGRATION
+
SCRIPT_TYPE_CHOICES: dict[str, str] = {
"sh": "POSIX Shell (bash/zsh)",
"ps": "PowerShell",
diff --git a/src/specify_cli/commands/bundle/__init__.py b/src/specify_cli/commands/bundle/__init__.py
index 9e9a0b5e8..7476cb41b 100644
--- a/src/specify_cli/commands/bundle/__init__.py
+++ b/src/specify_cli/commands/bundle/__init__.py
@@ -131,13 +131,13 @@ def _run_init(integration: str, *, script_type: str, offline: bool = False) -> N
def _resolve_init_integration(override: str | None, manifest) -> str:
"""Precedence (FR-013): explicit override β†’ bundle-declared β†’ default."""
- from ..._agent_config import DEFAULT_INIT_INTEGRATION
+ from ..._agent_config import resolve_default_init_integration
if override:
return override
if manifest is not None and manifest.integration is not None:
return manifest.integration.id
- return DEFAULT_INIT_INTEGRATION
+ return resolve_default_init_integration()
# ===== Consume =====
diff --git a/src/specify_cli/commands/init.py b/src/specify_cli/commands/init.py
index d076a7198..dc4ba90a9 100644
--- a/src/specify_cli/commands/init.py
+++ b/src/specify_cli/commands/init.py
@@ -14,8 +14,8 @@ from rich.panel import Panel
from .._agent_config import (
AGENT_CONFIG,
- DEFAULT_INIT_INTEGRATION,
SCRIPT_TYPE_CHOICES,
+ resolve_default_init_integration,
)
from .._assets import (
_locate_bundled_preset,
@@ -466,17 +466,18 @@ def register(app: typer.Typer) -> None:
raise typer.Exit(1)
selected_ai = integration
elif not _stdin_is_interactive():
+ default_integration = resolve_default_init_integration()
console.print(
- f"[dim]Non-interactive session detected: defaulting to '{DEFAULT_INIT_INTEGRATION}'. "
+ f"[dim]Non-interactive session detected: defaulting to '{default_integration}'. "
"Use --integration to choose a different agent.[/dim]"
)
- selected_ai = DEFAULT_INIT_INTEGRATION
+ selected_ai = default_integration
else:
ai_choices = {key: config["name"] for key, config in AGENT_CONFIG.items()}
selected_ai = select_with_arrows(
ai_choices,
"Choose your coding agent integration:",
- DEFAULT_INIT_INTEGRATION,
+ resolve_default_init_integration(),
)
if not integration:
diff --git a/src/specify_cli/workflows/steps/init/__init__.py b/src/specify_cli/workflows/steps/init/__init__.py
index 5dc1ee9c0..e952e19d3 100644
--- a/src/specify_cli/workflows/steps/init/__init__.py
+++ b/src/specify_cli/workflows/steps/init/__init__.py
@@ -11,7 +11,10 @@ from __future__ import annotations
import os
from typing import Any
-from specify_cli._agent_config import DEFAULT_INIT_INTEGRATION, SCRIPT_TYPE_CHOICES
+from specify_cli._agent_config import (
+ SCRIPT_TYPE_CHOICES,
+ resolve_default_init_integration,
+)
from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
from specify_cli.workflows.expressions import evaluate_expression
@@ -54,7 +57,8 @@ class InitStep(StepBase):
Initialize in the target directory instead of creating a new one.
``integration``
Integration key (e.g. ``copilot``). Defaults to the workflow's
- default integration, then to ``DEFAULT_INIT_INTEGRATION``.
+ default integration, then to the resolved default init integration
+ (``SPECKIT_INTEGRATION_DEFAULT`` env var, else ``copilot``).
``integration_options``
Extra options for the integration (e.g. ``"--skills"`` or
``"--commands-dir .myagent/cmds"``).
@@ -81,7 +85,7 @@ class InitStep(StepBase):
# Apply the same default that specify init uses in non-interactive mode
# so that output.integration reflects the actual integration used.
if not integration:
- integration = DEFAULT_INIT_INTEGRATION
+ integration = resolve_default_init_integration()
integration_options = self._resolve(
config.get("integration_options"), context
diff --git a/tests/integration/test_bundler_init_install.py b/tests/integration/test_bundler_init_install.py
index c1e079ce2..a13def5ff 100644
--- a/tests/integration/test_bundler_init_install.py
+++ b/tests/integration/test_bundler_init_install.py
@@ -44,6 +44,20 @@ def test_precedence_default_when_unspecified():
assert _resolve_init_integration(None, None) == "copilot"
+def test_precedence_default_honors_env_var(monkeypatch):
+ monkeypatch.setenv("SPECKIT_INTEGRATION_DEFAULT", "gemini")
+ # With no override and no bundle-declared integration, the env-var default
+ # applies instead of the hardcoded "copilot".
+ assert _resolve_init_integration(None, None) == "gemini"
+ assert _resolve_init_integration(None, _manifest()) == "gemini"
+ # Explicit override and bundle-declared integration still take precedence.
+ assert _resolve_init_integration("claude", None) == "claude"
+ assert (
+ _resolve_init_integration(None, _manifest(integration={"id": "claude"}))
+ == "claude"
+ )
+
+
def _build_mini(tmp_path: Path) -> Path:
bundle = tmp_path / "mini"
bundle.mkdir()
diff --git a/tests/integrations/test_cli.py b/tests/integrations/test_cli.py
index 84d86589e..15647d58a 100644
--- a/tests/integrations/test_cli.py
+++ b/tests/integrations/test_cli.py
@@ -116,6 +116,68 @@ class TestInitIntegrationFlag:
data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
assert data["integration"] == specify_cli.DEFAULT_INIT_INTEGRATION
+ def test_noninteractive_init_honors_default_integration_env_var(
+ self, tmp_path, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ import specify_cli
+
+ def fail_select(*_args, **_kwargs):
+ raise AssertionError("non-interactive init should not open the integration picker")
+
+ monkeypatch.setattr(specify_cli, "select_with_arrows", fail_select)
+ monkeypatch.setenv(
+ specify_cli.DEFAULT_INIT_INTEGRATION_ENV_VAR, "gemini"
+ )
+
+ runner = CliRunner()
+ project = tmp_path / "noninteractive_env"
+ result = runner.invoke(app, [
+ "init", str(project), "--script", "sh", "--ignore-agent-tools",
+ ], catch_exceptions=False)
+
+ assert result.exit_code == 0, result.output
+ assert "defaulting to 'gemini'" in result.output
+
+ data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
+ assert data["integration"] == "gemini"
+
+ def test_interactive_init_picker_default_honors_env_var(
+ self, tmp_path, monkeypatch
+ ):
+ # The interactive integration picker must receive the resolved
+ # SPECKIT_INTEGRATION_DEFAULT value as its default_key, not the
+ # hardcoded constant (guards the picker wiring against regression).
+ 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)
+ monkeypatch.setenv("SPECKIT_INTEGRATION_DEFAULT", "gemini")
+
+ captured = {}
+
+ def fake_select(options, prompt_text=None, default_key=None):
+ # Only capture the integration picker (not the script picker).
+ if "Choose your coding agent integration" in (prompt_text or ""):
+ captured["default_key"] = default_key
+ return default_key
+
+ monkeypatch.setattr(init_mod, "select_with_arrows", fake_select)
+
+ runner = CliRunner()
+ project = tmp_path / "interactive_env"
+ result = runner.invoke(app, [
+ "init", str(project), "--script", "sh", "--ignore-agent-tools",
+ ], catch_exceptions=False)
+
+ assert result.exit_code == 0, result.output
+ assert captured.get("default_key") == "gemini"
+
+ data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
+ assert data["integration"] == "gemini"
+
def test_init_here_nonempty_noninteractive_errors_with_force_guidance(self, tmp_path):
"""`init --here` on a non-empty directory with no confirmation input (empty
stdin) must fail fast with guidance to use --force, instead of the bare
diff --git a/tests/test_commands_package.py b/tests/test_commands_package.py
index b8cd262e8..a92470264 100644
--- a/tests/test_commands_package.py
+++ b/tests/test_commands_package.py
@@ -50,3 +50,51 @@ def test_init_command_registered():
cmd.callback.__name__ for cmd in app.registered_commands if cmd.callback
]
assert "init" in callback_names
+
+
+def test_resolve_default_init_integration_unset(monkeypatch):
+ from specify_cli._agent_config import (
+ DEFAULT_INIT_INTEGRATION,
+ DEFAULT_INIT_INTEGRATION_ENV_VAR,
+ resolve_default_init_integration,
+ )
+ monkeypatch.delenv(DEFAULT_INIT_INTEGRATION_ENV_VAR, raising=False)
+ assert resolve_default_init_integration() == DEFAULT_INIT_INTEGRATION
+
+
+def test_resolve_default_init_integration_valid_override(monkeypatch):
+ from specify_cli._agent_config import (
+ DEFAULT_INIT_INTEGRATION_ENV_VAR,
+ resolve_default_init_integration,
+ )
+ monkeypatch.setenv(DEFAULT_INIT_INTEGRATION_ENV_VAR, "gemini")
+ assert resolve_default_init_integration() == "gemini"
+
+
+def test_resolve_default_init_integration_whitespace_trimmed(monkeypatch):
+ from specify_cli._agent_config import (
+ DEFAULT_INIT_INTEGRATION_ENV_VAR,
+ resolve_default_init_integration,
+ )
+ monkeypatch.setenv(DEFAULT_INIT_INTEGRATION_ENV_VAR, " gemini ")
+ assert resolve_default_init_integration() == "gemini"
+
+
+def test_resolve_default_init_integration_invalid_warns_and_falls_back(
+ monkeypatch, capsys
+):
+ from specify_cli._agent_config import (
+ DEFAULT_INIT_INTEGRATION,
+ DEFAULT_INIT_INTEGRATION_ENV_VAR,
+ resolve_default_init_integration,
+ )
+ monkeypatch.setenv(DEFAULT_INIT_INTEGRATION_ENV_VAR, "not-a-real-agent")
+ assert resolve_default_init_integration() == DEFAULT_INIT_INTEGRATION
+ captured = capsys.readouterr()
+ assert "not-a-real-agent" in captured.err
+ assert DEFAULT_INIT_INTEGRATION_ENV_VAR in captured.err
+
+
+def test_resolve_default_init_integration_re_exported_from_init():
+ from specify_cli import resolve_default_init_integration
+ assert callable(resolve_default_init_integration)
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index dc2a70d4f..4aadfc4a4 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -2190,6 +2190,24 @@ class TestInitStep:
assert result.status == StepStatus.COMPLETED
assert result.output["integration"] == "copilot"
+ def test_default_integration_honors_env_var(self, tmp_path, monkeypatch):
+ # With no step-level and no workflow-level default, the resolved
+ # SPECKIT_INTEGRATION_DEFAULT value must drive both output.integration
+ # and the argv passed to init (guards against reverting to the constant).
+ from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.base import StepContext, StepStatus
+
+ monkeypatch.setenv("SPECKIT_INTEGRATION_DEFAULT", "gemini")
+ step = InitStep()
+ ctx = StepContext(project_root=str(tmp_path))
+ result = step.execute(
+ {"id": "bootstrap", "here": True, "script": "sh"}, ctx
+ )
+ assert result.status == StepStatus.COMPLETED
+ assert result.output["integration"] == "gemini"
+ argv = result.output["argv"]
+ assert "--integration" in argv and "gemini" in argv
+
def test_project_name_creates_subdirectory(self, tmp_path):
from specify_cli.workflows.steps.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus