impreza-cli 0.5.1__tar.gz → 0.7.0__tar.gz

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: impreza-cli
-Version: 0.5.1
+Version: 0.7.0
 Summary: Official command-line interface for the Impreza Host public REST API
 Author-email: Impreza Host <support@imprezahost.com>
 License: MIT
@@ -23,7 +23,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: impreza-sdk<0.6,>=0.5.0
+Requires-Dist: impreza-sdk<0.8,>=0.7.0
 Requires-Dist: typer>=0.12
 Requires-Dist: rich>=13.7
 Requires-Dist: click>=8.0
@@ -227,23 +227,33 @@ equivalent) and `impreza <TAB>` should suggest resource groups,
 
 ## Tor
 
-Inherited from the SDK. Three knobs:
+Four knobs, from the most persistent to the most one-off:
 
 ```bash
-# Per-context override at create time
-impreza context create offshore \
-  --key imp_... --secret ... \
-  # No --proxy flag yet; for now, set IMPREZA_USE_TOR before invoking
+# Persisted at context creation (writes [settings] use_tor=true)
+impreza context create offshore --key imp_... --secret ... --via-tor
+
+# Explicit SOCKS5 proxy instead (wins over use_tor; works for any
+# SOCKS5, not just Tor)
+impreza context create offshore --key imp_... --secret ...   --proxy socks5://127.0.0.1:9050
+
+# One-shot global flag on any command
+impreza --via-tor account info
 
 # Env var, picked up by the SDK transparently
 IMPREZA_USE_TOR=1 impreza account info
-
-# Programmatic via the SDK (Python users skip the CLI for this)
 ```
 
+All four route through the local Tor daemon's SOCKS5 port with remote
+DNS (no local lookup of the API hostname). Because exit nodes rotate,
+set the API key's IP factor to `tofu` or `keyonly` in the client area —
+`whitelist` cannot work without a stable egress IP. When the account
+uses the API's `.onion` mirror, the IP factor sees a stable loopback
+instead.
+
 The SDK's `auto_tor=True` path (probe Tor, fall back to clearnet)
-isn't surfaced through the CLI yet — coming in a future release
-alongside the `--via-tor` shortcut.
+isn't surfaced through the CLI yet — it is a fail-open convenience,
+which is the wrong default here.
 
 ## Error handling
 
@@ -259,6 +269,15 @@ Tracebacks never leak from expected failures (auth errors, missing
 contexts, 404s, 429s, etc.). Bugs in the CLI itself still raise so
 the traceback isn't swallowed — that's intentional.
 
