Inspecting & browsing snapshots

List what is in the catalog, then read a snapshot’s files without restoring anything. This is how you answer “is the file I need actually in last night’s backup?” in seconds. All global flags apply.

snapshots list

A richer kubectl get snapshots. It shows the policy, the origin, the phase, the kopia snapshot ID, real size and file counts from the run’s stats, and the start time. Rows are sorted newest first, can be filtered, and -A lists across namespaces.

$ kubectl kopiur snapshots list -n media
NAME                        POLICY   ORIGIN     PHASE      SNAPSHOT-ID   SIZE     FILES  START                 AGE
nightly-20260611-030012     nightly  scheduled  Succeeded  a1b2c3d4e5f6  5.0 GiB  1000   2026-06-11T03:00:12Z  9h

The filters can be combined:

Flag	Effect
--policy NAME	Only snapshots produced from this SnapshotPolicy.
--origin scheduled|manual|discovered	Only this origin. discovered = found in the repository by the catalog scan, not produced by this cluster.
--repository NAME	Only snapshots stored in this repository. Matches produced snapshots through their pinned status.resolved.repository and discovered ones through the repository-UID label.
--repository-kind repository|cluster-repository	Which kind --repository names (default repository).
--repository-namespace NS	Where the --repository lives, when it differs from the query namespace.

-o wide adds the kopia identity as username@hostname:path, the deletionPolicy, and the pin state Kopiur last observed.

ls / cat / download / browse

Read a snapshot’s files without restoring anything:

$ kubectl kopiur ls nightly-20260611-030012 -n media
NAME       TYPE  SIZE     MODIFIED
config/    dir   1.2 MiB  2026-06-10 21:14:02
movies.db  file  4.8 GiB  2026-06-11 02:59:31

$ kubectl kopiur ls nightly-20260611-030012 config -n media
$ kubectl kopiur cat nightly-20260611-030012 config/app.yaml -n media
$ kubectl kopiur download nightly-20260611-030012 movies.db ./movies.db -n media
$ kubectl kopiur browse nightly-20260611-030012 -n media   # interactive ls/cd/cat/get

All four take a Snapshot object name, whether scheduled, manual or discovered, so anything snapshots list shows with a kopia snapshot ID. They also take an optional path relative to the snapshot root.

cat streams the file to stdout and is safe for binary data, so you can pipe it anywhere. download writes the file locally, defaulting to the file’s own name, and verifies the byte count against the snapshot manifest; if the count does not match it deletes the partial file rather than leaving a truncated one behind. browse opens a small read-only shell with ls, cd, cat, get, pwd, help and quit.

ls -o wide adds the kopia object ID column, and ls -o json prints the kopia directory manifest exactly as kopia produced it.

The session-pod model

The first command against a repository starts a session pod: a mover Job in the snapshot’s namespace that connects to the repository read-only and then idles.

That first command takes a few seconds, for the pod start and the connect. Every later ls, cat or download against the same repository reuses the warm session and answers instantly.

The session expires on its own after --session-ttl, which defaults to 15m, and the cluster garbage-collects the finished Job a minute later. An abandoned browse therefore cannot hold a repository connection, or a pod, open forever. browse ends its session when you exit, unless you pass --keep.

Flag	Effect
--session-ttl DURATION	How long the session pod stays warm (default 15m).
--local	Skip the session pod; read with a local kopia binary (below).
--kopia-bin PATH	Which local kopia to run (--local only; default $KOPIUR_KOPIA_BINARY, then kopia on PATH).
--keep	(browse only) keep the session warm on exit.

A ClusterRepository that keeps its credential Secret in another namespace, usually the operator’s, is browsed through a copy the operator writes into the snapshot’s namespace for the session’s lifetime. It does that only under the gates a backup’s projection passes: the repository sets spec.credentialProjection.allowed: true, the run that took the snapshot opted in through its policy’s spec.credentialProjection.enabled: true, and the namespace is in allowedNamespaces. Otherwise browse says which gate is closed, and --local remains the way round it. See the console’s browse docs for the details, which are the same.

There is deliberately no --image flag. The session pod runs the exact mover image the operator’s controller Deployment is configured with, through KOPIUR_MOVER_IMAGE, falling back to the release default. Whatever browses your repository is always what backs it up.

The security model

Read-only is enforced twice, but the two layers are different things.

The first layer is an anti-footgun, not a security boundary. The session connects with kopia’s --readonly, and the CLI can only run a closed, typed set of kopia read commands, so snapshot list and object show. There is no way to express a mutating verb in the client, and the read-only connection refuses writes even if someone execs into the pod by hand.

The second layer is the actual boundary, and it is RBAC. Anyone who can create pods that reference the repository’s credential Secret in that namespace can already read the repository. Browsing needs exactly that power: create the session Job and exec into it. Note that it does not need permission to read Secrets. The pod loads the credentials itself, and they never pass through the user’s hands.

The chart ships an opt-in ClusterRole with exactly the browse permission set. Set rbac.browseRole: true and bind <release>-browse to the humans who should browse; a namespaced RoleBinding scopes them to one namespace. See the RBAC reference.

Binding browse in a namespace grants that namespace’s repository credentials

