diff --git a/docs/reference/core.md b/docs/reference/core.md index 5623c66ead..70c711b1cc 100644 --- a/docs/reference/core.md +++ b/docs/reference/core.md @@ -69,6 +69,8 @@ specify check Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool. +This command stays offline. If a command behaves like an older Spec Kit version or an expected CLI feature is missing, run `specify self check` to check whether your local CLI is behind the latest release. + ## Version Information ```bash diff --git a/docs/upgrade.md b/docs/upgrade.md index 83edc58c22..5355a0b576 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -388,6 +388,14 @@ Only Spec Kit infrastructure files: ### "CLI upgrade doesn't seem to work" +If a command behaves like an older Spec Kit version, first check for local CLI drift: + +```bash +specify self check +``` + +`specify check` is an offline environment scan; `specify self check` is the CLI version lookup. + Verify the installation: ```bash diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index 41fb994726..769521a340 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -1157,6 +1157,8 @@ def check(): if not any(agent_results.values()): console.print("[dim]Tip: Install a coding agent for the best experience[/dim]") + console.print("[dim]Tip: Run 'specify self check' to verify you have the latest CLI version[/dim]") + def _feature_capabilities() -> dict[str, bool]: """Return stable local CLI capability flags for humans and agents.""" diff --git a/tests/test_check_tool.py b/tests/test_check_tool.py index d07783f975..b492f301e8 100644 --- a/tests/test_check_tool.py +++ b/tests/test_check_tool.py @@ -7,7 +7,13 @@ from unittest.mock import patch, MagicMock -from specify_cli import check_tool +from typer.testing import CliRunner + +from specify_cli import app, check_tool +from tests.conftest import strip_ansi + + +runner = CliRunner() class TestCheckToolClaude: @@ -103,4 +109,32 @@ def fake_which(name): return "/usr/bin/kiro" if name == "kiro" else None with patch("shutil.which", side_effect=fake_which): - assert check_tool("kiro-cli") is True \ No newline at end of file + assert check_tool("kiro-cli") is True + + +class TestCheckTip: + """`specify check` should point users to the existing version check.""" + + def test_check_shows_self_check_tip(self): + with patch("specify_cli.check_tool", return_value=True): + result = runner.invoke(app, ["check"]) + + output = strip_ansi(result.output) + assert result.exit_code == 0 + assert ( + "Tip: Run 'specify self check' to verify you have the latest CLI version" + in output + ) + + def test_check_tip_does_not_fetch_latest_release(self): + with ( + patch("specify_cli.check_tool", return_value=True), + patch( + "specify_cli._version._fetch_latest_release_tag", + side_effect=AssertionError("latest release lookup should not run"), + ) as fetch_latest, + ): + result = runner.invoke(app, ["check"]) + + assert result.exit_code == 0 + fetch_latest.assert_not_called()