+## Reviewed application configuration
+
+Version 0.6.0 adds configuration export, review and apply. Documents are limited
+to 64 KiB of UTF-8 and carry secret references instead of values. Applications
+retain their current configuration until a reviewed plan is explicitly applied.
+
+See [the configuration guide](https://docs.imprezahost.com/customer-workflows.html#config-cli)
+for SDK and CLI examples, permissions, review expiry and replay behavior.
+
 ## Development
 
 ```bash

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/README.md

@@ -185,23 +185,33 @@ equivalent) and `impreza <TAB>` should suggest resource groups,
 
 ## Tor
 
-Inherited from the SDK. Three knobs:
+Four knobs, from the most persistent to the most one-off:
 
 ```bash
-# Per-context override at create time
-impreza context create offshore \
-  --key imp_... --secret ... \
-  # No --proxy flag yet; for now, set IMPREZA_USE_TOR before invoking
+# Persisted at context creation (writes [settings] use_tor=true)
+impreza context create offshore --key imp_... --secret ... --via-tor
+
+# Explicit SOCKS5 proxy instead (wins over use_tor; works for any
+# SOCKS5, not just Tor)
+impreza context create offshore --key imp_... --secret ...   --proxy socks5://127.0.0.1:9050
+
+# One-shot global flag on any command
+impreza --via-tor account info
 
 # Env var, picked up by the SDK transparently
 IMPREZA_USE_TOR=1 impreza account info
-
-# Programmatic via the SDK (Python users skip the CLI for this)
 ```
 
+All four route through the local Tor daemon's SOCKS5 port with remote
+DNS (no local lookup of the API hostname). Because exit nodes rotate,
+set the API key's IP factor to `tofu` or `keyonly` in the client area —
+`whitelist` cannot work without a stable egress IP. When the account
+uses the API's `.onion` mirror, the IP factor sees a stable loopback
+instead.
+
 The SDK's `auto_tor=True` path (probe Tor, fall back to clearnet)
-isn't surfaced through the CLI yet — coming in a future release
-alongside the `--via-tor` shortcut.
+isn't surfaced through the CLI yet — it is a fail-open convenience,
+which is the wrong default here.
 
 ## Error handling
 
@@ -217,6 +227,15 @@ Tracebacks never leak from expected failures (auth errors, missing
 contexts, 404s, 429s, etc.). Bugs in the CLI itself still raise so
 the traceback isn't swallowed — that's intentional.
 
+## Reviewed application configuration
+
+Version 0.6.0 adds configuration export, review and apply. Documents are limited
+to 64 KiB of UTF-8 and carry secret references instead of values. Applications
+retain their current configuration until a reviewed plan is explicitly applied.
+
+See [the configuration guide](https://docs.imprezahost.com/customer-workflows.html#config-cli)
+for SDK and CLI examples, permissions, review expiry and replay behavior.
+
 ## Development
 
 ```bash

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/commands/_helpers.py

@@ -28,11 +28,10 @@ Conventions kept consistent across every CLI command:
 from __future__ import annotations
 
 import time
-from typing import Any
 from urllib.parse import quote
 
 import typer
-from impreza import Operation, Vps
+from impreza import Client, Operation, Vps
 from impreza.exceptions import ApiError, InvalidRequest, ResourceNotFound
 
 from ..output import error
@@ -85,7 +84,7 @@ def exit_on_api_error(exc: ApiError) -> None:
     raise typer.Exit(code=1)
 
 
-def resolve_vps_or_exit(client: Any, service_id: int) -> Vps:
+def resolve_vps_or_exit(client: Client, service_id: int) -> Vps:
     """Look up a VPS by id, mapping the standard SDK errors to the
     same friendly stderr lines the 3.2 power verbs introduced.
 

impreza_cli-0.7.0/impreza_cli/commands/config.py

@@ -0,0 +1,220 @@
+"""``impreza config`` — configuration as code for custom deployments (P4).
+
+Three commands over the reviewed config surface:
+
+* ``impreza config export <deployment> [--out FILE]`` — write the versioned
+  document (secrets as references) to stdout or a file;
+* ``impreza config apply <deployment> --file FILE [--yes]`` — prepare a
+  reviewed apply from the document, show the server-computed diff, and only
+  queue it after an explicit confirmation. The apply carries the exact
+  review digest, so what you confirmed is byte-for-byte what runs;
+* ``impreza config plan <plan-id>`` — read a saved review's status or
+  replay its receipt.
+
+The document is meant for version control: export it, commit it, edit it,
+apply it. Secret values never appear in the document — applying resolves
+the references server-side.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+from pathlib import Path
+
+import typer
+from impreza.exceptions import ApiError
+
+from ..output import error, success
+from ..sdk import make_client_or_exit
+from ..state import confirm_or_exit, from_typer_context
+from ._helpers import exit_on_api_error
+
+app = typer.Typer(
+    name="config",
+    help="Export, review and apply versioned application configuration.",
+    no_args_is_help=True,
+)
+
+
+def _terminal_text(value: str) -> str:
+    # Escape terminal control characters and bidi overrides in server text.
+    return "".join(
+        ch
+        if ch in "\n\t"
+        or (
+            ord(ch) >= 32
+            and not 127 <= ord(ch) <= 159
+            and not 0x202A <= ord(ch) <= 0x202E
+            and not 0x2066 <= ord(ch) <= 0x2069
+        )
+        else f"\\u{ord(ch):04x}"
+        for ch in value
+    )
+
+
+@app.command("export")
+def export(
+    typer_ctx: typer.Context,
+    deployment_id: str = typer.Argument(..., help="Custom deployment id (dpl_…)."),
+    out: Path | None = typer.Option(
+        None,
+        "--out",
+        "-o",
+        help="Write the document to this file instead of stdout.",
+    ),
+) -> None:
+    """Export the versioned config document (secrets as references)."""
+    client = make_client_or_exit(from_typer_context(typer_ctx))
+    try:
+        payload = client.config.export(deployment_id)
+    except ApiError as exc:
+        exit_on_api_error(exc)
+    except ValueError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    document_text = payload.get("document_text")
+    if not isinstance(document_text, str) or not document_text.strip():
+        error("The export carried no document text.")
+        raise typer.Exit(1)
+    if out is not None:
+        out.write_text(document_text, encoding="utf-8")
+        success(
+            f"Exported config for {payload.get('deployment_id', deployment_id)} "
+            f"(schema {payload.get('schema', '?')}) to {out}."
+        )
+        return
+    typer.echo(document_text, nl=False)
+
+
+@app.command("apply")
+def apply(
+    typer_ctx: typer.Context,
+    deployment_id: str = typer.Argument(..., help="Custom deployment id (dpl_…)."),
+    file: Path = typer.Option(
+        ...,
+        "--file",
+        "-f",
+        help="Config document to apply (as written by `impreza config export`).",
+        exists=True,
+        readable=True,
+        dir_okay=False,
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Apply without the interactive confirmation prompt.",
+    ),
+) -> None:
+    """Prepare a reviewed apply from a document, show its diff, confirm, apply."""
+    try:
+        if not file.is_file():
+            raise ValueError("Config input must be a regular file.")
+        # Nonblocking open also prevents a raced replacement with a FIFO from
+        # hanging automation. Validate the opened descriptor, then bound reads.
+        fd = os.open(file, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0))
+        with os.fdopen(fd, "rb") as stream:
+            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                raise ValueError("Config input must be a regular file.")
+            raw = stream.read(65537)
+        if not raw or len(raw) > 65536:
+            raise ValueError("Config document must contain 1 to 65536 UTF-8 bytes.")
+        document = raw.decode("utf-8")
+    except (OSError, ValueError) as exc:
+        error("Cannot read config document: " + str(exc))
+        raise typer.Exit(1) from exc
+    client = make_client_or_exit(from_typer_context(typer_ctx))
+    try:
+        review = client.config.prepare(deployment_id, document)
+    except ApiError as exc:
+        exit_on_api_error(exc)
+    except ValueError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    plan_id = review.get("plan_id")
+    review_digest = review.get("review_digest")
+    changes = review.get("changes")
+    diff_text = review.get("diff_text")
+    if (
+        not isinstance(plan_id, str)
+        or re.fullmatch(r"cplan_[a-f0-9]{24}", plan_id) is None
+        or not isinstance(review_digest, str)
+        or re.fullmatch(r"[a-f0-9]{64}", review_digest) is None
+        or review.get("deployment_id") != deployment_id
+        or review.get("operation") != "config_apply"
+        or not isinstance(changes, list)
+        or not all(isinstance(item, str) for item in changes)
+        or not isinstance(diff_text, str)
+        or review.get("no_changes") is not (changes == [])
+    ):
+        error(
+            "The review response is incomplete or does not match this deployment; "
+            "nothing was applied."
+        )
+        raise typer.Exit(1)
+
+    if isinstance(changes, (list, dict)) and changes:
+        typer.secho("Planned changes:", fg=typer.colors.YELLOW, bold=True)
+        if isinstance(changes, dict):
+            for key, value in changes.items():
+                typer.echo(f"  {key}: {value}")
+        else:
+            for line in changes:
+                typer.echo(_terminal_text(f"  {line}"))
+    else:
+        typer.echo("No changes detected — the apply is idempotent for this document.")
+    if isinstance(diff_text, str) and diff_text.strip():
+        typer.echo("")
+        typer.secho("Diff:", fg=typer.colors.YELLOW, bold=True)
+        typer.echo(_terminal_text(diff_text.rstrip()))
+
+    typer.echo("")
+    confirm_or_exit(f"Apply this configuration to {deployment_id}.", yes=yes)
+    try:
+        result = client.config.apply(plan_id, review_digest)
+    except ApiError as exc:
+        exit_on_api_error(exc)
+    except ValueError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    receipt = result.get("receipt")
+    if not isinstance(receipt, dict):
+        receipt = result
+    command_id = result.get("command_id") or receipt.get("command_id")
+    replayed = bool(result.get("replayed"))
+    if replayed:
+        success(f"Plan {plan_id} was already accepted — replayed its receipt.")
+    else:
+        success(f"Configuration applied (plan {plan_id}).")
+    if isinstance(command_id, str) and command_id:
+        typer.echo(_terminal_text(f"Deploy command: {command_id}"))
+    if receipt.get("no_changes") is True:
+        typer.echo("No deployment was queued because the configuration already matches.")
+    else:
+        typer.echo("The change is queued; watch the deployment's status or the command above.")
+
+
+@app.command("plan")
+def plan(
+    typer_ctx: typer.Context,
+    plan_id: str = typer.Argument(..., help="Config plan id (cplan_…)."),
+) -> None:
+    """Read one saved config review: status, digest and receipt."""
+    client = make_client_or_exit(from_typer_context(typer_ctx))
+    try:
+        payload = client.config.get_plan(plan_id)
+    except ApiError as exc:
+        exit_on_api_error(exc)
+    except ValueError as exc:
+        error(str(exc))
+        raise typer.Exit(1) from exc
+    status = payload.get("status", "unknown")
+    typer.echo(_terminal_text(f"Plan {plan_id}: {status}"))
+    digest = payload.get("review_digest")
+    if isinstance(digest, str) and digest:
+        typer.echo(_terminal_text(f"Review digest: {digest}"))
+    receipt = payload.get("receipt")
+    if isinstance(receipt, dict):
+        typer.echo(f"Receipt: {receipt}")

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/commands/context.py

