tlaplus-cli 0.7.0__tar.gz → 0.8.1__tar.gz

{tlaplus_cli-0.7.0/src/tlaplus_cli.egg-info → tlaplus_cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.7.0
+Version: 0.8.1
 Summary: TLA+ tools: download TLC, compile custom modules, run model checker
 Author-email: Denis Nikolskiy <codeomatics@gmail.com>
 License-Expression: MIT
@@ -32,20 +32,39 @@ Dynamic: license-file
 
 Command-line tool for working with TLA+ specifications and the TLC model checker.
 
-## Project goals
+## Project Goals
 
 1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
 2. Run TLA tools in a single CLI interface.
-3. Manage and display the tools outputs.
+3. Manage and display the tool outputs.
 
-## Features
+## Quick Start & Usage
 
-* [Managing TLA+ Tools](docs/managing-tlaplus-tools/managing-tla2tools.md): Verify Java requirements, manage/pin `tla2tools.jar` versions, and handle cache settings.
-* [Running TLC](docs/tlc/tlc.md): Run the TLC model checker, inspect commands, and execute model checking with custom modules.
-* [Custom Java Modules](docs/java-modules-for-tlc/README.md): Compile, register, and manage custom Java operator overrides for TLC using automated CLI commands.
+### 1. Toolset Management (`tla tools`)
+* `tla check-java`: Verify Java installation and compatibility.
+* `tla tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tla tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tla tools pin <version>`: Set default toolset version for TLC runs.
 
-## Installation
+### 2. Model Checking (`tla tlc`)
+* `tla tlc <spec>`: Execute TLC model checker on a specification.
+* `tla tlc <spec> --show-command`: Inspect exact JVM command before execution.
 
-For detailed installation instructions, please refer to:
-* [Installation via uv tool](docs/installation/uv-tool.md)
-* [Nix Flakes Installation & Development](docs/installation/nix.md)
+### 3. Custom Java Modules (`tla modules`)
+* `tla modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tla modules list`: Display cached custom modules.
+* `tla modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaplus-cli
+```
+
+### Via Nix Flakes
+```bash
+nix profile install github:nikolskiy/tlaplus-cli
+```

tlaplus_cli-0.8.1/README.md

@@ -0,0 +1,40 @@
+# TLA+ CLI
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+## Project Goals
+
+1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
+2. Run TLA tools in a single CLI interface.
+3. Manage and display the tool outputs.
+
+## Quick Start & Usage
+
+### 1. Toolset Management (`tla tools`)
+* `tla check-java`: Verify Java installation and compatibility.
+* `tla tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tla tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tla tools pin <version>`: Set default toolset version for TLC runs.
+
+### 2. Model Checking (`tla tlc`)
+* `tla tlc <spec>`: Execute TLC model checker on a specification.
+* `tla tlc <spec> --show-command`: Inspect exact JVM command before execution.
+
+### 3. Custom Java Modules (`tla modules`)
+* `tla modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tla modules list`: Display cached custom modules.
+* `tla modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaplus-cli
+```
+
+### Via Nix Flakes
+```bash
+nix profile install github:nikolskiy/tlaplus-cli
+```

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.7.0"
+version = "0.8.1"
 description = "TLA+ tools: download TLC, compile custom modules, run model checker"
 readme = "README.md"
 requires-python = ">=3.11"

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/cli.py

@@ -11,6 +11,7 @@ from tlaplus_cli.cmd.modules import app as modules_app
 from tlaplus_cli.cmd.tlc import tlc as run_tlc_cmd
 from tlaplus_cli.cmd.tools import app as tools_app
 from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.versioning import get_app_version
 
 app = typer.Typer(
     name="tla",
@@ -23,7 +24,8 @@ app = typer.Typer(
 def version_callback(value: bool) -> None:
     if value:
         meta = importlib.metadata.metadata("tlaplus-cli")
-        typer.echo(f"{meta['Name']} v{meta['Version']}")
+        app_ver = get_app_version(base_version=meta["Version"])
+        typer.echo(f"{meta['Name']} v{app_ver}")
         typer.echo(meta["Summary"])
         raise typer.Exit()
 

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/cmd/modules/add.py

@@ -11,6 +11,7 @@ import typer
 from tlaplus_cli.config.loader import load_config
 from tlaplus_cli.java.classpath import ClasspathResolver, ResolveMode
 from tlaplus_cli.tlc.compiler import get_tlc_jar_path
+from tlaplus_cli.tlc.run_cache import clear_tlc_run_cache
 from tlaplus_cli.versioning.paths import get_modules_dir
 
 
@@ -135,4 +136,5 @@ def add_module(  # noqa: PLR0912, PLR0915
     with (target_dir / "metadata.json").open("w") as f:
         json.dump(metadata, f, indent=2)
 
+    clear_tlc_run_cache()
     typer.echo(f"Module '{module_name}' successfully added to cache.")

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/cmd/modules/remove.py

@@ -2,6 +2,7 @@ import shutil
 
 import typer
 
+from tlaplus_cli.tlc.run_cache import clear_tlc_run_cache
 from tlaplus_cli.versioning.paths import get_modules_dir
 
 
@@ -14,6 +15,7 @@ def remove_module(module_name: str = typer.Argument(..., help="Name of the modul
 
     try:
         shutil.rmtree(target_dir)
+        clear_tlc_run_cache()
         typer.echo(f"Module '{module_name}' successfully deleted from cache.")
     except OSError as e:
         typer.echo(f"Error: Failed to delete module: {e}", err=True)

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/cmd/tlc.py

@@ -12,9 +12,11 @@ from tlaplus_cli.tlc.compiler import get_tlc_jar_path
 from tlaplus_cli.tlc.components import StatsTableFormatter, StatusFooterRenderable
 from tlaplus_cli.tlc.formatter import TlcFormatter
 from tlaplus_cli.tlc.models import CheckState, ModelCheckResult
+from tlaplus_cli.tlc.run_cache import clear_tlc_run_cache
 from tlaplus_cli.tlc.runner import (
     build_tlc_command,
     get_tlc_version,
+    resolve_cfg_file,
     resolve_spec_file,
     run_tlc,
 )
@@ -62,9 +64,13 @@ def _show_diagnostic_info(spec: str, spec_name: str) -> None:
 
 # PLR0912: This command handler orchestrates multiple output types (errors, warnings, results, progress);
 # splitting it would fragment the CLI's primary user-facing logic.
+# PLR0913: CLI command function accepts options as parameters.
 # PLR0915: Too many statements.
-def tlc(  # noqa: PLR0912, PLR0915
-    spec: str = typer.Argument(help="Name of the TLA+ specification (without .tla extension)."),
+def tlc(  # noqa: PLR0912, PLR0913, PLR0915
+    spec: str | None = typer.Argument(
+        None,
+        help="Name of the TLA+ specification (without .tla extension).",
+    ),
     # Typer requires the parameter in the signature to register the CLI option;
     # since the logic is in the eager callback, the value is not used here.
     version: bool | None = typer.Option(  # noqa: ARG001
@@ -75,6 +81,7 @@ def tlc(  # noqa: PLR0912, PLR0915
         is_eager=True,
     ),
     show_command: bool = typer.Option(False, "--show-command", help="Print the command instead of executing it."),
+    cleanup: bool = typer.Option(False, "--cleanup", help="Purge all cached TLC run artifacts from cache."),
     _refresh_interval: float | None = typer.Option(
         None,
         "--refresh-interval",
@@ -82,17 +89,39 @@ def tlc(  # noqa: PLR0912, PLR0915
     ),
     coverage: bool = typer.Option(False, "--coverage", help="Enable code coverage visualization."),
     raw: bool = typer.Option(False, "--raw", help="Run TLC in raw mode without structured tool mode formatting."),
+    cfg: str | None = typer.Option(
+        None,
+        "--cfg",
+        help="Custom TLC configuration file name or path (e.g. spec-v1 or spec-v1.cfg).",
+    ),
 ) -> None:
     """Run TLC model checker on a TLA+ specification."""
+    if cleanup:
+        clear_tlc_run_cache()
+        ui.success("TLC run cache cleared successfully.")
+        raise typer.Exit(0)
+
+    if not spec:
+        ui.error("Missing argument 'SPEC'.")
+        raise typer.Exit(1)
+
     # version argument is handled by version_callback (is_eager=True)
     try:
-        _, _spec_name = resolve_spec_file(spec)
+        spec_file, _spec_name = resolve_spec_file(spec)
+        if cfg:
+            config_obj = load_config()
+            project_root = find_project_root(
+                spec_file,
+                modules_dir=config_obj.workspace.modules_dir,
+                classes_dir=config_obj.workspace.classes_dir,
+            )
+            resolve_cfg_file(cfg, spec_file, project_root=project_root)
     except FileNotFoundError as e:
         ui.error(str(e))
         raise typer.Exit(1) from None
 
     if show_command:
-        cmd = build_tlc_command(spec)
+        cmd = build_tlc_command(spec, cfg=cfg)
         if coverage:
             cmd.extend(["-coverage", "1"])
         if not cmd:
@@ -101,9 +130,10 @@ def tlc(  # noqa: PLR0912, PLR0915
         raise typer.Exit(0)
 
     if raw:
-        exit_code = run_tlc(spec, coverage=coverage, raw=True)
+        exit_code = run_tlc(spec, coverage=coverage, raw=True, cfg=cfg)
         raise typer.Exit(exit_code)
 
+
     tlc_version = get_tlc_version() or "unknown"
     formatter = TlcFormatter(tlc_version=tlc_version)
     layout = formatter.create_layout()
@@ -164,7 +194,7 @@ def tlc(  # noqa: PLR0912, PLR0915
                         live.console.print(table_formatter.get_border())
                         stats_border_printed = True
 
-                exit_code = run_tlc(spec, callback=wrapped_callback, coverage=coverage)
+                exit_code = run_tlc(spec, callback=wrapped_callback, coverage=coverage, cfg=cfg)
         else:
             # Non-TTY mode: no Live block
             table_formatter = StatsTableFormatter()
@@ -207,7 +237,7 @@ def tlc(  # noqa: PLR0912, PLR0915
                     print(table_formatter.get_border())
                     stats_border_printed = True
 
-            exit_code = run_tlc(spec, callback=wrapped_callback, coverage=coverage)
+            exit_code = run_tlc(spec, callback=wrapped_callback, coverage=coverage, cfg=cfg)
 
         # Fallback print of border if not printed yet
         if stats_header_printed and not stats_border_printed:

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/cmd/tools/list.py

@@ -15,6 +15,7 @@ from tlaplus_cli.versioning import (
 
 @app.command(name="list")
 def list_versions() -> None:
+    """List available and installed TLC versions."""
     config = load_config()
     versions, status = fetch_remote_versions(config.tla.urls.tags, config.tla.urls.releases, config.tla.urls.per_page)
 

tlaplus_cli-0.8.1/src/tlaplus_cli/tlc/run_cache.py

@@ -0,0 +1,61 @@
+import contextlib
+import hashlib
+import shutil
+from pathlib import Path
+
+from tlaplus_cli.versioning.paths import get_tlc_run_dir
+
+
+def compute_spec_hash(spec_file: Path) -> str:
+    """Compute an 8-character SHA-256 short hash for a TLA+ specification and its configuration file."""
+    hasher = hashlib.sha256()
+
+    # Include absolute path string
+    hasher.update(str(spec_file.absolute()).encode("utf-8"))
+
+    # Include spec file contents if it exists
+    with contextlib.suppress(OSError):
+        hasher.update(spec_file.read_bytes())
+
+    # Include .cfg file contents if present
+    cfg_file = spec_file.with_suffix(".cfg")
+    if cfg_file.is_file():
+        with contextlib.suppress(OSError):
+            hasher.update(cfg_file.read_bytes())
+
+    return hasher.hexdigest()[:8]
+
+
+def _cleanup_stale_spec_dirs(tlc_run_dir: Path, spec_stem: str, current_hash: str) -> None:
+    """Remove older cached run directories for the spec stem that do not match the current hash."""
+    if not tlc_run_dir.is_dir():
+        return
+
+    prefix = f"{spec_stem}_"
+    current_dir_name = f"{spec_stem}_{current_hash}"
+
+    for item in tlc_run_dir.iterdir():
+        if item.is_dir() and item.name.startswith(prefix) and item.name != current_dir_name:
+            with contextlib.suppress(OSError):
+                shutil.rmtree(item)
+
+
+def get_spec_run_dir(spec_file: Path) -> Path:
+    """Get or create the isolated run directory for a spec and purge stale runs for the same spec."""
+    spec_file = spec_file.absolute()
+    short_hash = compute_spec_hash(spec_file)
+    tlc_run_dir = get_tlc_run_dir()
+
+    _cleanup_stale_spec_dirs(tlc_run_dir, spec_file.stem, short_hash)
+
+    target_dir = tlc_run_dir / f"{spec_file.stem}_{short_hash}"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    return target_dir
+
+
+def clear_tlc_run_cache() -> None:
+    """Purge all cached TLC run state directories."""
+    tlc_run_dir = get_tlc_run_dir()
+    if tlc_run_dir.exists():
+        with contextlib.suppress(OSError):
+            shutil.rmtree(tlc_run_dir)

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/tlc/runner.py

@@ -12,6 +12,7 @@ from tlaplus_cli.project import find_project_root
 from tlaplus_cli.tlc.compiler import get_tlc_jar_path
 from tlaplus_cli.tlc.models import CheckState, ModelCheckResult
 from tlaplus_cli.tlc.parser import TlcParser
+from tlaplus_cli.tlc.run_cache import get_spec_run_dir
 from tlaplus_cli.tlc.sany import SanyParser
 
 
@@ -36,6 +37,51 @@ def resolve_spec_file(spec: str) -> tuple[Path, str]:
     return spec_file.absolute(), spec_file.name
 
 
+def resolve_cfg_file(cfg: str, spec_file: Path, project_root: Path | None = None) -> tuple[Path, str]:
+    """Resolve a .cfg configuration file from a string name or path.
+
+    Returns (absolute_path, cfg_arg_for_tlc).
+    Raises FileNotFoundError if not found.
+    """
+    cfg_path = Path(cfg)
+    cfg_names: list[str] = [cfg_path.name]
+    if cfg_path.suffix != ".cfg":
+        cfg_names.append(cfg_path.name + ".cfg")
+
+    candidates: list[Path] = []
+    if cfg_path.is_absolute():
+        candidates.append(cfg_path)
+        if cfg_path.suffix != ".cfg":
+            candidates.append(cfg_path.with_suffix(".cfg"))
+    else:
+        search_dirs: list[Path] = []
+        base_parent = cfg_path.parent
+        search_dirs.append(spec_file.parent / base_parent)
+        search_dirs.append(Path.cwd() / base_parent)
+        if project_root:
+            search_dirs.append(project_root / base_parent)
+
+        seen_dirs: set[Path] = set()
+        for sdir in search_dirs:
+            resolved_dir = sdir.resolve()
+            if resolved_dir not in seen_dirs:
+                seen_dirs.add(resolved_dir)
+                for cname in cfg_names:
+                    candidates.append(sdir / cname)
+
+    cfg_file = next((c for c in candidates if c.is_file()), None)
+    if not cfg_file:
+        msg = f"Could not find TLC configuration file '{cfg}'"
+        raise FileNotFoundError(msg)
+
+    cfg_arg = cfg_file.name
+    if project_root:
+        with contextlib.suppress(ValueError):
+            cfg_arg = str(cfg_file.relative_to(project_root))
+
+    return cfg_file.absolute(), cfg_arg
+
+
 def get_override_classes(classpath: list[str]) -> list[str]:
     """Inspect all classpath directories and locate override classes."""
     classes = []
@@ -63,7 +109,7 @@ def get_override_classes(classpath: list[str]) -> list[str]:
     return deduped
 
 
-def build_tlc_command(spec: str) -> list[str]:
+def build_tlc_command(spec: str, cfg: str | None = None) -> list[str]:
     """Build the java command for running TLC."""
     config = load_config()
 
@@ -95,29 +141,41 @@ def build_tlc_command(spec: str) -> list[str]:
         with contextlib.suppress(ValueError):
             spec_arg = str(spec_file.relative_to(project_root))
 
-    return [
+    run_dir = get_spec_run_dir(spec_file)
+
+    cmd = [
         "java",
         *config.java.opts,
         *extra_jvm_opts,
         "-cp",
         classpath,
         config.tlc.java_class,
-        spec_arg,
+        "-metadir",
+        str(run_dir),
     ]
 
+    if cfg:
+        _, cfg_arg = resolve_cfg_file(cfg, spec_file, project_root=project_root)
+        cmd.extend(["-config", cfg_arg])
+
+    cmd.append(spec_arg)
+    return cmd
+
 
 def run_tlc(  # noqa: PLR0912, PLR0915
     spec: str,
     callback: Callable[[ModelCheckResult], None] | None = None,
     coverage: bool = False,
     raw: bool = False,
+    cfg: str | None = None,
 ) -> int:
     """Run TLC model checker on a TLA+ specification. Returns exit code."""
     config = load_config()
     validate_java_version(config.java.min_version)
 
     spec_file, _ = resolve_spec_file(spec)
-    cmd = build_tlc_command(spec)
+    cmd = build_tlc_command(spec, cfg=cfg)
+
 
     # Ensure tool mode is enabled for structured output (unless in raw mode)
     if not raw and "-tool" not in cmd:

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/versioning/__init__.py

@@ -1,4 +1,9 @@
 from tlaplus_cli.versioning.api import fetch_remote_versions
+from tlaplus_cli.versioning.app_version import (
+    get_app_version,
+    get_git_commit_hash,
+    is_editable_install,
+)
 from tlaplus_cli.versioning.downloader import (
     download_version,
     download_version_from_url,
@@ -39,10 +44,13 @@ __all__ = [
     "download_version_from_url",
     "extract_version_from_url",
     "fetch_remote_versions",
+    "get_app_version",
+    "get_git_commit_hash",
     "get_github_cache_file",
     "get_pinned_path",
     "get_pinned_version_dir",
     "get_tools_dir",
+    "is_editable_install",
     "is_url",
     "list_local_versions",
     "read_version_metadata",

tlaplus_cli-0.8.1/src/tlaplus_cli/versioning/app_version.py

@@ -0,0 +1,62 @@
+"""App version discovery and git commit resolution for development installations."""
+
+import importlib.metadata
+import json
+import subprocess
+from pathlib import Path
+
+
+def is_editable_install() -> bool:
+    """Check if the tlaplus-cli package is installed in editable / development mode."""
+    try:
+        dist = importlib.metadata.distribution("tlaplus-cli")
+        raw = dist.read_text("direct_url.json")
+        if raw:
+            data = json.loads(raw)
+            if isinstance(data, dict) and data.get("dir_info", {}).get("editable") is True:
+                return True
+
+        origin = getattr(dist, "origin", None)
+        if origin is not None:
+            dir_info = getattr(origin, "dir_info", None)
+            if dir_info is not None and getattr(dir_info, "editable", None) is True:
+                return True
+    except (importlib.metadata.PackageNotFoundError, json.JSONDecodeError, TypeError, KeyError, AttributeError):
+        pass
+    return False
+
+
+def get_git_commit_hash(base_dir: Path | None = None) -> str | None:
+    """Attempt to retrieve short git commit hash using git rev-parse --short HEAD."""
+    cmd = ["git", "rev-parse", "--short", "HEAD"]
+    cwd = base_dir if (base_dir and base_dir.is_dir()) else Path(__file__).parent
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, check=False, cwd=cwd)
+        if res.returncode == 0:
+            commit = res.stdout.strip()
+            if commit and len(commit) >= 7:
+                return commit
+    except (subprocess.SubprocessError, OSError):
+        pass
+    return None
+
+
+def get_app_version(base_version: str | None = None, base_dir: Path | None = None) -> str:
+    """Return the application version string.
+
+    Appends short git commit hash if running in an editable/development installation.
+    """
+    if not base_version:
+        try:
+            meta = importlib.metadata.metadata("tlaplus-cli")
+            base_version = meta["Version"]
+        except (importlib.metadata.PackageNotFoundError, KeyError):
+            base_version = "0.0.0"
+
+    git_hash = get_git_commit_hash(base_dir)
+    repo_git = (Path(__file__).parent / "../../..").resolve() / ".git"
+    is_dev = is_editable_install() or base_dir is not None or repo_git.exists()
+    if git_hash and is_dev:
+        return f"{base_version}+{git_hash}"
+
+    return base_version

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/versioning/paths.py

@@ -17,6 +17,14 @@ def get_modules_dir() -> Path:
     return cache_dir() / "modules"
 
 
+def get_run_dir() -> Path:
+    return cache_dir() / "run"
+
+
+def get_tlc_run_dir() -> Path:
+    return get_run_dir() / "tlc"
+
+
 def get_pinned_path() -> Path:
     """Returns path to the pin marker file."""
     return get_tools_dir() / "tools-pinned-version.txt"

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1/src/tlaplus_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.7.0
+Version: 0.8.1
 Summary: TLA+ tools: download TLC, compile custom modules, run model checker
 Author-email: Denis Nikolskiy <codeomatics@gmail.com>
 License-Expression: MIT
@@ -32,20 +32,39 @@ Dynamic: license-file
 
 Command-line tool for working with TLA+ specifications and the TLC model checker.
 
-## Project goals
+## Project Goals
 
 1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
 2. Run TLA tools in a single CLI interface.
-3. Manage and display the tools outputs.
+3. Manage and display the tool outputs.
 
-## Features
+## Quick Start & Usage
 
-* [Managing TLA+ Tools](docs/managing-tlaplus-tools/managing-tla2tools.md): Verify Java requirements, manage/pin `tla2tools.jar` versions, and handle cache settings.
-* [Running TLC](docs/tlc/tlc.md): Run the TLC model checker, inspect commands, and execute model checking with custom modules.
-* [Custom Java Modules](docs/java-modules-for-tlc/README.md): Compile, register, and manage custom Java operator overrides for TLC using automated CLI commands.
+### 1. Toolset Management (`tla tools`)
+* `tla check-java`: Verify Java installation and compatibility.
+* `tla tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tla tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tla tools pin <version>`: Set default toolset version for TLC runs.
 
-## Installation
+### 2. Model Checking (`tla tlc`)
+* `tla tlc <spec>`: Execute TLC model checker on a specification.
+* `tla tlc <spec> --show-command`: Inspect exact JVM command before execution.
 
-For detailed installation instructions, please refer to:
-* [Installation via uv tool](docs/installation/uv-tool.md)
-* [Nix Flakes Installation & Development](docs/installation/nix.md)
+### 3. Custom Java Modules (`tla modules`)
+* `tla modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tla modules list`: Display cached custom modules.
+* `tla modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaplus-cli
+```
+
+### Via Nix Flakes
+```bash
+nix profile install github:nikolskiy/tlaplus-cli
+```

{tlaplus_cli-0.7.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli.egg-info/SOURCES.txt

@@ -54,11 +54,13 @@ src/tlaplus_cli/tlc/components.py
 src/tlaplus_cli/tlc/formatter.py
 src/tlaplus_cli/tlc/models.py
 src/tlaplus_cli/tlc/parser.py
+src/tlaplus_cli/tlc/run_cache.py
 src/tlaplus_cli/tlc/runner.py
 src/tlaplus_cli/tlc/sany.py
 src/tlaplus_cli/tlc/values.py
 src/tlaplus_cli/versioning/__init__.py
 src/tlaplus_cli/versioning/api.py
+src/tlaplus_cli/versioning/app_version.py
 src/tlaplus_cli/versioning/downloader.py
 src/tlaplus_cli/versioning/metadata.py
 src/tlaplus_cli/versioning/paths.py

tlaplus_cli-0.7.0/README.md

@@ -1,21 +0,0 @@
-# TLA+ CLI
-
-Command-line tool for working with TLA+ specifications and the TLC model checker.
-
-## Project goals
-
-1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
-2. Run TLA tools in a single CLI interface.
-3. Manage and display the tools outputs.
-
-## Features
-
-* [Managing TLA+ Tools](docs/managing-tlaplus-tools/managing-tla2tools.md): Verify Java requirements, manage/pin `tla2tools.jar` versions, and handle cache settings.
-* [Running TLC](docs/tlc/tlc.md): Run the TLC model checker, inspect commands, and execute model checking with custom modules.
-* [Custom Java Modules](docs/java-modules-for-tlc/README.md): Compile, register, and manage custom Java operator overrides for TLC using automated CLI commands.
-
-## Installation
-
-For detailed installation instructions, please refer to:
-* [Installation via uv tool](docs/installation/uv-tool.md)
-* [Nix Flakes Installation & Development](docs/installation/nix.md)