impreza-cli 0.3.0__py3-none-any.whl

impreza_cli/output.py

@@ -0,0 +1,207 @@
+"""Output formatting for CLI commands.
+
+The CLI supports three output modes selected via the global
+``--output`` flag (default: ``table``):
+
+* ``table`` — Rich-rendered tables for human consumption (default).
+* ``json``  — UTF-8 JSON, pretty-printed with 2-space indent. Pipes
+  cleanly into ``jq`` and friends.
+* ``yaml``  — defer-imported PyYAML output (only loaded when actually
+  selected so the import cost is paid only on use).
+
+Phase 2.1 ships only ``table`` and ``json`` since the context
+commands' output is small. ``yaml`` lands in Phase 2.7 alongside the
+output polish + tab completion pass; the ``OutputFormat`` enum
+already lists it so command code can target the final API today and
+the 2.7 work is purely additive.
+
+Stderr is a separate channel via :func:`error` — used for
+user-visible errors (typed config failures, etc.) so the success
+output on stdout stays scriptable.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from enum import Enum
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+__all__ = [
+    "OutputFormat",
+    "error",
+    "info",
+    "print_dict",
+    "print_table",
+    "success",
+    "warning",
+]
+
+
+class OutputFormat(str, Enum):
+    """Selectable output mode. ``str``-mixin so it round-trips
+    cleanly through Typer's `--output` flag."""
+
+    TABLE = "table"
+    JSON = "json"
+    YAML = "yaml"
+
+
+_stdout = Console()
+
+
+def error(message: str) -> None:
+    """Print a user-facing error message to stderr in red.
+
+    Uses ``typer.secho`` (line-based, via Click) rather than Rich
+    so the output doesn't wrap based on detected terminal width.
+    Wrapping was hiding the back half of long error messages
+    (e.g. ``[request_id=...]`` suffixes) from stderr capture in
+    CliRunner-driven tests, and would do the same to grep-piped
+    output on narrow real terminals.
+
+    Bugs should still raise so the traceback isn't swallowed —
+    this helper is only for friendly errors on expected failures.
+    """
+    typer.secho(f"Error: {message}", err=True, fg=typer.colors.RED, bold=True)
+
+
+def success(message: str) -> None:
+    """Print a user-facing success message to stdout in green.
+
+    Companion to :func:`error`. Use for the trailing "X created /
+    deleted / updated" line that confirms an operation took effect.
+    No "OK:" prefix — Phase 1.6's cp1252 lesson kept us off Unicode
+    glyphs and the colour itself reads as success cue without one.
+
+    Note: success messages go to stdout (not stderr) so they don't
+    confuse scripts that pipe stderr to /dev/null while parsing
+    stdout. Tests asserting against output should look at
+    ``result.stdout``.
+    """
+    typer.secho(message, fg=typer.colors.GREEN, bold=True)
+
+
+def info(message: str) -> None:
+    """Print a user-facing informational message to stdout in cyan.
+
+    Use for hints / status notes that aren't success per se —
+    "Reboot to apply", "Operation queued — uuid X", etc. The cyan
+    is distinct enough from green-success that a script-reading
+    user can tell at a glance whether something completed or is
+    waiting on an action.
+    """
+    typer.secho(message, fg=typer.colors.CYAN)
+
+
+def warning(message: str) -> None:
+    """Print a user-facing warning to stderr in yellow.
+
+    Goes to stderr (not stdout) so scripts capturing stdout for
+    parsing don't see the warning in their data stream. Use for
+    "the call succeeded but something looks off" cases —
+    deprecation hints, surprising upstream behaviour, edge
+    conditions that don't actually fail.
+    """
+    typer.secho(f"Warning: {message}", err=True, fg=typer.colors.YELLOW)
+
+
+def print_table(
+    title: str,
+    rows: list[dict[str, Any]],
+    *,
+    columns: list[str] | None = None,
+    fmt: OutputFormat = OutputFormat.TABLE,
+) -> None:
+    """Render ``rows`` (list of homogenous dicts) per the chosen format.
+
+    ``columns`` overrides the column order. When omitted, columns are
+    taken from the first row's key order — Python 3.7+ preserves
+    dict insertion order so this is deterministic per the calling
+    code.
+
+    Empty ``rows`` is acceptable; we render an empty table with the
+    headers (or print ``[]`` for JSON).
+    """
+    if fmt is OutputFormat.JSON:
+        sys.stdout.write(json.dumps(rows, indent=2, ensure_ascii=False))
+        sys.stdout.write("\n")
+        return
+
+    if fmt is OutputFormat.YAML:
+        _yaml_dump(rows)
+        return
+
+    # Table rendering.
+    if columns is None:
+        columns = list(rows[0].keys()) if rows else []
+    table = Table(title=title, header_style="bold cyan", show_lines=False)
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*[_render_cell(row.get(col)) for col in columns])
+    _stdout.print(table)
+
+
+def print_dict(
+    title: str,
+    data: dict[str, Any],
+    *,
+    fmt: OutputFormat = OutputFormat.TABLE,
+) -> None:
+    """Render a single resource (dict) — two-column ``Field / Value``
+    table by default."""
+    if fmt is OutputFormat.JSON:
+        sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False))
+        sys.stdout.write("\n")
+        return
+
+    if fmt is OutputFormat.YAML:
+        _yaml_dump(data)
+        return
+
+    table = Table(title=title, header_style="bold cyan", show_header=True)
+    table.add_column("Field")
+    table.add_column("Value")
+    for k, v in data.items():
+        table.add_row(str(k), _render_cell(v))
+    _stdout.print(table)
+
+
+def _render_cell(value: Any) -> str:
+    """Format a single cell for table rendering.
+
+    Uses ASCII glyphs (``-``, ``yes`` / ``no``) rather than fancy
+    Unicode (``—`` / ``✓`` / ``✗``) because Windows legacy consoles
+    default to cp1252 and crash on the latter — Phase 1.6's smoke
+    learned this the hard way and we want CLI output to read on
+    every terminal, not just modern UTF-8 ones.
+    """
+    if value is None:
+        return "[dim]-[/]"
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    return str(value)
+
+
+def _yaml_dump(data: Any) -> None:
+    """Defer-import PyYAML so installs that never touch YAML output
+    don't pay the dependency cost.
+
+    Phase 2.7 wired pyyaml as the optional ``[yaml]`` extra. Calling
+    this function on an install that didn't pull in that extra
+    surfaces a clear ImportError telling the user how to upgrade or
+    pick a different format.
+    """
+    try:
+        import yaml
+    except ImportError as exc:
+        raise RuntimeError(
+            "YAML output requires the optional `pyyaml` dependency. "
+            "Install with: pip install impreza-cli[yaml]"
+        ) from exc
+    sys.stdout.write(yaml.safe_dump(data, sort_keys=False, allow_unicode=True))