@@ -88,6 +88,18 @@ def create(
         help="Optional default output format for this context.",
         case_sensitive=False,
     ),
+    via_tor: bool = typer.Option(
+        False,
+        "--via-tor",
+        help="Route API calls through the local Tor daemon "
+        "(sets [settings] use_tor=true, CLI-wide).",
+    ),
+    proxy: str | None = typer.Option(
+        None,
+        "--proxy",
+        help="Explicit SOCKS5 proxy, e.g. socks5://127.0.0.1:9050 "
+        "(sets [settings] proxy, CLI-wide; wins over use_tor).",
+    ),
     overwrite: bool = typer.Option(
         False,
         "--overwrite",
@@ -108,6 +120,12 @@ def create(
         )
     except (ContextAlreadyExists, InvalidContextName) as exc:
         _exit_on_config_error(exc)
+
+    if via_tor or proxy:
+        if via_tor:
+            cfg.settings.use_tor = True
+        if proxy:
+            cfg.settings.proxy = proxy
     cfg.save()
 
     is_default = cfg.default_context == name

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/commands/dedicated.py

@@ -45,7 +45,7 @@ Reinstall (destructive — wipes ALL data):
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Literal, cast
 
 import typer
 from impreza.exceptions import ApiError
@@ -76,9 +76,11 @@ def _emit(value: Any, *, ctx: typer.Context, title: str) -> None:
     """
     fmt = resolve_output(from_typer_context(ctx), None)
     if isinstance(value, list):
-        rows = value if all(isinstance(row, dict) for row in value) else [
-            {"value": item} for item in value
-        ]
+        rows = (
+            value
+            if all(isinstance(row, dict) for row in value)
+            else [{"value": item} for item in value]
+        )
         print_table(title, rows, fmt=fmt)
     elif isinstance(value, dict):
         print_dict(title, value, fmt=fmt)
@@ -356,8 +358,15 @@ def cmd_set_firewall(
     """Update DDoS firewall state/sensitivity for an IP. Requires the ``firewall`` capability."""
     client = make_client_or_exit(from_typer_context(ctx))
     try:
+        if state not in (None, "always_on", "redirect_on_attack"):
+            raise typer.BadParameter("Use always_on or redirect_on_attack.", param_hint="--state")
+        if sensitivity not in (None, "low", "normal", "medium", "high"):
+            raise typer.BadParameter("Use low, normal, medium or high.", param_hint="--sensitivity")
         data = client.dedicated.set_firewall(
-            service_id, ip=ip, state=state, sensitivity=sensitivity
+            service_id,
+            ip=ip,
+            state=cast(Literal["always_on", "redirect_on_attack"] | None, state),
+            sensitivity=cast(Literal["low", "normal", "medium", "high"] | None, sensitivity),
         )
     except ApiError as exc:
         exit_on_api_error(exc)
@@ -382,7 +391,32 @@ def cmd_bandwidth(
     """Bandwidth graph (PNG base64). Requires the ``bandwidth`` capability."""
     client = make_client_or_exit(from_typer_context(ctx))
     try:
-        data = client.dedicated.bandwidth(service_id, type=type, scale=scale)
+        if type not in (
+            "port_bits",
+            "port_upkts",
+            "port_percent",
+            "port_errors",
+            "port_pktsize",
+            "port_discards",
+        ):
+            raise typer.BadParameter("Unsupported bandwidth type.", param_hint="--type")
+        if scale not in ("day", "week", "month"):
+            raise typer.BadParameter("Use day, week or month.", param_hint="--scale")
+        data = client.dedicated.bandwidth(
+            service_id,
+            type=cast(
+                Literal[
+                    "port_bits",
+                    "port_upkts",
+                    "port_percent",
+                    "port_errors",
+                    "port_pktsize",
+                    "port_discards",
+                ],
+                type,
+            ),
+            scale=cast(Literal["day", "week", "month"], scale),
+        )
     except ApiError as exc:
         exit_on_api_error(exc)
         return

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/commands/vps_cloud.py

@@ -178,6 +178,7 @@ def images_list(
     if not images:
         typer.echo("No images saved on this account.")
         return
+    rows: list[dict[str, Any]]
     if fmt is OutputFormat.TABLE:
         rows = [
             {

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/config.py

@@ -167,6 +167,7 @@ class _Settings:
 
     poll_interval: float | None = None
     use_tor: bool | None = None
+    proxy: str | None = None
 
     def to_toml_dict(self) -> dict[str, Any]:
         body: dict[str, Any] = {}
@@ -174,6 +175,8 @@ class _Settings:
             body["poll_interval"] = self.poll_interval
         if self.use_tor is not None:
             body["use_tor"] = self.use_tor
+        if self.proxy is not None:
+            body["proxy"] = self.proxy
         return body
 
 
@@ -267,6 +270,9 @@ class Config:
             tor = settings_raw.get("use_tor")
             if isinstance(tor, bool):
                 settings.use_tor = tor
+            proxy = settings_raw.get("proxy")
+            if isinstance(proxy, str) and proxy:
+                settings.proxy = proxy
 
         default_context = raw.get("default_context")
         if not isinstance(default_context, str):

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/main.py

@@ -18,6 +18,7 @@ import typer
 from . import __version__
 from .commands import account as account_cmd
 from .commands import catalog as catalog_cmd
+from .commands import config as config_cmd
 from .commands import context as context_cmd
 from .commands import dedicated as dedicated_cmd
 from .commands import doctor as doctor_cmd
@@ -61,6 +62,15 @@ def _root(
         "-c",
         help="Override the default context for this invocation.",
     ),
+    via_tor: bool = typer.Option(
+        False,
+        "--via-tor",
+        help=(
+            "Route this invocation through the local Tor daemon "
+            "(SOCKS5 127.0.0.1:9050). Overrides [settings] use_tor once; "
+            "persist it with `impreza context create --via-tor`."
+        ),
+    ),
     output: OutputFormat | None = typer.Option(
         None,
         "--output",
@@ -77,7 +87,7 @@ def _root(
     Global flags ``--context`` and ``--output`` apply to every
     subcommand and are inherited via Typer's context object.
     """
-    ctx.obj = GlobalState(context_override=context, output=output)
+    ctx.obj = GlobalState(context_override=context, output=output, via_tor=via_tor)
 
 
 # ── Subcommand mounts ────────────────────────────────────────────────
@@ -86,6 +96,7 @@ def _root(
 # ``impreza --help`` output reads predictably.
 app.add_typer(account_cmd.app, name="account")
 app.add_typer(catalog_cmd.app, name="catalog")
+app.add_typer(config_cmd.app, name="config")
 app.add_typer(context_cmd.app, name="context")
 app.add_typer(dedicated_cmd.app, name="dedicated")
 app.add_typer(doctor_cmd.app, name="doctor")

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/sdk.py

@@ -69,10 +69,13 @@ def make_client(
     if ctx.base_url:
         kwargs["base_url"] = ctx.base_url
 
-    # Tor preference comes from the [settings] block (CLI-wide). A
-    # future per-context override (one VPN context, one clearnet, etc.)
+    # Tor/proxy preference: an explicit [settings] proxy wins; then the
+    # one-shot global --via-tor flag; then the CLI-wide use_tor setting.
+    # A future per-context override (one VPN context, one clearnet, etc.)
     # would slot in here without touching callers.
-    if cfg.settings.use_tor:
+    if cfg.settings.proxy:
+        kwargs["proxy"] = cfg.settings.proxy
+    elif state.via_tor or cfg.settings.use_tor:
         kwargs["use_tor"] = True
 
     return Client(**kwargs)

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli/state.py

@@ -31,6 +31,11 @@ class GlobalState:
     #: ``None`` means "use the config file's ``default_context``".
     context_override: str | None = None
 
+    #: One-shot Tor routing selected via the global ``--via-tor`` flag.
+    #: Overrides the config file's ``[settings] use_tor`` for this
+    #: invocation only; ``None``/False means "follow the config".
+    via_tor: bool = False
+
     #: Default output format selected via the global ``--output`` flag.
     #: Per-command ``--output`` flags can override this on a single
     #: invocation; ``None`` here means "no preference, fall back to

{impreza_cli-0.5.1 → impreza_cli-0.7.0}/impreza_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: impreza-cli
-Version: 0.5.1
+Version: 0.7.0
 Summary: Official command-line interface for the Impreza Host public REST API
 Author-email: Impreza Host <support@imprezahost.com>
 License: MIT
@@ -23,7 +23,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: impreza-sdk<0.6,>=0.5.0
+Requires-Dist: impreza-sdk<0.8,>=0.7.0
 Requires-Dist: typer>=0.12
 Requires-Dist: rich>=13.7
 Requires-Dist: click>=8.0
@@ -227,23 +227,33 @@ equivalent) and `impreza <TAB>` should suggest resource groups,
 
 ## Tor
 
-Inherited from the SDK. Three knobs:
+Four knobs, from the most persistent to the most one-off:
 
 ```bash
-# Per-context override at create time
-impreza context create offshore \
-  --key imp_... --secret ... \
-  # No --proxy flag yet; for now, set IMPREZA_USE_TOR before invoking
+# Persisted at context creation (writes [settings] use_tor=true)
+impreza context create offshore --key imp_... --secret ... --via-tor
+
+# Explicit SOCKS5 proxy instead (wins over use_tor; works for any
+# SOCKS5, not just Tor)
+impreza context create offshore --key imp_... --secret ...   --proxy socks5://127.0.0.1:9050
+
+# One-shot global flag on any command
+impreza --via-tor account info
 
 # Env var, picked up by the SDK transparently
 IMPREZA_USE_TOR=1 impreza account info
-
-# Programmatic via the SDK (Python users skip the CLI for this)
 ```
 
+All four route through the local Tor daemon's SOCKS5 port with remote
+DNS (no local lookup of the API hostname). Because exit nodes rotate,
+set the API key's IP factor to `tofu` or `keyonly` in the client area —
+`whitelist` cannot work without a stable egress IP. When the account
+uses the API's `.onion` mirror, the IP factor sees a stable loopback
+instead.
+
 The SDK's `auto_tor=True` path (probe Tor, fall back to clearnet)
-isn't surfaced through the CLI yet — coming in a future release
-alongside the `--via-tor` shortcut.
+isn't surfaced through the CLI yet — it is a fail-open convenience,
+which is the wrong default here.
 
 ## Error handling
 
@@ -259,6 +269,15 @@ Tracebacks never leak from expected failures (auth errors, missing
 contexts, 404s, 429s, etc.). Bugs in the CLI itself still raise so
 the traceback isn't swallowed — that's intentional.
 
+## Reviewed application configuration
+
+Version 0.6.0 adds configuration export, review and apply. Documents are limited
+to 64 KiB of UTF-8 and carry secret references instead of values. Applications
+retain their current configuration until a reviewed plan is explicitly applied.
+
+See [the configuration guide](https://docs.imprezahost.com/customer-workflows.html#config-cli)
+for SDK and CLI examples, permissions, review expiry and replay behavior.
+
 ## Development
 
 ```bash