The session pod loads the repository credentials from its own environment, and RBAC cannot narrow pods/exec create to one pod. So anyone bound to the browse role in a namespace can exec into the session pod and print them with env.

That is the same power as “can create pods referencing the credential Secret here”, which is why it is not a new exposure in most clusters — but it is not the same as read-only, so bind it per namespace and to people you would hand those credentials to anyway.

Sessions are shared with the web console too

The web console browses snapshots through this same mechanism, keyed the same way. A session started by kubectl kopiur ls is reused by someone opening that repository in the console, and vice versa — one warm pod per repository, whoever opened it. kubectl kopiur session end ends it for both.

The console’s equivalent role is kopiur-ui-browse, which carries the same rules minus apps/deployments (the console is told its mover image through KOPIUR_MOVER_IMAGE instead). Granting either has the same consequence.

--local moves the credentials to your machine

--local is for clusters you cannot run pods in, or backends only reachable from your workstation.

It fetches the repository’s credential Secrets onto your machine, which needs get secrets RBAC that the session path never needs. It stages them in a private temp directory, removed afterwards, and runs a local kopia binary with a read-only connect. Install kopia first, or point --kopia-bin at it.

The backend endpoint must be reachable from your machine. An in-cluster MinIO needs a kubectl port-forward and a Repository endpoint your workstation can resolve.

Sessions are shared per repository

One warm session serves every command against the same repository. Exiting browse without --keep ends that shared session, so a second terminal in the middle of a read will see its next command fail and start a fresh session.

session end

End a warm browse session early. It would expire by TTL anyway.

$ kubectl kopiur session end nightly-20260611-030012 -n media   # via a snapshot in that repo
$ kubectl kopiur session end --repository nas -n media          # or the repository directly
session kopiur-browse-nas-1a2b3c4d ended (Job deleted)

The command deletes the session Job, and the session’s whole spec rides on that Job. When no session is open it says so and exits 0, so it is safe to call from cleanup scripts.

Sessions are also labeled kopiur.home-operations.com/session=browse, so a plain kubectl delete job -l kopiur.home-operations.com/session=browse works too.

Try it end-to-end

Read a snapshot’s files without restoring anything: list them, cat a config file, download a blob, then poke around interactively.

Prerequisite: the playground + one snapshot

This arc runs against the shared CLI playground: the media namespace, repository nas, and a seeded PVC holding config/app.yaml and movies.db. Apply it and install the plugin first, as described in the playground setup, then take one snapshot so there is something to browse:

$ kubectl kopiur snapshot now --policy nightly -n media --wait

1. List the snapshots to get a name with a kopia snapshot ID:

$ kubectl kopiur snapshots list -n media
NAME                              POLICY   ORIGIN   PHASE      SNAPSHOT-ID   SIZE     FILES  START                 AGE
nightly-manual-20260611030012     nightly  manual   Succeeded  a1b2c3d4e5f6  5.0 MiB  2      2026-06-11T03:00:12Z  1m

2. List its files, then read the config file straight to stdout:

$ kubectl kopiur ls nightly-manual-20260611030012 -n media
NAME        TYPE  SIZE     MODIFIED
config/     dir   29 B     2026-06-11 03:00:10
movies.db   file  5.0 MiB  2026-06-11 03:00:11

$ kubectl kopiur cat nightly-manual-20260611030012 config/app.yaml -n media
# demo config the CLI arcs read back
name: media-app
replicas: 1

3. Download the blob locally. It is verified against the snapshot’s byte count:

$ kubectl kopiur download nightly-manual-20260611030012 movies.db ./movies.db -n media
downloading movies.db to ./movies.db…
wrote 5242880 bytes to ./movies.db

4. Browse interactively (deep). The shell reuses the warm session, and quit ends it:

$ kubectl kopiur browse nightly-manual-20260611030012 -n media
browsing snapshot nightly-manual-20260611030012 (kopia a1b2c3d4e5f6) — read-only; `help` lists commands, `quit` leaves
kopiur:/> help
commands:
  ls            list the current directory
  cd <dir>      enter a directory (cd .. to go up)
  cat <file>    print a file to stdout
  get <file> [dest]  download a file
  pwd           print the current path
  help          this help
  quit          leave (also: exit, q, ctrl-d)
kopiur:/> ls
NAME        TYPE  SIZE     MODIFIED
config/     dir   29 B     2026-06-11 03:00:10
movies.db   file  5.0 MiB  2026-06-11 03:00:11
kopiur:/> cd config
kopiur:/config> cat app.yaml
# demo config the CLI arcs read back
name: media-app
replicas: 1
kopiur:/config> get app.yaml ./app.yaml
wrote 29 bytes to ./app.yaml
kopiur:/config> quit

5. Tidy up the warm session early. It would expire by TTL anyway:

$ kubectl kopiur session end nightly-manual-20260611030012 -n media
session kopiur-browse-nas-1a2b3c4d ended (Job deleted)

Illustrative output

The kopia ids, sizes, timestamps, the session-pod suffix such as …-1a2b3c4d, and the byte counts all vary per run. What appears exactly as shown is the browse banner, the kopiur:<path>> prompt, the help text, and the wrote N bytes to … and session … ended lines.