impreza_cli/sdk.py

@@ -0,0 +1,97 @@
+"""SDK bootstrap — single source of truth for "given a context, hand
+me an :class:`impreza.Client`".
+
+Every command that needs to call the API goes through this module so
+the resolution rules (which context, which base URL, Tor or not)
+live in one place. Adding new resolution sources later (per-context
+``proxy=`` overrides, env-var fallbacks, etc.) is a one-file change.
+
+The SDK's own :func:`Client.from_env` reads ``IMPREZA_API_KEY`` /
+``IMPREZA_API_SECRET`` directly from the environment — that path
+stays available for users who prefer env-var auth and bypass the
+context machinery entirely. This module is for the context-driven
+path (the CLI's primary UX).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import typer
+from impreza import Client
+
+from .config import Config, ConfigError
+from .output import error
+from .state import GlobalState
+
+__all__ = [
+    "make_client",
+    "make_client_or_exit",
+]
+
+
+def make_client(
+    state: GlobalState,
+    *,
+    config_path: Path | None = None,
+) -> Client:
+    """Build a sync :class:`impreza.Client` from the active context.
+
+    Args:
+        state: The CLI's :class:`~.state.GlobalState`. Reads
+            ``state.context_override`` to pick a non-default context.
+        config_path: Optional override for the config file location
+            (mostly used in tests; production flow always uses the
+            default).
+
+    Raises:
+        ConfigError: any of the config-resolution errors —
+            :class:`~.config.NoContextsConfigured`,
+            :class:`~.config.NoActiveContext`,
+            :class:`~.config.ContextNotFound`. The :func:`make_client_or_exit`
+            wrapper catches these for the typical CLI command flow;
+            tests / library callers can let them propagate.
+
+    Returns:
+        A sync :class:`Client` ready to call. Caller is responsible
+        for closing it (the standard `with Client(...) as c:` pattern
+        works — Typer commands just let it close on process exit
+        which is fine for short-lived CLI invocations).
+    """
+    cfg = Config.load(config_path)
+    ctx = cfg.get_context(state.context_override)
+
+    kwargs: dict[str, Any] = {
+        "api_key": ctx.api_key,
+        "api_secret": ctx.api_secret,
+    }
+    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.)
+    # would slot in here without touching callers.
+    if cfg.settings.use_tor:
+        kwargs["use_tor"] = True
+
+    return Client(**kwargs)
+
+
+def make_client_or_exit(
+    state: GlobalState,
+    *,
+    config_path: Path | None = None,
+) -> Client:
+    """Same as :func:`make_client`, but converts config errors into
+    friendly stderr output and a non-zero exit.
+
+    This is the path every Typer command follows. Bugs (network
+    errors at construction time, etc.) still raise so the traceback
+    isn't swallowed.
+    """
+    try:
+        return make_client(state, config_path=config_path)
+    except ConfigError as exc:
+        error(str(exc))
+        raise typer.Exit(code=1) from None

impreza_cli/state.py

@@ -0,0 +1,94 @@
+"""CLI-wide shared state passed between the root callback and
+subcommands via ``typer.Context.obj``.
+
+Subcommands never read these flags from their own argument list —
+they pull them off ``ctx.obj`` so the same flag can be set at the
+``impreza`` root (`impreza --output json account info`) or at the
+subcommand level (`impreza account info --output json`). Per-command
+overrides win; falling back through to the context override and
+then the table default.
+
+The state object is intentionally tiny — only fields that are read
+by more than one command should live here. Anything specific to a
+single command stays as a regular function argument.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import typer
+
+from .output import OutputFormat
+
+
+@dataclass
+class GlobalState:
+    """Values populated by the root callback and shared with every
+    subcommand."""
+
+    #: When set, the named context is used instead of the default.
+    #: ``None`` means "use the config file's ``default_context``".
+    context_override: str | None = None
+
+    #: 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
+    #: the table default".
+    output: OutputFormat | None = None
+
+
+def from_typer_context(ctx: typer.Context) -> GlobalState:
+    """Pull the :class:`GlobalState` off a Typer context.
+
+    Typer's :attr:`Context.obj` is typed as ``Any`` — this helper
+    narrows it back to ``GlobalState`` so callers don't have to
+    sprinkle ``cast()`` calls. If for any reason the obj is missing
+    (test invocation that bypasses the root callback, etc.), an
+    empty ``GlobalState`` is returned so commands don't NPE.
+    """
+    obj = getattr(ctx, "obj", None)
+    if isinstance(obj, GlobalState):
+        return obj
+    return GlobalState()
+
+
+def resolve_output(
+    state: GlobalState,
+    per_command: OutputFormat | None,
+) -> OutputFormat:
+    """Pick the output format for a single command invocation.
+
+    Resolution order: per-command `--output` flag > global `--output`
+    flag > :attr:`OutputFormat.TABLE` default.
+    """
+    if per_command is not None:
+        return per_command
+    if state.output is not None:
+        return state.output
+    return OutputFormat.TABLE
+
+
+def confirm_or_exit(message: str, *, yes: bool) -> None:
+    """Prompt the user to confirm a destructive / costly action.
+
+    The standard pattern across every Phase 3 mutating command:
+
+    .. code-block:: python
+
+        confirm_or_exit("This will charge $12.99 from your balance.", yes=yes)
+
+    When ``yes=True`` the prompt is skipped (intent already opted-in
+    via the ``--yes`` flag). When the user declines, the CLI prints
+    "Cancelled." on stdout and exits 0 — declining is not an error.
+
+    The message should be a complete sentence describing what's
+    about to happen; the helper appends "Continue?" automatically.
+    """
+    import typer  # local import keeps state.py importable without typer
+
+    if yes:
+        return
+    if not typer.confirm(f"{message} Continue?", default=False):
+        typer.echo("Cancelled.")
+        raise typer.Exit(code=0)

