panorama-super-cli 0.2.4__tar.gz → 0.2.6__tar.gz

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/CHANGELOG.md

@@ -7,6 +7,45 @@ project will follow [Semantic Versioning](https://semver.org/). While on
 
 ## [Unreleased]
 
+## v0.2.6 — 2026-06-04
+
+### Added
+
+- **`psc version` and `psc version check`** (#33). `psc version` prints the
+  installed version (the format-aware equivalent of the `--version` flag, which
+  is kept); `psc version check` queries PyPI and reports whether a newer release
+  is available, exiting 0 either way. An unreachable PyPI surfaces as a typed
+  `transport` error rather than a stack trace.
+
+### Fixed
+
+- **`psc profile list` now prints the config file's location** (#48). The path
+  is platform-dependent (notably different on Windows), so it was hard to find
+  where psc reads/writes profiles. The path is written to stderr — keeping the
+  machine-readable rows on stdout clean — and flagged `(not created yet)` when
+  the file is absent.
+- **`--out` now writes the artifact even in a dry-run, and on a live profile**
+  (#47). Previously `dedup merge`/`name` silently ignored `--out` unless
+  `--apply` was passed, and ignored it entirely on a live profile — so
+  `dedup merge … -of set --out out.txt` against a live Panorama printed the plan
+  but wrote no file. `--out` is now treated as an artifact request (a `set`
+  script or rewritten `xml`): writing a user-named file never touches the source
+  export or the live candidate, so it is honoured regardless of `--apply` or
+  source. `--apply` still governs the live candidate push; combining
+  `--apply --out` on a live profile both pushes and saves the artifact. Offline
+  `--apply` still requires `--out`. The blocker gate holds on every path.
+
+## v0.2.5 — 2026-06-04
+
+### Fixed
+
+- **`psc find ip` table output now separates each target's matches with a
+  horizontal rule** (#43). Resolving several targets at once (notably with
+  `--file`) previously printed every match as one undifferentiated block, so it
+  was hard to see where one target's matches ended and the next began. The
+  table now draws a rule between per-target blocks. Machine output formats
+  (json/jsonl/yaml/csv/set) are unchanged.
+
 ## v0.2.4 — 2026-06-04
 
 ### Changed

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panorama-super-cli
-Version: 0.2.4
+Version: 0.2.6
 Summary: Agent-friendly CLI for Palo Alto Panorama object management: find, dedup/merge, rename, and audit address/service objects safely.
 Project-URL: Homepage, https://github.com/thomaschristory/panorama-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/panorama-super-cli/
@@ -20,6 +20,7 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Requires-Dist: defusedxml>=0.7
+Requires-Dist: packaging>=23.0
 Requires-Dist: pan-os-python>=1.12
 Requires-Dist: platformdirs>=4.2
 Requires-Dist: pydantic>=2.7

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/docs/getting-started/install.md

@@ -24,10 +24,13 @@ command.
 Verify:
 
 ```console
-$ psc --version
+$ psc version
 psc 0.1.0
 ```
 
+(`psc --version` works too. `psc version check` reports whether a newer release
+is available on PyPI.)
+
 `psc` requires Python 3.12+. It has no external service dependencies for the
 offline path; the live path talks to Panorama via
 [`pan-os-python`](https://github.com/PaloAltoNetworks/pan-os-python), which is

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/docs/guides/live-vs-offline.md

@@ -58,3 +58,8 @@ gate and repoint-before-delete ordering apply on the wire. See
 | Reads | ✅ | ✅ |
 | Writes | new file via `--out` | candidate config (you commit) |
 | Best for | audits, CI, safe edits | lookups and edits against prod |
+
+`--out` works on either source — it saves a reviewable `set`/`xml` artifact
+without touching the export or the candidate, even in a dry-run. On live it's
+independent of `--apply`: use `--apply` to push the candidate, add `--out` if
+you also want the script on disk.

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/docs/guides/naming.md

@@ -40,7 +40,10 @@ psc -c panorama.xml name rename --object h-web1 --to H-10.0.0.10
 psc -c panorama.xml name apply  --object h-web1   # rename to the scheme name
 ```
 
-Both are dry-run by default; add `--apply --out fixed.xml` (offline) to execute.
+Both are dry-run by default. Offline, `--out fixed.xml` writes the rewritten
+config (add `--apply` to execute; the file is written either way). Add
+`-of set` for a PAN-OS `set` script instead. Live, `--apply` pushes the
+candidate; add `--out` to also save the artifact.
 
 ## The shadow guard
 

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/docs/guides/output-formats.md

@@ -56,18 +56,19 @@ These are two different knobs and it's worth keeping them straight:
 
 - **`-o set`** controls what a command prints to **stdout** — use it to read or
   pipe the plan during a dry-run.
-- **`-of` / `--output-format`** (offline mutating commands only) controls the
-  format of the **`--apply --out` file artifact**: `xml` (default) rewrites the
-  whole config to load with `load config`, while `set` writes the same PAN-OS
-  `set` script shown above to that file — easier to read and to paste into a
-  config session or `load config partial`.
+- **`-of` / `--output-format`** (mutating commands only) controls the format of
+  the **`--out` file artifact**: `xml` (default) rewrites the whole config to
+  load with `load config`, while `set` writes the same PAN-OS `set` script shown
+  above to that file — easier to read and to paste into a config session or
+  `load config partial`.
 
 ```console
-psc -c panorama.xml dedup merge --keep h-web1 --remove web-primary --apply --out plan.set -of set
+psc -c panorama.xml dedup merge --keep h-web1 --remove web-primary --out plan.set -of set
 ```
 
-`-of` only shapes the file and is ignored without `--apply`; on a live profile
-there is no file artifact, so it has no effect there.
+`-of` only shapes the `--out` file. `--out` writes that file whenever it's
+given — including in a dry-run, and on a live profile — because writing a file
+never touches the source export or the device candidate.
 
 ## Errors
 

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/docs/guides/safety.md

@@ -37,9 +37,11 @@ don't block.
 
 ## Offline apply never overwrites your export
 
-Offline, `--apply` requires `--out PATH` and writes the rewritten config there —
-it will refuse to write back over the source file. Your export stays pristine and
-the change is reviewable as a diff.
+Offline, `--out PATH` writes the rewritten config there — it will refuse to
+write back over the source file. Your export stays pristine and the change is
+reviewable as a diff. `--out` is an artifact request, so it is honoured even in
+a dry-run (writing a file is not a mutation); `--apply` alone still requires
+`--out`.
 
 ```console
 psc -c panorama.xml dedup merge --keep a --remove b --apply --out fixed.xml
@@ -74,8 +76,9 @@ rejected up front (`input`, exit `2`) rather than sent malformed — rename it o
 apply that plan offline. If a write fails mid-plan, `psc` reports how far it got
 and leaves the uncommitted candidate for you to inspect or revert.
 
-Prefer to stage the change as a file instead? Plan with `-o set` (paste / `load
-config partial`) or plan offline with `--apply --out`.
+Prefer to stage the change as a file instead? Add `--out plan.set -of set` (it
+writes the artifact without pushing, even on a live profile), or print the
+script to stdout with `-o set` (paste / `load config partial`).
 
 ## Debugging
 

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/docs/reference/cli.md

@@ -18,12 +18,18 @@ These are **context** options — pass them *before* the subcommand:
 | `--version` | Print version and exit. |
 
 Write-execution options (`--apply`, `--out`, `-of/--output-format`) belong to
-the individual mutating commands and are passed *after* the command. `--apply`
-is the only path to a write; offline it requires `--out PATH` (a new file) and
-`-of xml|set` chooses what that file holds (default `xml`), while live it pushes
-to
-Panorama's candidate config and never commits. See
-[Writes and safety](../guides/safety.md).
+the individual mutating commands and are passed *after* the command.
+
+- `--out PATH` writes a reviewable artifact file; `-of xml|set` chooses what it
+  holds (default `xml`). It's an artifact request, not a mutation, so it's
+  honoured even in a dry-run and on a live profile — writing a file never
+  touches the source export or the device candidate.
+- `--apply` executes the change against the managed config: **live** pushes the
+  plan to Panorama's candidate config and never commits; **offline** requires
+  `--out PATH` (the rewritten file *is* the execution, and never overwrites the
+  source export).
+
+See [Writes and safety](../guides/safety.md).
 
 ## Commands
 
@@ -110,5 +116,18 @@ psc profile remove <name>
 ```
 
 Manage live connection profiles. `init`/`login` are the friendlier front door;
-`profile add` is the scriptable, non-interactive form. See
-[Configuration](config.md).
+`profile add` is the scriptable, non-interactive form. `profile list` also
+prints the config file's location (on stderr, so machine output stays clean) —
+handy because the path is platform-dependent. See [Configuration](config.md).
+
+### version
+
+```
+psc version
+psc version check
+```
+
+`psc version` prints the installed version (the format-aware equivalent of the
+`--version` flag). `psc version check` queries PyPI and reports whether a newer
+release is available; it exits 0 either way and emits a typed `transport` error
+if PyPI is unreachable.

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/_version.py

@@ -4,4 +4,4 @@
 Keep this in sync with `[project].version` in `pyproject.toml`.
 """
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/_plan.py

@@ -2,7 +2,9 @@
 
 Centralising this is what guarantees the safety contract is identical across
 `dedup merge`, `name rename`, and any future write command: blocked plans are
-refused, dry-run is the default, and `--apply` is the only path to a write.
+refused, dry-run is the default, and `--apply` is the only path to mutating the
+managed config (the live candidate; offline, the rewritten `--out` file). A
+bare `--out` only ever writes a reviewable artifact file — never the device.
 """
 
 from __future__ import annotations
@@ -27,7 +29,7 @@ OUT_FORMAT_OPTION = typer.Option(
         "Format of the offline --out artifact. 'xml' (default) rewrites the whole "
         "config to load with `load config`; 'set' writes the equivalent PAN-OS set "
         "script (the creates/deletes/repoints) — easier to read and to paste into a "
-        "config session. Only affects --out; ignored without --apply."
+        "config session. Only affects the --out file."
     ),
 )
 
@@ -64,7 +66,10 @@ def complete(
         _print_human_plan(rt, cs)
 
     if cs.is_empty:
-        rt.stderr.print("[dim]nothing to do[/dim]")
+        # An empty plan has no artifact to write — say so explicitly when `--out`
+        # was asked for, rather than silently leaving the file absent.
+        note = " — no artifact written" if out_path is not None else ""
+        rt.stderr.print(f"[dim]nothing to do{note}[/dim]")
         return
 
     if apply:
@@ -73,6 +78,15 @@ def complete(
             f"[green]applied[/green] {result.ops} operation(s)"
             + (f" → {result.out_path}" if result.out_path else "")
         )
+    elif out_path is not None:
+        # `--out` is an artifact request, not a mutation: writing a user-named
+        # file never touches the source export or the live candidate, so honour
+        # it even in a dry-run. This is the whole fix for #47.
+        result = rt.source().write_out(cs, out_path=out_path, out_format=out_format)
+        rt.stderr.print(
+            f"[green]wrote[/green] {out_format.value} artifact → {result.out_path} "
+            "[dim](dry-run — re-run with --apply to push)[/dim]"
+        )
     else:
         rt.stderr.print("[yellow]dry-run[/yellow] — re-run with --apply to execute")
 

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/app.py

@@ -10,9 +10,17 @@ import typer
 from rich.console import Console
 
 from psc import __version__
-from psc.cli import auth_cmds, dedup_cmds, find_cmds, name_cmds, profile_cmds, refs_cmds
+from psc.cli import (
+    auth_cmds,
+    dedup_cmds,
+    find_cmds,
+    name_cmds,
+    profile_cmds,
+    refs_cmds,
+    version_cmds,
+)
 from psc.cli.runtime import Runtime, configure_logging
-from psc.config.loader import load_config
+from psc.config.loader import config_path, load_config
 from psc.output.errors import PscError
 from psc.output.format import OutputFormat
 
@@ -109,14 +117,16 @@ def root(
 ) -> None:
     global _ACTIVE  # noqa: PLW0603 — single process-wide handle for the error printer
     configure_logging(debug)
+    cfg_path = config_path()  # resolve once so the loaded and displayed paths match
     rt = Runtime(
-        config=load_config(),
+        config=load_config(cfg_path),
         config_file=config,
         profile=profile,
         debug=debug,
         device_group=device_group,
         strict=strict,
         _output=output,
+        config_path=cfg_path,
     )
     ctx.obj = rt
     _ACTIVE = rt
@@ -127,6 +137,7 @@ app.add_typer(dedup_cmds.app, name="dedup", help="Find and merge duplicate objec
 app.add_typer(refs_cmds.app, name="refs", help="Where-used, unused, and dangling references.")
 app.add_typer(name_cmds.app, name="name", help="Naming-template lint and rename.")
 app.add_typer(profile_cmds.app, name="profile", help="Manage live connection profiles.")
+app.add_typer(version_cmds.app, name="version", help="Show version; check PyPI for updates.")
 app.command(
     "init",
     help="Interactively bootstrap a live profile (fetches an API key from a username/password).",

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/dedup_cmds.py

@@ -85,7 +85,10 @@ def merge(
     ),
     apply: bool = typer.Option(False, "--apply", help="Execute the merge (default: dry-run)."),
     out: str | None = typer.Option(
-        None, "--out", help="Offline: write the rewritten config here (see --output-format)."
+        None,
+        "--out",
+        help="Write the plan artifact (set script or rewritten config) to this "
+        "file; honoured even in a dry-run (see --output-format).",
     ),
     output_format: ConfigFormat = OUT_FORMAT_OPTION,
 ) -> None:

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/find_cmds.py

@@ -78,7 +78,9 @@ def ip(
         raise PscError("no matching objects", ErrorType.NOT_FOUND)
 
     model = results if len(results) != 1 else results[0]
-    render(rt.stdout, rt.output, model=model, rows=rows, table_title="find ip")
+    # Group the table by query so multi-target output (e.g. --file) draws a rule
+    # between each target's matches instead of one undifferentiated block.
+    render(rt.stdout, rt.output, model=model, rows=rows, table_title="find ip", group_by="query")
 
 
 @app.command("object")

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/name_cmds.py

@@ -51,7 +51,10 @@ def rename(
     location: str | None = typer.Option(None, "--location"),
     apply: bool = typer.Option(False, "--apply", help="Execute the rename (default: dry-run)."),
     out: str | None = typer.Option(
-        None, "--out", help="Offline: write rewritten config here (see --output-format)."
+        None,
+        "--out",
+        help="Write the plan artifact (set script or rewritten config) to this "
+        "file; honoured even in a dry-run (see --output-format).",
     ),
     output_format: ConfigFormat = OUT_FORMAT_OPTION,
 ) -> None:
@@ -71,7 +74,10 @@ def apply_scheme(
     location: str | None = typer.Option(None, "--location"),
     apply: bool = typer.Option(False, "--apply", help="Execute the rename (default: dry-run)."),
     out: str | None = typer.Option(
-        None, "--out", help="Offline: write rewritten config here (see --output-format)."
+        None,
+        "--out",
+        help="Write the plan artifact (set script or rewritten config) to this "
+        "file; honoured even in a dry-run (see --output-format).",
     ),
     output_format: ConfigFormat = OUT_FORMAT_OPTION,
 ) -> None:

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/profile_cmds.py

@@ -17,6 +17,16 @@ app = typer.Typer(no_args_is_help=True)
 def list_profiles(ctx: typer.Context) -> None:
     """Show configured live profiles (API keys are not printed)."""
     rt: Runtime = ctx.obj
+    # Where the config lives is platform-dependent (it differs on Windows), so
+    # surface it to help users find/edit the file (#48). It goes to stderr so it
+    # never pollutes the machine-readable rows on stdout, and prints even when
+    # no profiles are configured yet — the empty case is exactly when "where do
+    # I put them?" matters most.
+    path = rt.config_path
+    suffix = "" if path.exists() else " (not created yet)"
+    # soft_wrap + markup=False: never wrap a long path onto two lines, and never
+    # let a path with `[...]` be parsed as rich markup.
+    rt.stderr.print(f"config file: {path}{suffix}", soft_wrap=True, markup=False, highlight=False)
     rows = [
         {
             "name": p.name,

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/cli/runtime.py

@@ -10,10 +10,12 @@ from __future__ import annotations
 
 import sys
 from dataclasses import dataclass, field
+from pathlib import Path
 
 import structlog
 from rich.console import Console
 
+from psc.config.loader import config_path
 from psc.config.models import Config
 from psc.core.models import Location, Snapshot
 from psc.core.source import LiveSource, OfflineSource
@@ -44,6 +46,10 @@ class Runtime:
     device_group: str | None
     strict: bool
     _output: OutputFormat | None
+    # The resolved `config.yaml` path actually loaded from — so commands can show
+    # users where their profiles live (#48). Distinct from `config_file`, which
+    # is the offline `--config` XML export.
+    config_path: Path = field(default_factory=config_path)
     stdout: Console = field(default_factory=Console)
     stderr: Console = field(default_factory=lambda: Console(stderr=True))
     _source: OfflineSource | LiveSource | None = None

panorama_super_cli-0.2.6/psc/cli/version_cmds.py

@@ -0,0 +1,42 @@
+"""`psc version` — show the installed version and check PyPI for updates (#33).
+
+`psc version` (bare) replaces `psc --version` with a format-aware report; the
+`--version` flag stays for backwards compatibility. `psc version check` reaches
+out to PyPI and tells you whether a newer release is available.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from psc import __version__
+from psc.cli.runtime import Runtime
+from psc.core.version_check import check_for_update
+from psc.output.format import render
+
+app = typer.Typer(no_args_is_help=False)
+
+
+@app.callback(invoke_without_command=True)
+def version(ctx: typer.Context) -> None:
+    """Show the installed psc version."""
+    if ctx.invoked_subcommand is not None:
+        return
+    rt: Runtime = ctx.obj
+    row = {"version": __version__}
+    render(rt.stdout, rt.output, model=row, rows=[row], table_title="version")
+
+
+@app.command("check")
+def check(ctx: typer.Context) -> None:
+    """Check PyPI for a newer release of panorama-super-cli."""
+    rt: Runtime = ctx.obj
+    info = check_for_update()
+    render(rt.stdout, rt.output, model=info, rows=[info.model_dump()], table_title="update check")
+    if info.update_available:
+        rt.stderr.print(
+            f"[yellow]update available[/yellow]: {info.installed} → {info.latest} "
+            "(run: pip install -U panorama-super-cli)"
+        )
+    else:
+        rt.stderr.print(f"[green]up to date[/green]: {info.installed}")

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/config/loader.py

@@ -22,8 +22,10 @@ def config_path() -> Path:
     return Path(user_config_dir(_APP)) / "config.yaml"
 
 
-def load_config() -> Config:
-    path = config_path()
+def load_config(path: Path | None = None) -> Config:
+    # Callers may pass an already-resolved path so the value they display (e.g.
+    # `psc profile list`) is provably the same file we loaded (#48).
+    path = path if path is not None else config_path()
     if not path.exists():
         return Config()
     yaml = YAML(typ="safe")

{panorama_super_cli-0.2.4 → panorama_super_cli-0.2.6}/psc/core/source.py

@@ -75,6 +75,17 @@ def _ssl_context(verify: bool) -> ssl.SSLContext:
     return ctx
 
 
+def _write_artifact(out: Path, data: str) -> None:
+    """Write an `--out` artifact, mapping filesystem errors onto the error
+    contract. A bad `--out` (missing parent dir, a directory, unwritable) is an
+    *expected* failure — surface it as `INPUT` rather than leaking a raw
+    `OSError` traceback (which would also corrupt machine output)."""
+    try:
+        out.write_text(data, encoding="utf-8")
+    except OSError as exc:
+        raise PscError(f"cannot write artifact to {out}: {exc}", ErrorType.INPUT) from exc
+
+
 class OfflineSource:
     """Read + rewrite an exported Panorama config XML on disk."""
 
@@ -98,16 +109,23 @@ class OfflineSource:
         except Exception as exc:
             raise PscError(f"failed to parse {self.path}: {exc}", ErrorType.INPUT) from exc
 
-    def apply(
+    def write_out(
         self,
         cs: ChangeSet,
         *,
         out_path: str | Path | None,
         out_format: ConfigFormat = ConfigFormat.XML,
     ) -> ApplyResult:
+        """Render `cs` to the `--out` artifact file (set script or rewritten XML).
+
+        This is the *artifact* path: it only ever writes the separate `--out`
+        file and never the source export, so it is safe in a dry-run. For the
+        offline source the artifact *is* the whole point — `apply` is just this
+        with an `applied=True` flag (there is no separate device to push to).
+        """
         if out_path is None:
             raise PscError(
-                "offline apply needs --out PATH (the rewritten config is never "
+                "offline --out needs a PATH (the rewritten config is never "
                 "written back over the source export)",
                 ErrorType.CONFIG,
             )
@@ -119,18 +137,30 @@ class OfflineSource:
         # it, so refuse before writing rather than emit a `# BLOCKED` file.
         if cs.is_blocked:
             raise PscError(
-                "refusing to apply a blocked plan",
+                "refusing to write a blocked plan",
                 ErrorType.CONFLICT,
                 details={"blockers": cs.blockers},
             )
         # Both artifacts share the same safety guards above; only the bytes differ.
         if out_format is ConfigFormat.SET:
             script = render_changeset(cs)
-            out.write_text("\n".join(script) + "\n", encoding="utf-8")
-            return ApplyResult(applied=True, ops=cs.op_count, out_path=str(out), set_script=script)
+            _write_artifact(out, "\n".join(script) + "\n")
+            return ApplyResult(applied=False, ops=cs.op_count, out_path=str(out), set_script=script)
         new_xml = apply_changeset(self._xml, cs)
-        out.write_text(new_xml, encoding="utf-8")
-        return ApplyResult(applied=True, ops=cs.op_count, out_path=str(out))
+        _write_artifact(out, new_xml)
+        return ApplyResult(applied=False, ops=cs.op_count, out_path=str(out))
+
+    def apply(
+        self,
+        cs: ChangeSet,
+        *,
+        out_path: str | Path | None,
+        out_format: ConfigFormat = ConfigFormat.XML,
+    ) -> ApplyResult:
+        # Offline has no live device: applying *is* producing the `--out`
+        # artifact. Reuse the artifact path and only flip the `applied` flag.
+        res = self.write_out(cs, out_path=out_path, out_format=out_format)
+        return res.model_copy(update={"applied": True})
 
 
 class LiveSource:
@@ -151,6 +181,7 @@ class LiveSource:
         self._api_key = api_key
         self._port = port
         self._verify = verify
+        self._raw: str | None = None
 
     @staticmethod
     def fetch_api_key(
@@ -242,10 +273,17 @@ class LiveSource:
         return pano
 
     def raw_xml(self) -> str:
+        # Memoised for the lifetime of this source: one CLI invocation reads the
+        # running config once and reuses it for the snapshot *and* any `--out`
+        # XML artifact, so the artifact is rewritten from the exact config the
+        # plan was computed against (no divergence, no second round-trip).
+        if self._raw is not None:
+            return self._raw
         try:
             pano = self._device()
             pano.xapi.show(xpath="/config")  # type: ignore[attr-defined]
-            return str(pano.xapi.xml_result())  # type: ignore[attr-defined]
+            self._raw = str(pano.xapi.xml_result())  # type: ignore[attr-defined]
+            return self._raw
         except PscError:
             raise
         except Exception as exc:
@@ -256,6 +294,40 @@ class LiveSource:
     def snapshot(self) -> Snapshot:
         return parse_config(self.raw_xml())
 
+    def write_out(
+        self,
+        cs: ChangeSet,
+        *,
+        out_path: str | Path | None,
+        out_format: ConfigFormat = ConfigFormat.XML,
+    ) -> ApplyResult:
+        """Render `cs` to the `--out` artifact file from the live config.
+
+        This never touches the device's candidate config — it only writes a
+        local file the operator can review or paste. A `set` script is pure
+        rendering of the plan; an `xml` artifact is the *running* config (read
+        over the API) rewritten by the same offline applier. Honoured in a
+        dry-run because emitting a file is not a device mutation.
+        """
+        if out_path is None:
+            raise PscError("--out needs a PATH", ErrorType.CONFIG)
+        out = Path(out_path)
+        # Same blocker gate as every other write path: refuse before any bytes
+        # hit disk rather than leave a misleading artifact.
+        if cs.is_blocked:
+            raise PscError(
+                "refusing to write a blocked plan",
+                ErrorType.CONFLICT,
+                details={"blockers": cs.blockers},
+            )
+        if out_format is ConfigFormat.SET:
+            script = render_changeset(cs)
+            _write_artifact(out, "\n".join(script) + "\n")
+            return ApplyResult(applied=False, ops=cs.op_count, out_path=str(out), set_script=script)
+        new_xml = apply_changeset(self.raw_xml(), cs)
+        _write_artifact(out, new_xml)
+        return ApplyResult(applied=False, ops=cs.op_count, out_path=str(out))
+
     def apply(
         self,
         cs: ChangeSet,
@@ -265,9 +337,9 @@ class LiveSource:
     ) -> ApplyResult:
         """Push `cs` to Panorama's candidate config over the XML API.
 
-        `out_path`/`out_format` are accepted for interface parity with the
-        offline source but ignored — a live apply leaves a candidate on the
-        device, not a file, so there is no artifact to format.
+        When `out_path` is given, the `--out` artifact is written *first* (so a
+        reviewable file survives even if the device push later fails midway),
+        then the plan is pushed to the candidate.
 
         The plan is lowered to xpath set/edit/delete/rename ops and replayed in
         order (repoint before delete). The `blockers` gate and name-addressing
@@ -286,6 +358,13 @@ class LiveSource:
         # live update) before we touch the device.
         ops = plan_xapi_ops(cs)
 
+        # Write the reviewable artifact first so it survives a failed push.
+        artifact = (
+            self.write_out(cs, out_path=out_path, out_format=out_format)
+            if out_path is not None
+            else None
+        )
+
         from panos.errors import PanConnectionTimeout, PanURLError  # noqa: PLC0415
 
         pano = self._device()
@@ -323,4 +402,9 @@ class LiveSource:
                 ErrorType.TRANSPORT,
                 details={"sent": sent, "planned": len(ops)},
             ) from exc
-        return ApplyResult(applied=True, ops=len(ops), out_path=None)
+        return ApplyResult(
+            applied=True,
+            ops=len(ops),
+            out_path=artifact.out_path if artifact else None,
+            set_script=artifact.set_script if artifact else [],
+        )