Add root CLI version option

README.md

@@ -60,6 +60,7 @@ Release notes and verified distribution hashes are available in the
 Generate a title or tags:
 
 ```bash
+creator-toolkit --version
 creator-toolkit title "video editing"
 creator-toolkit tags --count 5
 ```

src/creator_toolkit/main.py

@@ -2,6 +2,7 @@
 import json
 import sys
 from collections.abc import Sequence
+from importlib import metadata
 from pathlib import Path
 from random import Random
 from typing import Any
@@ -20,6 +21,7 @@
 from creator_toolkit.title_generator import generate_title
 
 JSON_SCHEMA_VERSION = 1
+PACKAGE_NAME = "creator-toolkit-cli"
 
 
 class UsageError(ValueError):
@@ -31,6 +33,12 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="creator-toolkit", description="Tools for creator workflows"
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"{PACKAGE_NAME} {metadata.version(PACKAGE_NAME)}",
+        help="show the installed package version and exit",
+    )
     subparsers = parser.add_subparsers(dest="command")
 
     title_parser = subparsers.add_parser("title", help="generate a title from a keyword")

tests/test_cli_smoke.py

@@ -2,6 +2,7 @@
 import shutil
 import subprocess
 import sys
+from importlib import metadata
 from pathlib import Path
 
 
@@ -34,10 +35,19 @@ def test_installed_cli_help_lists_commands():
 
     assert_success(result)
     assert result.stderr == ""
+    assert "--version" in result.stdout
     for command in ("title", "tags", "rename", "undo"):
         assert command in result.stdout
 
 
+def test_installed_cli_version_reports_package_name_and_version():
+    result = run_cli("--version")
+
+    assert_success(result)
+    assert result.stderr == ""
+    assert result.stdout == f"creator-toolkit-cli {metadata.version('creator-toolkit-cli')}\n"
+
+
 def test_installed_cli_generates_title_and_tags_json():
     title_result = run_cli("title", "creator workflow", "--seed", "2026", "--json")
     assert_success(title_result)

tests/test_main.py

@@ -1,4 +1,7 @@
 import json
+from importlib import metadata
+
+import pytest
 
 from creator_toolkit.main import interactive_menu, main
 
@@ -13,6 +16,16 @@ def test_tags_command(capsys):
     assert len(capsys.readouterr().out.splitlines()) == 2
 
 
+def test_version_command_uses_installed_package_metadata(capsys):
+    with pytest.raises(SystemExit) as exit_info:
+        main(["--version"])
+
+    assert exit_info.value.code == 0
+    assert capsys.readouterr().out == (
+        f"creator-toolkit-cli {metadata.version('creator-toolkit-cli')}\n"
+    )
+
+
 def test_seeded_title_and_tags_commands_are_reproducible(capsys):
     assert main(["title", "creator workflow", "--seed", "2026"]) == 0
     first_title = capsys.readouterr().out