impreza_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: impreza-cli
+Version: 0.3.0
+Summary: Official command-line interface for the Impreza Host public REST API
+Author-email: Impreza Host <support@imprezahost.com>
+License: MIT
+Project-URL: Homepage, https://imprezahost.com
+Project-URL: Documentation, https://docs.imprezahost.com
+Project-URL: Repository, https://github.com/imprezahost/impreza-devkit
+Project-URL: Changelog, https://github.com/imprezahost/impreza-devkit/blob/master/CHANGELOG.md
+Keywords: impreza,hosting,cli,offshore,crypto
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: impreza-sdk
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
+Requires-Dist: pyyaml>=6.0; extra == "test"
+Requires-Dist: types-PyYAML>=6.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+
+# `impreza-cli` — Official CLI for Impreza Host
+
+Command-line interface for the Impreza Host public REST API.
+Built on top of [`impreza-sdk`](../sdk-python/README.md) — same
+auth model, same Tor support, same retry behaviour, plus
+multi-context configuration and Rich-rendered tables for human-
+friendly output.
+
+```bash
+pip install impreza-cli
+```
+
+Requires Python 3.10+. See [`../CHANGELOG.md`](../CHANGELOG.md) for
+release history.
+
+## Quickstart
+
+```bash
+# 1. Add a context with your API credentials. Generate keys in
+#    Impreza Account → API Keys; whitelist the calling
+#    machine's IP at the same screen.
+$ impreza context create personal --key imp_... --secret ...
+Context 'personal' created and set as default.
+
+# 2. Confirm everything works. impreza doctor runs five sequenced
+#    health checks (config, API reachable, key status, IP
+#    whitelist, account profile) and exits 0 only if all pass.
+$ impreza doctor
+
+impreza doctor
+----------------------------------------
+[OK]    active-context: Default context
+[OK]    api-reachable: GET /account/api-keys/self OK (142ms)
+        key prefix='imp_a1b2c3d4', label='devkit'
+[OK]    key-status: status='active'
+[OK]    ip-whitelist: request_ip 200.1.2.3 matches entry ('home')
+[OK]    account-profile: Jane Doe <jane@example.com>, balance 5.00 USD
+                         registered 2024-01-15
+----------------------------------------
+All checks passed. 5/5.
+
+# 3. Read commands span every resource group:
+$ impreza account info             # profile + balance
+$ impreza vps list                 # across both backends
+$ impreza domain check example.com mydomain.io
+$ impreza catalog products --group "VPS"
+
+# 4. Pipe into jq for scripting (every read verb supports --output
+#    json | yaml):
+$ impreza invoice list --output json \
+    | jq '[.[] | select(.status == "Unpaid")] | length'
+
+# 5. Write verbs are gated by confirm_or_exit so you don't lose
+#    data accidentally; pass --yes / -y to skip prompts in scripts:
+$ impreza vps reboot 17988
+$ impreza vps proxmox snapshots create 17988 pre-update
+$ impreza domain dns add example.com --type A --name www --value 1.2.3.4
+
+# 6. Crypto top-up. --browser opens the BTCPay invoice URL
+#    automatically; --wait polls until the gateway confirms
+#    (default 2h timeout matches server-side invoice expiry).
+$ impreza account topup --amount 50 --method xmr --browser --wait
+```
+
+## Authentication
+
+Two ways to authenticate. The CLI tries them in order:
+
+1. **Context** (recommended) — `impreza context create <name>` stores
+   credentials in a config file; commands read them automatically.
+   Per-invocation override via `impreza --context other <command>`.
+
+2. **Environment variables** — `IMPREZA_API_KEY` + `IMPREZA_API_SECRET`.
+   Useful in CI, but contexts are preferred for local work.
+
+The config file lives at:
+
+| OS | Path |
+|---|---|
+| Linux | `$XDG_CONFIG_HOME/impreza/config.toml` (default `~/.config/impreza/config.toml`) |
+| macOS | `~/Library/Application Support/impreza/config.toml` |
+| Windows | `%APPDATA%\impreza\config.toml` |
+
+Override with `IMPREZA_CONFIG=/path/to/config.toml` for testing or
+non-standard layouts.
+
+On POSIX, the config file is `chmod 0o600` after every write so only
+the owner can read the credentials. Windows ACLs are left to the OS
+default.
+
+## Commands
+
+The CLI groups commands by resource. Run `impreza <group> --help`
+to see the full subcommand list, or `impreza <group> <command>
+--help` for option-level detail.
+
+| Group | Verbs | Notes |
+|---|---|---|
+| `context` | `create / use / list / current / delete` | Local credential management — never hits the network |
+| `doctor` | (single command) | Health check — config + API reachable + key status + IP whitelist + account profile |
+| `account` | `info / balance / services / topup / topup-status` | Profile + balance + services + crypto top-up |
+| `catalog` | `products / product / product-groups / tlds` | Pre-purchase discovery |
+| `domain` | `show / check / pricing / register / transfer / set-nameservers / lock / unlock / id-protection / raa-verify / gdpr-auth / transfer-approval` + `domain dns list / add / update / delete / activate` | Domain registrations + full DNS CRUD |
+| `vps` | `list / show / status / start / stop / reboot / shutdown / set-hostname / set-password / reinstall / migrate / cancel` + `vps proxmox snapshots / backups / backup-schedules / network` + `vps cloud images / rescue / iso / rdns / ssh-keys / vnc / vnc-password / resize / boot-order / ipv6` | Cross-backend (Proxmox + Cloud) VPS with smart dispatch |
+| `order` | `list / show / create / upgrade` | Submit / browse product orders |
+| `service` | `cancel` | Submit cancellation request (any service) |
+| `webhook` | `list / show / create / update / delete / rotate-secret / deliveries / event-types` | Webhook subscription management + delivery history |
+| `invoice` | `list / show` | Invoices with line items + transactions |
+| `key` | `whoami` | Active API key identity + IP whitelist |
+
+**Conventions:**
+
+- Destructive verbs prompt for confirmation; pass `--yes` / `-y`
+  to skip the prompt in scripts.
+- Operation-returning verbs (`vps reinstall`, `vps migrate`,
+  `vps proxmox snapshots rollback`, `vps proxmox backups
+  create/restore`) accept `--wait` to block on the Proxmox queue,
+  with `--timeout` (default 600 s for fast ops, 1800 s for the
+  slower restores).
+- Cost-incurring verbs (`domain register/transfer/id-protection`,
+  `order create/upgrade`, `account topup`) call out the
+  balance impact in the confirmation prompt; an
+  `InsufficientCredit` 402 surfaces with a hint pointing at
+  `impreza account topup`.
+- Verbs that mutate a resource emit a green success line on
+  stdout; queued / reboot-required state changes emit a cyan
+  info line. Errors are red on stderr.
+
+**Service termination policy:** `service cancel` / `vps cancel`
+submit an `AddCancelRequest` — staff approves the actual
+termination. There is no direct customer path to terminate a
+service or remove a service suspension (suspension is
+billing-state and is removed automatically when the overdue
+invoice is paid, or manually by staff after an abuse hold is
+resolved).
+
+## Output formats
+
+Every command supports `--output table|json|yaml` (short form `-o`).
+
+| Format | Default | Best for |
+|---|---|---|
+| `table` | yes | human reading at the terminal |
+| `json` | | piping into `jq`, automation, scripting |
+| `yaml` | | human-editable config snapshots, CI/CD pipelines |
+
+YAML output requires the optional `pyyaml` dependency:
+
+```bash
+pip install impreza-cli[yaml]
+```
+
+The CLI raises a clear `RuntimeError` pointing at the install hint
+if you select `--output yaml` without it.
+
+The flag works at both the global level and per-command:
+
+```bash
+# Global default for the invocation
+impreza --output json account info
+
+# Per-command override (wins over global)
+impreza --output yaml account info --output table
+```
+
+## Tab completion
+
+Typer ships completion for `bash`, `zsh`, `fish`, and PowerShell
+out of the box:
+
+```bash
+# Install for the current shell (auto-detected)
+impreza --install-completion
+
+# Or explicitly
+impreza --install-completion bash    # / zsh / fish / powershell
+
+# Inspect the script before installing
+impreza --show-completion bash
+```
+
+After installing, restart the shell (or `source ~/.bashrc` /
+equivalent) and `impreza <TAB>` should suggest resource groups,
+`impreza account <TAB>` should suggest verbs, and so on.
+
+## Tor
+
+Inherited from the SDK. Three knobs:
+
+```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
+
+# 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)
+```
+
+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.
+
+## Error handling
+
+The CLI maps SDK exceptions to friendly stderr messages and a
+non-zero exit code, matching the format `ImprezaError.__str__`
+produces:
+
+```
+Error: Invalid API credentials. (code=UNAUTHORIZED) [request_id=req_abc]
+```
+
+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.
+
+## Development
+
+```bash
+git clone https://github.com/imprezahost/impreza-devkit.git
+cd impreza-devkit/cli-python
+
+python -m venv .venv
+# Linux/macOS:        source .venv/bin/activate
+# Windows PowerShell: .venv\Scripts\Activate.ps1
+
+# Install editable + test/dev/yaml extras + the SDK as a path dep
+pip install -e ../sdk-python -e ".[test,dev,yaml]"
+
+pytest                              # unit + Typer-runner E2E
+ruff check
+mypy --strict impreza_cli
+```
+
+To run the live integration smokes (skipped silently without creds):
+
+```bash
+export IMPREZA_API_KEY="imp_..."
+export IMPREZA_API_SECRET="..."
+# Optional, for `impreza domain show / dns list`:
+export IMPREZA_TEST_DOMAIN="<a domain on your account>"
+
+pytest -v -s tests/
+```
+
+The smokes exercise the same surface as the unit tests against the
+real API, so they catch contract drift between the CLI and the
+server.
+
+## License
+
+MIT. See [`../LICENSE`](../LICENSE) at the repository root.