terok-executor 0.2.0__tar.gz → 0.3.0__tar.gz

{terok_executor-0.2.0 → terok_executor-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: terok-executor
-Version: 0.2.0
+Version: 0.3.0
 Summary: Single-agent task runner for hardened Podman containers
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -23,15 +23,15 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Typing :: Typed
-Requires-Dist: Jinja2 (>=3.1)
-Requires-Dist: agent-client-protocol (>=0.10.1)
-Requires-Dist: prompt-toolkit (>=3.0)
-Requires-Dist: pydantic (>=2.9)
-Requires-Dist: rich (>=13.0)
-Requires-Dist: ruamel.yaml (>=0.18)
-Requires-Dist: terok-sandbox (>=0.2.0,<0.3.0)
-Requires-Dist: terok-util (>=0.2.0,<0.3.0)
-Requires-Dist: tomli-w (>=1.0)
+Requires-Dist: Jinja2 (>=3.1,<4.0)
+Requires-Dist: agent-client-protocol (==0.10.1)
+Requires-Dist: prompt-toolkit (>=3.0,<4.0)
+Requires-Dist: pydantic (>=2.13,<3.0)
+Requires-Dist: rich (>=15.0,<16.0)
+Requires-Dist: ruamel.yaml (==0.19.1)
+Requires-Dist: terok-sandbox (>=0.4.0,<0.5.0)
+Requires-Dist: terok-util (>=0.2.1,<0.3.0)
+Requires-Dist: tomli-w (>=1.2,<2.0)
 Project-URL: Changelog, https://github.com/terok-ai/terok-executor/blob/master/CHANGELOG.md
 Project-URL: Documentation, https://terok-ai.github.io/terok-executor/
 Project-URL: Homepage, https://terok-ai.github.io/terok-executor/
@@ -70,7 +70,7 @@ Python when you want library-grade control.
 
 ```bash
 pip install terok-executor
-terok-executor run claude ~/my-workspace
+terok-executor run claude ~/my-workspace -p "Fix the bug"
 ```
 
 The first `run` interactively offers any missing prerequisites — sandbox
@@ -112,16 +112,18 @@ hardening guarantees.
 | Claude Code | OAuth*, API key | Anthropic Claude Code |
 | Codex | OAuth*, API key | OpenAI Codex CLI |
 | Vibe | API key | Mistral Vibe |
-| OpenCode | API key | Generic LLM endpoint driver — bundled defaults for Helmholtz Blablador, KISSKI AcademicCloud, and your own endpoint |
+| Copilot | — | GitHub Copilot (no vault route yet) |
+| OpenCode | — (uses provider keys) | Harness that drives any OpenAI-compatible provider — curated configs for Helmholtz Blablador, KISSKI AcademicCloud, and OpenRouter (each authenticated with its own API key) |
+| Pi | — (uses provider keys) | Multi-provider harness; routes through the phantom tokens of co-installed providers |
 | gh | OAuth, API key | GitHub CLI |
 | glab | API key | GitLab CLI |
+| SonarCloud | API key | SonarCloud scanner |
 | CodeRabbit | API key | CodeRabbit (sidecar tool) |
-| SonarCloud | API key | SonarCloud scanner (sidecar tool) |
 
-\* Claude and Codex OAuth are experimental, and support must be explicitly allowed in the config file. 
+\* Claude and Codex OAuth are experimental.
 
-`terok-executor agents` lists the live roster (add `--all` to
-include the tool entries).
+`terok-executor agents list` lists the live roster (add `--all` to
+include tools and harness-driven providers).
 
 ## Where it sits in the stack
 
@@ -131,7 +133,8 @@ runs across many projects.  Below it, terok-executor delegates the
 host-side security boundary
 ([terok-sandbox](https://github.com/terok-ai/terok-sandbox)): the
 credential vault, the git gate, the egress firewall hooks, the
-systemd service lifecycle.
+per-container supervisor lifecycle (OCI `createRuntime`/`poststop`
+hooks).
 
 ## Commands
 
@@ -141,13 +144,16 @@ systemd service lifecycle.
 | `setup` | Bootstrap sandbox services + container images |
 | `uninstall` | Remove sandbox services + container images |
 | `auth` | Authenticate a provider |
-| `agents` | List the agent roster |
+| `agents` | Inspect the agent roster (`list`) and set the build-time default selection (`set`) |
 | `build` | Build base + agent images explicitly |
-| `run-tool` | Run a sidecar tool (CodeRabbit, SonarCloud) |
-| `list` | List running containers |
-| `stop` | Stop a running container |
+| `run-tool` | Run a sidecar tool (CodeRabbit) |
+| `list` | List containers |
+| `start` | Start a stopped container |
+| `stop` | Stop a container (kept for a later `start`) |
+| `rm` | Remove a container and its host-side state |
 | `show-config` | Print the effective `SandboxConfig` as YAML (diffable across orchestrators) |
-| `vault` | Vault management (start, stop, status, install, routes) |
+| `vault` | Vault management (status, unlock, lock, list, passphrase, routes, clean) |
+| `sandbox` | Full terok-sandbox command tree (shield, vault, ssh, doctor, …) |
 
 ### Config override
 

{terok_executor-0.2.0 → terok_executor-0.3.0}/README.md

@@ -28,7 +28,7 @@ Python when you want library-grade control.
 
 ```bash
 pip install terok-executor
-terok-executor run claude ~/my-workspace
+terok-executor run claude ~/my-workspace -p "Fix the bug"
 ```
 
 The first `run` interactively offers any missing prerequisites — sandbox
@@ -70,16 +70,18 @@ hardening guarantees.
 | Claude Code | OAuth*, API key | Anthropic Claude Code |
 | Codex | OAuth*, API key | OpenAI Codex CLI |
 | Vibe | API key | Mistral Vibe |
-| OpenCode | API key | Generic LLM endpoint driver — bundled defaults for Helmholtz Blablador, KISSKI AcademicCloud, and your own endpoint |
+| Copilot | — | GitHub Copilot (no vault route yet) |
+| OpenCode | — (uses provider keys) | Harness that drives any OpenAI-compatible provider — curated configs for Helmholtz Blablador, KISSKI AcademicCloud, and OpenRouter (each authenticated with its own API key) |
+| Pi | — (uses provider keys) | Multi-provider harness; routes through the phantom tokens of co-installed providers |
 | gh | OAuth, API key | GitHub CLI |
 | glab | API key | GitLab CLI |
+| SonarCloud | API key | SonarCloud scanner |
 | CodeRabbit | API key | CodeRabbit (sidecar tool) |
-| SonarCloud | API key | SonarCloud scanner (sidecar tool) |
 
-\* Claude and Codex OAuth are experimental, and support must be explicitly allowed in the config file. 
+\* Claude and Codex OAuth are experimental.
 
-`terok-executor agents` lists the live roster (add `--all` to
-include the tool entries).
+`terok-executor agents list` lists the live roster (add `--all` to
+include tools and harness-driven providers).
 
 ## Where it sits in the stack
 
@@ -89,7 +91,8 @@ runs across many projects.  Below it, terok-executor delegates the
 host-side security boundary
 ([terok-sandbox](https://github.com/terok-ai/terok-sandbox)): the
 credential vault, the git gate, the egress firewall hooks, the
-systemd service lifecycle.
+per-container supervisor lifecycle (OCI `createRuntime`/`poststop`
+hooks).
 
 ## Commands
 
@@ -99,13 +102,16 @@ systemd service lifecycle.
 | `setup` | Bootstrap sandbox services + container images |
 | `uninstall` | Remove sandbox services + container images |
 | `auth` | Authenticate a provider |
-| `agents` | List the agent roster |
+| `agents` | Inspect the agent roster (`list`) and set the build-time default selection (`set`) |
 | `build` | Build base + agent images explicitly |
-| `run-tool` | Run a sidecar tool (CodeRabbit, SonarCloud) |
-| `list` | List running containers |
-| `stop` | Stop a running container |
+| `run-tool` | Run a sidecar tool (CodeRabbit) |
+| `list` | List containers |
+| `start` | Start a stopped container |
+| `stop` | Stop a container (kept for a later `start`) |
+| `rm` | Remove a container and its host-side state |
 | `show-config` | Print the effective `SandboxConfig` as YAML (diffable across orchestrators) |
-| `vault` | Vault management (start, stop, status, install, routes) |
+| `vault` | Vault management (status, unlock, lock, list, passphrase, routes, clean) |
+| `sandbox` | Full terok-sandbox command tree (shield, vault, ssh, doctor, …) |
 
 ### Config override
 

{terok_executor-0.2.0 → terok_executor-0.3.0}/pyproject.toml

@@ -16,18 +16,20 @@ maintainers = [
 keywords = ["podman", "containers", "agent", "ai", "coding-agent"]
 requires-python = ">=3.12,<3.15"
 dynamic = ["classifiers"]
+# Dependency pins follow the policy in AGENTS.md ("Dependency Pinning &
+# pyproject.toml Hygiene").  Keep the dependency list comment-free.
 dependencies = [
-    "terok-sandbox>=0.2.0,<0.3.0",
-    "terok-util>=0.2.0,<0.3.0",
-    "ruamel.yaml>=0.18",
-    "Jinja2>=3.1",
-    "tomli-w>=1.0",
-    "prompt-toolkit>=3.0",
-    "pydantic>=2.9",
-    "rich>=13.0",
-    "agent-client-protocol>=0.10.1",
+    "terok-sandbox>=0.4.0,<0.5.0",
+    "terok-util>=0.2.1,<0.3.0",
+    "ruamel.yaml==0.19.1",
+    "Jinja2~=3.1",
+    "tomli-w~=1.2",
+    "prompt-toolkit~=3.0",
+    "pydantic~=2.13",
+    "rich~=15.0",
+    "agent-client-protocol==0.10.1",
 ]
-version = "0.2.0"
+version = "0.3.0"
 
 [project.urls]
 Homepage = "https://terok-ai.github.io/terok-executor/"
@@ -58,18 +60,18 @@ packages = [
 
 [tool.poetry.group.dev.dependencies]
 pre-commit = ">=4.0"
-ruff = ">=0.15.16"
+ruff = ">=0.15.20"
 bandit = ">=1.7"
 docstr-coverage = "^2.3.2"
-complexipy = ">=5.5.0"
+complexipy = ">=6.0.0"
 vulture = ">=2.12"
 reuse = "^6.2.0"
 tach = "^0.35.0"
 mypy = ">=2.1.0,<3.0"
-import-linter = ">=2.1"
+import-linter = ">=2.12"
 
 [tool.poetry.group.test.dependencies]
-pytest = ">=9.0.3"
+pytest = ">=9.1.1"
 pytest-cov = ">=4.0"
 pytest-timeout = ">=2.0"
 
@@ -129,7 +131,7 @@ quote-style = "double"
 indent-style = "space"
 docstring-code-format = true
 
-# Static type checking — see `make typecheck`.
+# Static type checking -- see `make typecheck`.
 # ``resources/`` is excluded entirely: it holds container-side scripts and
 # bundled agent assets that aren't part of the host-side import graph
 # (``resources/toad-agents/`` isn't even a valid Python package name).
@@ -150,7 +152,7 @@ pretty = true
 show_error_codes = true
 
 # ``resources/`` holds container-side scripts (run inside task containers, not
-# part of the host import graph — the same reason mypy excludes it).  Tests
+# part of the host import graph -- the same reason mypy excludes it).  Tests
 # exercise them by path-loading (``SourceFileLoader``), which coverage.py can't
 # attribute, so they report 0%; omit them rather than chase phantom misses.
 [tool.coverage.run]

{terok_executor-0.2.0 → terok_executor-0.3.0}/src/terok_executor/__init__.py

@@ -20,7 +20,7 @@ in their submodules; reach into ``terok_executor.<sub>`` when you
 need them.
 """
 
-__version__: str = "0.2.0"  # placeholder; replaced at build time
+__version__: str = "0.3.0"  # placeholder; replaced at build time
 
 from importlib.metadata import PackageNotFoundError, version as _meta_version
 

{terok_executor-0.2.0 → terok_executor-0.3.0}/src/terok_executor/cli.py

@@ -36,6 +36,13 @@ except PackageNotFoundError:
     __version__ = "0.0.0"
 
 
+#: Spelling under which sandbox setup is reachable in this front-end;
+#: declared at CLI entry so sandbox-composed re-run hints name a verb
+#: this CLI actually exposes (protocol: env var name, shared by string).
+_SETUP_INVOCATION_ENV = "TEROK_SETUP_INVOCATION"
+_SETUP_INVOCATION = "terok-executor setup"
+
+
 def main() -> None:
     """Run the terok-executor CLI.
 
@@ -44,6 +51,7 @@ def main() -> None:
     subparser convention, matching the placement used by ``docker`` and
     ``kubectl``.
     """
+    os.environ.setdefault(_SETUP_INVOCATION_ENV, _SETUP_INVOCATION)
     parser = argparse.ArgumentParser(
         prog="terok-executor",
         description="Single-agent task runner for hardened Podman containers",

{terok_executor-0.2.0 → terok_executor-0.3.0}/src/terok_executor/commands.py

@@ -202,7 +202,7 @@ def _resolve_host_git_identity() -> tuple[str | None, str | None]:
 def _handle_run(
     *,
     agent: str,
-    repo: str = ".",
+    repo: str | None = None,
     prompt: str | None = None,
     model: str | None = None,
     max_turns: int | None = None,
@@ -218,6 +218,8 @@ def _handle_run(
     gpu: bool = False,
     memory: str | None = None,
     cpus: str | None = None,
+    workspace: str | None = None,
+    ephemeral: bool = False,
     git_identity_from_host: bool = False,
     shared_dir: str | None = None,
     shared_mount: str = "/shared",
@@ -249,6 +251,11 @@ def _handle_run(
         else:
             print("Warning: --git-identity-from-host: git config user.name not set, skipping")
 
+    # Bare ``run <agent>`` works on an isolated clone of the current repo;
+    # with --workspace the mounted directory's own content is the default.
+    if repo is None and workspace is None:
+        repo = "."
+
     effective_gate = gate and not no_gate
     runner = AgentRunner(base_image=base, family=family, cfg=cfg)
     resolved_shared_dir = Path(shared_dir) if shared_dir else None
@@ -260,6 +267,8 @@ def _handle_run(
         "gpu": gpu,
         "memory": memory,
         "cpus": cpus,
+        "workspace": Path(workspace) if workspace else None,
+        "ephemeral": ephemeral,
         "human_name": human_name,
         "human_email": human_email,
         "authorship": authorship,
@@ -295,12 +304,14 @@ def _handle_run(
 def _handle_run_tool(
     *,
     tool: str,
-    repo: str = ".",
+    repo: str | None = None,
     branch: str | None = None,
     gate: bool = True,
     no_gate: bool = False,
     name: str | None = None,
     timeout: int = 600,
+    workspace: str | None = None,
+    ephemeral: bool = False,
     tool_args: list[str] | None = None,
     base: str = DEFAULT_BASE_IMAGE,
     family: str | None = None,
@@ -318,6 +329,11 @@ def _handle_run_tool(
 
     from .container.runner import AgentRunner
 
+    # Same default policy as ``run``: bare invocation works on an isolated
+    # clone of the current repo; --workspace brings its own content.
+    if repo is None and workspace is None:
+        repo = "."
+
     effective_gate = gate and not no_gate
     runner = AgentRunner(base_image=base, family=family, cfg=cfg)
     cname = runner.run_tool(
@@ -328,6 +344,8 @@ def _handle_run_tool(
         gate=effective_gate,
         name=name,
         timeout=timeout,
+        workspace=Path(workspace) if workspace else None,
+        ephemeral=ephemeral,
         timezone=timezone,
     )
     print(f"Container: {cname}")
@@ -338,10 +356,27 @@ def _handle_auth(
     agent: str,
     api_key: str | None = None,
     base_image: str | None = None,
+    device_auth: bool = False,
 ) -> None:
-    """Run auth flow for an agent."""
+    """Run auth flow for an agent.
+
+    With *device_auth* the interactive method chooser is skipped and the
+    provider's headless device-code login runs directly — for remote or
+    headless hosts where the browser callback can't open.  ``--api-key`` and
+    ``--device-auth`` are mutually exclusive; passing both takes the API-key
+    route (no container) and warns that ``--device-auth`` was ignored.
+    """
     from .credentials.auth import AUTH_PROVIDERS, Authenticator, store_api_key
 
+    if api_key is not None and device_auth:
+        import sys
+
+        print(
+            "Warning: --device-auth is ignored when --api-key is given; "
+            "the API key takes precedence (no auth container is launched).",
+            file=sys.stderr,
+        )
+
     if api_key is not None:
         if not api_key.strip():
             raise SystemExit("API key cannot be empty.")
@@ -361,6 +396,7 @@ def _handle_auth(
             None,
             mounts_dir=mounts_dir(),
             image=lambda: ImageBuilder(base).ensure_default_l1(),
+            device_auth=device_auth,
         )
 
     # Write vault URLs to shared config files (e.g. Vibe config.toml, gh config.yml)
@@ -455,12 +491,27 @@ def _handle_build(
 
 
 def _handle_list() -> None:
-    """List running terok-executor containers."""
+    """List executor-managed containers and their states.
+
+    Two name sources meet here: the ``terok-executor-`` default-name
+    prefix, and the per-container state dirs under
+    [`container_state_root`][terok_executor.paths.container_state_root]
+    — the latter makes ``--name`` overrides visible.  Podman stays the
+    truth for liveness: the dirs only contribute names to ask about,
+    and a name whose container is gone is skipped.
+    """
     from terok_executor.integrations.sandbox import PodmanRuntime
+    from terok_executor.paths import container_state_root
 
-    states = PodmanRuntime().container_states("terok-executor")
+    runtime = PodmanRuntime()
+    states = runtime.container_states("terok-executor")
+    run_root = container_state_root()
+    named = (p.name for p in run_root.iterdir() if p.is_dir()) if run_root.is_dir() else ()
+    for name in named:
+        if name not in states and (state := runtime.container(name).state) is not None:
+            states[name] = state
     if not states:
-        print("No running containers.")
+        print("No containers.")
         return
     for name, state in sorted(states.items()):
         print(f"{name}  {state}")
@@ -510,19 +561,57 @@ def _handle_show_config(*, cfg: SandboxConfig | None = None) -> None:
     yaml.dump(data, sys.stdout)
 
 
-def _handle_stop(*, name: str) -> None:
-    """Stop a running container (best-effort)."""
-    from terok_executor.integrations.sandbox import PodmanRuntime
+def _handle_start(*, name: str) -> None:
+    """Start a stopped container, re-establishing its host scaffolding."""
+    from terok_executor.integrations.sandbox import PodmanRuntime, Sandbox
 
-    runtime = PodmanRuntime()
-    container = runtime.container(name)
-    if container.state is None:
-        print(f"Container not found: {name}")
-        return
-    runtime.force_remove([container])
+    try:
+        Sandbox(runtime=PodmanRuntime()).start(name)
+    except RuntimeError as exc:
+        raise SystemExit(str(exc)) from exc
+    print(f"Started: {name}")
+
+
+def _handle_stop(*, name: str, timeout: int = 10) -> None:
+    """Stop a container, keeping it for a later ``start``.
+
+    A missing container is an error, exactly as ``podman stop`` treats
+    it — the facade's ``RuntimeError`` carries podman's own message.
+    """
+    from terok_executor.integrations.sandbox import PodmanRuntime, Sandbox
+
+    try:
+        Sandbox(runtime=PodmanRuntime()).stop([name], timeout=timeout)
+    except RuntimeError as exc:
+        raise SystemExit(str(exc)) from exc
     print(f"Stopped: {name}")
 
 
+def _handle_rm(*, name: str) -> None:
+    """Remove a container together with its host-side state.
+
+    Also sweeps the per-container state when the container is already
+    gone — the one situation (crash, out-of-band ``podman rm``) where
+    residue outlives its container.
+    """
+    import shutil
+
+    from terok_executor.integrations.sandbox import (
+        PodmanRuntime,
+        Sandbox,
+        remove_container_state,
+    )
+    from terok_executor.paths import container_state_dir
+
+    sandbox = Sandbox(runtime=PodmanRuntime())
+    [result] = sandbox.rm([name])
+    if not result.removed:
+        raise SystemExit(f"Could not remove {name}: {result.error}")
+    remove_container_state(name, cfg=sandbox.config)
+    shutil.rmtree(container_state_dir(name), ignore_errors=True)
+    print(f"Removed: {name}")
+
+
 def _handle_setup(
     *,
     check: bool = False,
@@ -530,6 +619,7 @@ def _handle_setup(
     no_images: bool = False,
     base: str = DEFAULT_BASE_IMAGE,
     family: str | None = None,
+    passphrase_tier: str | None = None,
     cfg: SandboxConfig | None = None,
 ) -> None:
     """Bootstrap the full terok-executor stack on a fresh host.
@@ -546,7 +636,7 @@ def _handle_setup(
     if not no_sandbox:
         from .sandbox import ensure_sandbox_ready
 
-        ensure_sandbox_ready(cfg=cfg)
+        ensure_sandbox_ready(cfg=cfg, passphrase_tier=passphrase_tier)
 
     if not no_images:
         _build_images_with_banner(base, family)
@@ -656,7 +746,13 @@ RUN_COMMAND = CommandDef(
     handler=_handle_run,
     args=(
         ArgDef(name="agent", help="Agent name (claude, codex, vibe, ...)"),
-        ArgDef(name="repo", nargs="?", default=".", help="Local path or git URL (default: .)"),
+        ArgDef(
+            name="repo",
+            nargs="?",
+            default=None,
+            help="Git URL or local dir cloned into the workspace via the gate "
+            "(default: . — unless --workspace brings its own content)",
+        ),
         ArgDef(name="-p", dest="prompt", help="Prompt for headless mode"),
         ArgDef(name="-m", dest="model", help="Model override"),
         ArgDef(name="--max-turns", type=int, help="Maximum agent turns"),
@@ -676,6 +772,17 @@ RUN_COMMAND = CommandDef(
         ArgDef(name="--gpu", action="store_true", help="Enable GPU passthrough"),
         ArgDef(name="--memory", help="Container memory limit (e.g. 4g, 512m)"),
         ArgDef(name="--cpus", help="Container CPU limit (e.g. 2.0, 0.5)"),
+        ArgDef(
+            name="--workspace",
+            help="Host directory to mount at /workspace "
+            "(default: the workspace lives in the container)",
+        ),
+        ArgDef(
+            name="--rm",
+            dest="ephemeral",
+            action="store_true",
+            help="Remove the container when it exits (podman --rm)",
+        ),
         ArgDef(
             name="--git-identity-from-host",
             action="store_true",
@@ -726,12 +833,29 @@ RUN_TOOL_COMMAND = CommandDef(
     handler=_handle_run_tool,
     args=(
         ArgDef(name="tool", help="Tool name (coderabbit)"),
-        ArgDef(name="repo", nargs="?", default=".", help="Local path or git URL (default: .)"),
+        ArgDef(
+            name="repo",
+            nargs="?",
+            default=None,
+            help="Git URL or local dir cloned into the workspace via the gate "
+            "(default: . — unless --workspace brings its own content)",
+        ),
         ArgDef(name="--branch", help="Git branch to check out"),
         ArgDef(name="--gate", action="store_true", default=True, help="Use gate (default)"),
         ArgDef(name="--no-gate", action="store_true", help="Disable gate"),
         ArgDef(name="--name", help="Container name override"),
         ArgDef(name="--timeout", type=int, default=600, help="Timeout in seconds (default: 600)"),
+        ArgDef(
+            name="--workspace",
+            help="Host directory to mount at /workspace "
+            "(default: the workspace lives in the container)",
+        ),
+        ArgDef(
+            name="--rm",
+            dest="ephemeral",
+            action="store_true",
+            help="Remove the container when it exits (podman --rm)",
+        ),
         ArgDef(name="tool_args", nargs="*", help="Extra args passed to the tool (after --)"),
         ArgDef(
             name="--base",
@@ -773,6 +897,11 @@ AUTH_COMMAND = CommandDef(
     args=(
         ArgDef(name="agent", help="Agent or tool name (claude, codex, gh, ...)"),
         ArgDef(name="--api-key", help="Store an API key directly (skip interactive auth)"),
+        ArgDef(
+            name="--device-auth",
+            action="store_true",
+            help="Force the headless device-code login (skip the method chooser)",
+        ),
         ArgDef(
             name="--base-image",
             help=(
@@ -871,7 +1000,7 @@ ACP_COMMAND = CommandDef(
 )
 
 
-LIST_COMMAND = CommandDef(name="list", help="List running containers", handler=_handle_list)
+LIST_COMMAND = CommandDef(name="list", help="List containers", handler=_handle_list)
 
 SHOW_CONFIG_COMMAND = CommandDef(
     name="show-config",
@@ -879,10 +1008,32 @@ SHOW_CONFIG_COMMAND = CommandDef(
     handler=_handle_show_config,
 )
 
+START_COMMAND = CommandDef(
+    name="start",
+    help="Start a stopped container",
+    handler=_handle_start,
+    args=(ArgDef(name="name", help="Container name"),),
+)
+
 STOP_COMMAND = CommandDef(
     name="stop",
-    help="Stop a running container",
+    help="Stop a container (kept for a later start)",
     handler=_handle_stop,
+    args=(
+        ArgDef(name="name", help="Container name"),
+        ArgDef(
+            name="--timeout",
+            type=int,
+            default=10,
+            help="Seconds before the stop escalates to SIGKILL (default: 10)",
+        ),
+    ),
+)
+
+RM_COMMAND = CommandDef(
+    name="rm",
+    help="Remove a container and its host-side state",
+    handler=_handle_rm,
     args=(ArgDef(name="name", help="Container name"),),
 )
 
@@ -918,6 +1069,15 @@ SETUP_COMMAND = CommandDef(
             default=None,
             help="Override package family for unknown base images (deb or rpm)",
         ),
+        ArgDef(
+            name="--passphrase-tier",
+            default=None,
+            help=(
+                "Force credentials-DB passphrase storage to a specific tier"
+                " (systemd-creds | keyring | session-file | config); required"
+                " on a non-TTY host without systemd-creds"
+            ),
+        ),
     ),
 )
 
@@ -956,7 +1116,9 @@ COMMANDS: tuple[CommandDef, ...] = (
     SETUP_COMMAND,
     UNINSTALL_COMMAND,
     LIST_COMMAND,
+    START_COMMAND,
     STOP_COMMAND,
+    RM_COMMAND,
     SHOW_CONFIG_COMMAND,
     ACP_COMMAND,
 )