briar-cli 1.1.1__py3-none-any.whl

briar/commands/auth.py

@@ -0,0 +1,281 @@
+"""`briar auth` — interactive credential management.
+
+Surface mirrors ``gh auth login`` / ``vault login`` / ``op signin``:
+the thing you're logging into is the **positional target**, not a
+named flag. One unified verb for both directions:
+
+  briar auth login infisical                    # bootstrap a password manager
+  briar auth login github-pat --company acme  # acquire vendor credentials
+  briar auth login aws-sso --company acme --store infisical
+
+The acquirer's ``destination_policy`` decides whether ``--store``
+applies (vendor flows) or is forced to envfile (bootstrap flows that
+populate the credentials needed to talk to a store).
+
+Five subcommands:
+  login    run an acquirer's interactive flow + persist
+  logout   delete credentials a target's login would have written
+  refresh  renew without re-prompting where the acquirer supports it
+  list     enumerate credentials currently held in a store
+  status   show one target × company bundle's coverage (set / missing)
+
+Dispatch via the ``_ACTIONS`` map (one entry per subcommand) — same
+table-driven dispatch as ``commands/secrets.py``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from datetime import datetime, timezone
+from typing import ClassVar, Dict, List
+
+from briar.auth import AcquirerRegistry, CredentialExpired, Credentials, TerminalPromptIO
+from briar.auth._acquirer import DestinationPolicy
+from briar.commands.base import Command
+from briar.credentials import CredentialStoreRegistry, make_credential_store
+from briar.errors import CliError
+
+
+log = logging.getLogger(__name__)
+
+
+class CommandAuth(Command):
+    name = "auth"
+    help = "Acquire + persist credentials interactively (login / logout / list / status / refresh)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        sub = parser.add_subparsers(dest="auth_action", required=True)
+
+        targets = list(AcquirerRegistry.kinds())
+        store_kinds = list(CredentialStoreRegistry.kinds())
+        default_store = _resolve_default_store(store_kinds)
+
+        login = sub.add_parser(
+            "login",
+            help=(
+                "Log into a target. Positional `target` is the thing you're authenticating to: "
+                "a password manager (infisical) bootstraps a connection; "
+                "a vendor (github-pat / aws-sso / jira-session) acquires credentials and stores them."
+            ),
+        )
+        login.add_argument("target", choices=targets,
+                           help="What to log into. See `briar auth login -h` for the registry.")
+        login.add_argument("--company", default="", help="Per-company namespace (required for vendor targets).")
+        login.add_argument(
+            "--store", default=default_store, choices=store_kinds,
+            help=(
+                "Where to persist acquired credentials. Defaults to $BRIAR_DEFAULT_STORE then envfile. "
+                "IGNORED for bootstrap targets (e.g. infisical) — those always persist locally."
+            ),
+        )
+
+        logout = sub.add_parser("logout", help="Delete the credentials a target's login would have written.")
+        logout.add_argument("target", choices=targets)
+        logout.add_argument("--company", default="")
+        logout.add_argument("--store", default=default_store, choices=store_kinds)
+        logout.add_argument("--yes", action="store_true", help="Skip confirmation prompt.")
+
+        refresh = sub.add_parser(
+            "refresh",
+            help=(
+                "Renew an OAuth / SSO bundle without re-prompting. Paste-based targets (PAT, app-password, "
+                "Jira API token, Jira session cookie, Infisical machine identity) cannot refresh — re-run login."
+            ),
+        )
+        refresh.add_argument("target", choices=targets)
+        refresh.add_argument("--company", default="")
+        refresh.add_argument("--store", default=default_store, choices=store_kinds)
+
+        listing = sub.add_parser("list", help="Show which credential env-vars are populated (names only, no values).")
+        listing.add_argument("--store", default=default_store, choices=store_kinds)
+        listing.add_argument("--company", default="", help="Filter to one company (matches the company token in env-var names).")
+
+        status = sub.add_parser("status", help="Show one target × company bundle's coverage (names + set/missing).")
+        status.add_argument("target", choices=targets)
+        status.add_argument("--company", default="")
+        status.add_argument("--store", default=default_store, choices=store_kinds)
+
+    _ACTIONS: ClassVar[Dict[str, str]] = {
+        "login": "_login",
+        "logout": "_logout",
+        "refresh": "_refresh",
+        "list": "_list",
+        "status": "_status",
+    }
+
+    def run(self, args: argparse.Namespace) -> int:
+        handler_name = self._ACTIONS.get(args.auth_action)
+        if handler_name is None:
+            known = ", ".join(sorted(self._ACTIONS.keys()))
+            print(f"unknown auth action: {args.auth_action} (known: {known})")
+            return 1
+        try:
+            return getattr(self, handler_name)(args)
+        except CliError as exc:
+            print(f"error: {exc}")
+            return 1
+        except CredentialExpired as exc:
+            print(f"credential expired: {exc}")
+            return 2
+
+    # ────────────────────────────── login ──────────────────────────────
+
+    @staticmethod
+    def _login(args: argparse.Namespace) -> int:
+        acquirer = AcquirerRegistry.make(args.target)
+        effective_store = _effective_store_kind(acquirer, requested=args.store)
+        store = make_credential_store(effective_store)
+        prompt = TerminalPromptIO()
+        log.info("auth-login: target=%s company=%s store=%s policy=%s",
+                 args.target, args.company or "(none)", effective_store,
+                 type(acquirer).destination_policy.value)
+        creds = acquirer.acquire(company=args.company, prompt=prompt)
+        return _persist_and_report(creds, store=store, store_kind=effective_store)
+
+    # ────────────────────────────── logout ─────────────────────────────
+
+    @staticmethod
+    def _logout(args: argparse.Namespace) -> int:
+        acquirer = AcquirerRegistry.make(args.target)
+        acquirer_cls = type(acquirer)
+        names = acquirer_cls.writes(company=args.company)
+        effective_store = _effective_store_kind(acquirer, requested=args.store)
+        if not names:
+            print(f"auth-logout: nothing to delete for target={args.target} company={args.company or '(none)'}")
+            return 0
+        if not args.yes:
+            from briar.commands.base import confirm
+
+            print(f"auth-logout: will delete {len(names)} env vars from store={effective_store}:")
+            for n in names:
+                print(f"  - {n}")
+            if not confirm("proceed? "):
+                print("aborted")
+                return 1
+        store = make_credential_store(effective_store)
+        removed = 0
+        for n in names:
+            if store.delete(n):
+                removed += 1
+        print(f"auth-logout: removed {removed}/{len(names)} entries from store={effective_store}")
+        return 0
+
+    # ────────────────────────────── refresh ────────────────────────────
+
+    @staticmethod
+    def _refresh(args: argparse.Namespace) -> int:
+        acquirer = AcquirerRegistry.make(args.target)
+        effective_store = _effective_store_kind(acquirer, requested=args.store)
+        store = make_credential_store(effective_store)
+
+        # Reconstruct an "existing" bundle from the store so the
+        # acquirer's refresh() can use it (OAuth refresh tokens,
+        # expiry timestamps, etc.).
+        acquirer_cls = type(acquirer)
+        names = acquirer_cls.writes(company=args.company)
+        existing = Credentials(
+            provider_kind=args.target,
+            entries={n: store.read(n) for n in names if store.read(n)},
+        )
+        new = acquirer.refresh(company=args.company, existing=existing)
+        return _persist_and_report(new, store=store, store_kind=effective_store)
+
+    # ────────────────────────────── list ───────────────────────────────
+
+    @staticmethod
+    def _list(args: argparse.Namespace) -> int:
+        store = make_credential_store(args.store)
+        names = store.list()
+        if args.company:
+            tok = args.company.upper().replace("-", "_")
+            names = [n for n in names if f"_{tok}_" in f"_{n}_"]
+        if not names:
+            print(f"(no credentials in store={args.store}{' for company=' + args.company if args.company else ''})")
+            return 0
+        print(f"store={args.store}  {len(names)} entry(ies):")
+        for n in names:
+            print(f"  {n}")
+        return 0
+
+    # ────────────────────────────── status ─────────────────────────────
+
+    @staticmethod
+    def _status(args: argparse.Namespace) -> int:
+        acquirer = AcquirerRegistry.make(args.target)
+        acquirer_cls = type(acquirer)
+        names = acquirer_cls.writes(company=args.company)
+        effective_store = _effective_store_kind(acquirer, requested=args.store)
+        if not names:
+            print(f"auth-status: target={args.target} writes nothing for company={args.company or '(none)'}")
+            return 0
+        store = make_credential_store(effective_store)
+        print(f"auth-status: target={args.target} company={args.company or '(none)'} store={effective_store}")
+        any_missing = False
+        for n in names:
+            val = store.read(n)
+            mark = "ok  " if val else "MISS"
+            print(f"  {mark}  {n}")
+            if not val:
+                any_missing = True
+        return 1 if any_missing else 0
+
+
+def _resolve_default_store(known_kinds: List[str]) -> str:
+    """Default destination for ``--store``. Priority:
+       1. ``$BRIAR_DEFAULT_STORE`` if it names a registered store
+       2. ``envfile`` (always present, requires no setup)"""
+    import os
+
+    env = (os.environ.get("BRIAR_DEFAULT_STORE", "") or "").strip()
+    if env and env in known_kinds:
+        return env
+    return "envfile"
+
+
+def _effective_store_kind(acquirer, *, requested: str) -> str:
+    """Honour the acquirer's destination policy. Bootstrap acquirers
+    (Infisical machine identity, future Vault VAULT_ADDR/TOKEN) MUST
+    persist locally — they can't store the credentials that describe
+    how to reach their own store. Warn the operator if their
+    ``--store`` choice gets overridden."""
+    policy = type(acquirer).destination_policy
+    if policy is DestinationPolicy.BOOTSTRAP_LOCAL and requested != "envfile":
+        log.warning(
+            "auth: target=%s is a bootstrap flow — forcing store=envfile "
+            "(requested store=%s ignored; you can't store the credentials "
+            "for a store inside that same store)",
+            type(acquirer).kind,
+            requested,
+        )
+        return "envfile"
+    return requested
+
+
+def _persist_and_report(creds: Credentials, *, store, store_kind: str) -> int:
+    """Common login/refresh tail: write every entry through the store
+    and print a summary. Values are NEVER printed — only the key
+    names and counts."""
+    log.info("auth-persist: store=%s count=%d provider=%s", store_kind, len(creds.entries), creds.provider_kind)
+    failures: List[str] = []
+    for name, value in creds.entries.items():
+        try:
+            store.write(name, value)
+        except Exception as exc:  # noqa: BLE001
+            log.exception("auth-persist: write failed name=%s store=%s", name, store_kind)
+            failures.append(f"{name}: {exc}")
+
+    print(f"auth: persisted {len(creds.entries) - len(failures)}/{len(creds.entries)} entries to store={store_kind}")
+    for n in creds.names:
+        if n in {f.split(':', 1)[0] for f in failures}:
+            print(f"  FAIL  {n}")
+        else:
+            print(f"  ok    {n}")
+    if creds.expires_at:
+        delta = creds.expires_at - datetime.now(tz=timezone.utc)
+        days = delta.total_seconds() / 86400
+        print(f"expires: {creds.expires_at.isoformat()} ({days:+.1f} days from now)")
+    if failures:
+        for f in failures:
+            print(f"  reason: {f}")
+        return 3
+    return 0

briar/commands/base.py

@@ -0,0 +1,46 @@
+"""Command base class + shared helpers.
+
+Lives in its own module so sibling concretes can import it without
+triggering the package `__init__` (which itself imports the concretes
+to assemble the registry — a classic circular-import trap)."""
+
+from __future__ import annotations
+
+import argparse
+from abc import ABC, abstractmethod
+
+
+class Command(ABC):
+    """Implementation contract for every CLI verb.
+
+    Subclasses set `name` + `help` and implement `add_arguments` /
+    `run`. Subclasses must NOT touch the global registry or argparse
+    state directly — the entry point in `briar.cli` is the only
+    place that does that."""
+
+    name: str = ""
+    help: str = ""
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Default: no extra arguments."""
+
+    @abstractmethod
+    def run(self, args: argparse.Namespace) -> int:
+        """Execute the command. Returns the process exit code."""
+
+    @staticmethod
+    def confirm(prompt: str) -> bool:
+        """Yes/no prompt; treats EOF (piped input) as a no.
+
+        Subclasses use this to gate destructive operations behind a
+        --yes / interactive-prompt fork (`args.yes or self.confirm(...)`)."""
+        try:
+            return input(prompt).strip().lower() in {"y", "yes"}
+        except EOFError:
+            return False
+
+
+# Module-level back-compat shim — `confirm()` was the historic name
+# imported by sibling concretes. Kept so call-sites remain a one-symbol
+# import without per-class qualification.
+confirm = Command.confirm

