From 994bd965c325ca4d840169649250b9f39a434a60 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Fri, 1 May 2026 11:42:11 -0400
Subject: [PATCH] cli: Add examples to ephemeral and libvirt --help

Right now some of our flows just install the release binary,
which won't get manpages. Also agents like to run `--help`.
Let's give both humans and agents some useful tips by default
when they run that.

Assisted-by: OpenCode (Claude Sonnet 4.5)
Signed-off-by: Colin Walters <walters@verbum.org>
---
 crates/kit/src/ephemeral.rs | 36 ++++++++++++++++++++++++++++++++++++
 crates/kit/src/main.rs      | 30 +++++++++++++++++++++++++++---
 2 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/crates/kit/src/ephemeral.rs b/crates/kit/src/ephemeral.rs
index 652a335..04071a1 100644
--- a/crates/kit/src/ephemeral.rs
+++ b/crates/kit/src/ephemeral.rs
@@ -64,6 +64,42 @@ pub struct ContainerListEntry {
 
 /// Ephemeral VM operations
 #[derive(Debug, Subcommand)]
+#[command(after_long_help = "\
+EXAMPLES:
+
+  Fire-and-forget interactive session (VM is removed on exit):
+
+    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42
+
+  Background VM you can reconnect to:
+
+    bcvk ephemeral run -d --rm --ssh-keygen --name myvm quay.io/fedora/fedora-bootc:42
+    bcvk ephemeral ssh myvm
+    podman stop myvm
+
+  Run a single command and capture its exit code (CI pattern):
+
+    bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42 -- systemctl is-active myservice
+
+  Stream the boot console in real time:
+
+    bcvk ephemeral run -d --console --name myvm quay.io/fedora/fedora-bootc:42
+    podman logs -f myvm
+
+  Mount a host directory into the VM (available at /run/virtiofs-mnt-src):
+
+    bcvk ephemeral run-ssh --bind .:src quay.io/fedora/fedora-bootc:42
+
+  Make the root filesystem writable (changes are still lost on shutdown):
+
+    bcvk ephemeral run-ssh --karg systemd.volatile=overlay quay.io/fedora/fedora-bootc:42
+
+  Tip for systemd unit authors - detect ephemeral vs. real hardware:
+
+    ConditionKernelCommandLine=!rootfstype=virtiofs
+
+  (virtiofs root is the stable indicator that the VM is running under bcvk ephemeral)\
+")]
 pub enum EphemeralCommands {
     /// Run bootc containers as ephemeral VMs
     #[clap(name = "run")]
diff --git a/crates/kit/src/main.rs b/crates/kit/src/main.rs
index eb8c877..0948e55 100644
--- a/crates/kit/src/main.rs
+++ b/crates/kit/src/main.rs
@@ -135,13 +135,13 @@ enum Commands {
     Images(images::ImagesOpts),
 
     #[cfg(target_os = "linux")]
-    /// Manage ephemeral VMs for bootc containers
+    /// Run bootc images as stateless VMs via QEMU+Podman (no root required)
     #[clap(subcommand)]
     Ephemeral(ephemeral::EphemeralCommands),
 
     // macOS stub: ephemeral command exists but errors out
     #[cfg(not(target_os = "linux"))]
-    /// Manage ephemeral VMs for bootc containers (not available on this platform)
+    /// Run bootc images as stateless VMs via QEMU+Podman (not available on this platform)
     #[clap(subcommand)]
     Ephemeral(StubEphemeralCommands),
 
@@ -152,7 +152,31 @@ enum Commands {
 
     // Note: libvirt is intentionally NOT available on macOS
     #[cfg(target_os = "linux")]
-    /// Manage libvirt integration for bootc containers
+    /// Run bootc images as persistent VMs managed by libvirt
+    #[clap(after_long_help = "\
+EXAMPLES:
+
+  Check that your libvirt environment is ready:
+
+    bcvk libvirt status
+
+  Create a persistent VM and SSH into it:
+
+    bcvk libvirt run --name myvm quay.io/centos-bootc/centos-bootc:stream10
+    bcvk libvirt ssh myvm
+
+  List running bootc VMs:
+
+    bcvk libvirt list
+
+  Connect to a remote hypervisor:
+
+    bcvk libvirt -c qemu+ssh://myhost/system run quay.io/fedora/fedora-bootc:42
+
+  Use base disks for fast VM cloning (saves disk space and creation time):
+
+    bcvk libvirt base-disks --help\
+")]
     Libvirt {
         /// Hypervisor connection URI (e.g., qemu:///system, qemu+ssh://host/system)
         #[clap(short = 'c', long = "connect", global = true)]