briar/commands/context.py

@@ -0,0 +1,143 @@
+"""`briar context` — CRUD over local markdown knowledge blobs.
+
+A blob holds arbitrary markdown — extracted knowledge, accumulated
+memory, codified lessons, ad-hoc notes — keyed by `category:name`.
+Backed by the local file `KnowledgeStore`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Callable, Dict
+
+from briar.commands.base import Command, confirm
+from briar.errors import CliError
+from briar.formatting import render
+from briar.storage import KNOWLEDGE_STORE_NAMES, KnowledgeRef, make_store
+
+
+Handler = Callable[[argparse.Namespace], int]
+
+
+class ContextCommand(Command):
+    name = "context"
+    help = "Store and read named local markdown blobs."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--store",
+            default="file",
+            choices=list(KNOWLEDGE_STORE_NAMES),
+            help="Knowledge store backend (default: file)",
+        )
+        parser.add_argument(
+            "--root",
+            default="./knowledge",
+            help="Local file root",
+        )
+
+        sub = parser.add_subparsers(dest="op", required=True)
+
+        put = sub.add_parser("put", help="create or update a blob")
+        put.add_argument("blob_name", help="e.g. knowledge:acme")
+        put.add_argument("--content", help="inline content (or '-' for stdin)")
+        put.add_argument("--from-file", help="read content from this path")
+        put.add_argument(
+            "--category",
+            default="",
+            help="explicit category (default: derived from blob_name prefix)",
+        )
+
+        gp = sub.add_parser("get", help="print the markdown body to stdout")
+        gp.add_argument("blob_name")
+
+        lst = sub.add_parser("list", help="list stored blobs")
+        lst.add_argument(
+            "--prefix",
+            default="",
+            help="filter to names starting with this prefix",
+        )
+
+        de = sub.add_parser("delete", help="remove a blob")
+        de.add_argument("blob_name")
+        de.add_argument("--yes", action="store_true")
+
+        sub.add_parser("categories", help="print distinct category prefixes")
+
+    def run(self, args: argparse.Namespace) -> int:
+        handlers: Dict[str, Handler] = {
+            "put": self._put,
+            "get": self._get,
+            "list": self._list,
+            "delete": self._delete,
+            "categories": self._categories,
+        }
+        return handlers[args.op](args)
+
+    @staticmethod
+    def _read_content(args: argparse.Namespace) -> str:
+        ns = vars(args)
+        inline = ns.get("content")
+        if inline is not None:
+            return inline if inline != "-" else sys.stdin.read()
+        file_path = ns.get("from_file")
+        if file_path:
+            return Path(file_path).read_text()
+        if sys.stdin.isatty():
+            raise CliError("no content provided — pass --content '<text>', " "--from-file <path>, or pipe in via stdin")
+        return sys.stdin.read()
+
+    @staticmethod
+    def _ref_to_dict(ref: KnowledgeRef) -> dict:
+        return {
+            "name": ref.name,
+            "category": ref.category,
+            "byte_count": ref.byte_count,
+            "updated_at": ref.updated_at,
+            **ref.extra,
+        }
+
+    def _store(self, args: argparse.Namespace):
+        return make_store(args.store, file_root=Path(args.root))
+
+    def _put(self, args: argparse.Namespace) -> int:
+        ref = self._store(args).put(
+            args.blob_name,
+            self._read_content(args),
+            category=args.category,
+        )
+        render(self._ref_to_dict(ref), args.format)
+        return 0
+
+    def _get(self, args: argparse.Namespace) -> int:
+        body = self._store(args).get(args.blob_name)
+        if not body:
+            raise CliError(f"blob not found: {args.blob_name}")
+        sys.stdout.write(body)
+        if not body.endswith("\n"):
+            sys.stdout.write("\n")
+        return 0
+
+    def _list(self, args: argparse.Namespace) -> int:
+        refs = self._store(args).list(prefix=args.prefix)
+        items = [self._ref_to_dict(r) for r in refs]
+        render(items, args.format, ["name", "category", "byte_count", "updated_at"])
+        return 0
+
+    def _delete(self, args: argparse.Namespace) -> int:
+        ok = bool(args.yes) or confirm(f"Delete blob {args.blob_name} from store {args.store}? [y/N] ")
+        if not ok:
+            print("aborted")
+            return 1
+        removed = self._store(args).delete(args.blob_name)
+        print(f"{'deleted' if removed else 'not found'} {args.blob_name}")
+        return 0
+
+    def _categories(self, args: argparse.Namespace) -> int:
+        seen: Dict[str, int] = {}
+        for ref in self._store(args).list():
+            seen[ref.category] = seen.get(ref.category, 0) + 1
+        items = [{"category": cat or "(none)", "blob_count": n} for cat, n in sorted(seen.items())]
+        render(items, args.format, ["category", "blob_count"])
+        return 0

briar/commands/dashboard.py

@@ -0,0 +1,61 @@
+"""`briar dashboard` — boot the read-only HTML dashboard."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from briar.commands.base import Command
+from briar.dashboard.collectors import CollectorRegistry, DashboardPaths, DashboardSelf
+from briar.dashboard.server import DashboardServer
+from briar.env_vars import CredEnv
+from briar.storage import KNOWLEDGE_STORE_NAMES, make_store
+
+
+class CommandDashboard(Command):
+    name = "dashboard"
+    help = "Serve a read-only HTML dashboard summarising the droplet state."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("--host", default="0.0.0.0", help="bind address (default: 0.0.0.0 — public)")
+        parser.add_argument("--port", type=int, default=8080, help="bind port (default: 8080)")
+        parser.add_argument("--examples", default="./examples", help="directory of runbook YAMLs")
+        parser.add_argument(
+            "--knowledge-store",
+            default="",
+            choices=[""] + list(KNOWLEDGE_STORE_NAMES),
+            help="which KnowledgeStore to read from (default: postgres if BRIAR_DATABASE_URL is set, else file)",
+        )
+        parser.add_argument("--knowledge", default="./knowledge", help="knowledge file root (only used when --knowledge-store=file)")
+        parser.add_argument("--log-file", default="/var/log/briar/scheduler.log", help="path to the scheduler log")
+        parser.add_argument("--disk-path", default="/", help="filesystem path used for disk-usage stats")
+        parser.add_argument("--repo-path", default=".", help="path of the deployed git checkout")
+        parser.add_argument("--secrets-file", default="/etc/briar/secrets.env", help="secrets.env path (names+lengths only)")
+        parser.add_argument("--du-path", action="append", default=[], help="directory whose size to report (repeatable)")
+        parser.add_argument("--once", action="store_true", help="render once to stdout and exit")
+
+    def run(self, args: argparse.Namespace) -> int:
+        store_name = args.knowledge_store or ("postgres" if CredEnv.BRIAR_DATABASE_URL.read() else "file")
+        knowledge_store = make_store(store_name, file_root=Path(args.knowledge))
+
+        server = DashboardServer(host=args.host, port=args.port)
+        paths = DashboardPaths(
+            examples_dir=Path(args.examples),
+            knowledge_store=knowledge_store,
+            log_path=Path(args.log_file),
+            disk_path=Path(args.disk_path),
+            repo_path=Path(args.repo_path),
+            secrets_path=Path(args.secrets_file),
+            du_paths=[Path(p) for p in (args.du_path or [args.repo_path, args.knowledge, "/var/log/briar"])],
+        )
+        dash = DashboardSelf(
+            started_at=server.started_at,
+            request_count_fn=server.request_count,
+            last_render_ms_fn=server.last_render_ms,
+        )
+        server.set_collectors(CollectorRegistry.from_paths(paths, dash))
+        if args.once:
+            print(server.render_index())
+            return 0
+        server.serve()
+        return 0

briar/commands/extract.py

@@ -0,0 +1,79 @@
+"""`briar extract` — run one or more knowledge extractors, write the
+result to a local markdown file."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import List
+
+from briar.commands.base import Command
+from briar.errors import CliError
+from briar.extract import EXTRACTORS
+from briar.extract.base import ExtractedSection
+from briar.extract.composer import render_json, render_markdown
+from briar.storage import KNOWLEDGE_STORE_NAMES, make_store
+
+
+class CommandExtract(Command):
+    name = "extract"
+    help = "Mine the live state of GitHub / AWS / etc. into a markdown " "knowledge blob written to local disk."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--company",
+            required=True,
+            help="Company name (drives the markdown title + blob name)",
+        )
+        parser.add_argument(
+            "--include",
+            action="append",
+            default=[],
+            choices=sorted(EXTRACTORS.keys()),
+            help="Which extractor(s) to run (repeatable; default: all available)",
+        )
+        parser.add_argument(
+            "--storage",
+            default="file",
+            choices=list(KNOWLEDGE_STORE_NAMES),
+            help="Where to write the result (default: file)",
+        )
+        parser.add_argument("--blob-name", default="", help="Storage blob name (default: knowledge:<company>)")
+        parser.add_argument("--root", default="./knowledge", help="Local file root (only used when --storage=file)")
+        parser.add_argument("--out-json", default="", help="Parallel JSON output path (empty = skip)")
+        for ext in EXTRACTORS.values():
+            ext.add_arguments(parser)
+
+    def run(self, args: argparse.Namespace) -> int:
+        selected = args.include or list(EXTRACTORS.keys())
+
+        sections: List[ExtractedSection] = []
+        for name in selected:
+            ext = EXTRACTORS[name]
+            if not ext.is_available(args):
+                print(f"  skipped {name}  (not available in this env)")
+                continue
+            print(f"  running {name} ...")
+            section = ext.extract(args)
+            if section.is_empty:
+                print(f"  {name}: no data")
+                continue
+            sections.append(section)
+
+        if not sections:
+            raise CliError("nothing extracted — every enabled extractor returned empty")
+
+        md = render_markdown(company=args.company, sections=sections)
+        blob_name = args.blob_name or f"knowledge:{args.company}"
+
+        store = make_store(args.storage, file_root=Path(args.root))
+        ref = store.put(blob_name, md, category="knowledge")
+        print(f"\nwrote blob '{ref.name}' " f"({ref.byte_count} bytes, {len(sections)} sections) " f"via store={args.storage}")
+
+        if args.out_json:
+            json_path = Path(args.out_json)
+            json_path.parent.mkdir(parents=True, exist_ok=True)
+            json_path.write_text(render_json(company=args.company, sections=sections))
+            print(f"wrote {json_path}")
+
+        return 0

briar/commands/iac.py

@@ -0,0 +1,44 @@
+"""IaC scaffold command — emits JSON the user pastes into the web UI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from briar.commands.base import Command
+from briar.errors import CliError
+from briar.iac import TEMPLATES
+
+
+class CommandScaffold(Command):
+    name = "scaffold"
+    help = "Generate a starter config file for a built-in template."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        sub = parser.add_subparsers(
+            dest="template",
+            required=True,
+            metavar="TEMPLATE",
+        )
+        for name, tmpl in TEMPLATES.items():
+            tp = sub.add_parser(name, help=tmpl.description)
+            tp.add_argument(
+                "--out",
+                "-o",
+                default="-",
+                help="output path (default: stdout)",
+            )
+            tmpl.add_arguments(tp)
+
+    def run(self, args: argparse.Namespace) -> int:
+        tmpl = TEMPLATES.get(args.template)
+        if tmpl is None:
+            raise CliError(f"unknown template: {args.template}")
+        text = json.dumps(tmpl.build(args), indent=2)
+        if args.out == "-":
+            print(text)
+            return 0
+        Path(args.out).write_text(text)
+        print(f"wrote {args.out}")
+        return 0