From 3d95c1cc959bddba8a2b9cf36a9633d6cfe296f7 Mon Sep 17 00:00:00 2001
From: Azzurriii <vtthanh04.qb@gmail.com>
Date: Tue, 10 Nov 2026 16:19:33 +0700
Subject: [PATCH] feat: clearer runtime vs CLI updates, default checkpoint
 path, self-update

- update: checkpoint defaults to <home>/backups/ (or COSIGNER_BACKUP_DIR);
  backups/ is the only folder inside an instance that may hold archives
- update: shows the plan and asks before stopping Cosigner (--yes without a
  terminal), prints the restore command afterwards, adds --check (exit 10)
  and --json
- name the component everywhere: runtime update vs cosigner-cli update
  notices, version prints both (--check, --json)
- self-update: cosign-verified, atomic replacement of the CLI binary
- runtime needing a newer CLI points at self-update; errors carry hint: lines
- backup --out is optional; restore accepts a directory holding backups/
- doctor --json, help environment

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                       |  65 ++++++--
 cmd/cosigner-cli/main.go        |   9 +
 internal/app/app.go             |  35 ++--
 internal/app/app_test.go        |  10 --
 internal/app/commands.go        |  36 ++--
 internal/app/cosign.go          |   6 +
 internal/app/hints.go           |  53 ++++++
 internal/app/password.go        |   6 +-
 internal/app/recovery.go        |  94 ++++++++++-
 internal/app/registry.go        |  39 ++++-
 internal/app/selfupdate.go      | 232 ++++++++++++++++++++++++++
 internal/app/selfupdate_test.go | 146 ++++++++++++++++
 internal/app/update.go          | 263 ++++++++++++++++++++---------
 internal/app/update_test.go     | 286 ++++++++++++++++++++++++++++++++
 internal/app/version.go         | 126 ++++++++++++++
 15 files changed, 1269 insertions(+), 137 deletions(-)
 create mode 100644 internal/app/hints.go
 create mode 100644 internal/app/selfupdate.go
 create mode 100644 internal/app/selfupdate_test.go
 create mode 100644 internal/app/update_test.go
 create mode 100644 internal/app/version.go

diff --git a/README.md b/README.md
index 869aa7e..2f2cfe0 100644
--- a/README.md
+++ b/README.md
@@ -165,11 +165,18 @@ cosigner-cli logs -f
 | `backup`  | Encrypted backup of the instance (must be stopped)              |
 | `restore` | Restore a backup into an empty directory                        |
 | `export`  | Write `.mshare` files for Fystack Recovery (must be stopped)    |
-| `update`  | Verify and install a newer release                              |
-| `version` | Print CLI and runtime versions                                  |
+| `update`  | Update the **runtime** (container image) to a newer signed release |
+| `self-update` | Update **cosigner-cli** itself to a newer signed release    |
+| `version` | Print CLI and runtime versions (`--check` looks up the newest)  |
+| `help environment` | List every environment variable the CLI reads          |
 
 Global flags: `--home DIR` (or `COSIGNER_HOME`), `--docker CMD`.
 
+For scripts and agents: `version`, `doctor`, `update` and `self-update` take `--json` (the
+document goes to stdout, progress to stderr). `update --check` and `self-update --check` exit
+with status `10` when a newer release exists. Commands never prompt without a terminal: they
+fail, and a `hint:` line names the flag or variable to set (for example `--yes`).
+
 ## Approval callback
 
 `callback add` connects a paired cosigner to your approval callback. It generates the cosigner's
@@ -236,7 +243,7 @@ COSIGNER_PASSWORD_FD=3 cosigner-cli start 3< /run/secrets/cosigner-pw
 | Variable                        | Used by           |
 | ------------------------------- | ----------------- |
 | `COSIGNER_PASSWORD_FD`          | storage password  |
-| `COSIGNER_RECOVERY_PASSWORD_FD` | `backup`/`restore` |
+| `COSIGNER_RECOVERY_PASSWORD_FD` | `backup`/`restore`/`update` |
 
 `COSIGNER_PASSWORD` / `COSIGNER_RECOVERY_PASSWORD` also work but leak into the environment. Avoid them.
 
@@ -244,16 +251,19 @@ COSIGNER_PASSWORD_FD=3 cosigner-cli start 3< /run/secrets/cosigner-pw
 
 ```bash
 cosigner-cli stop
-cosigner-cli backup --out /secure/backups/cosigner.enc
+cosigner-cli backup                               # -> ./backups/backup-<version>-<time>.enc
 cosigner-cli export --out-dir /secure/exports     # --list to see wallets, --wallet ID to pick
 cosigner-cli start
 ```
 
 - `backup` asks for a separate **recovery password**. Store the archive and the password in different places.
+- Archives go to `<home>/backups/` unless you pass `--out PATH` or set `COSIGNER_BACKUP_DIR`. Backups never
+  include that folder. A copy on the instance's own disk is lost with the disk, so copy archives off-host.
+  Inside the instance, only `backups/` may hold archives.
 - `export` prints a six-word passphrase once. Store it apart from the `.mshare` files.
 - Backup size limit: 128 MiB of data.
 
-Restore into a new, empty directory:
+Restore into a new, empty directory (it may already contain a `backups/` folder holding the archive):
 
 ```bash
 cosigner-cli --home /srv/cosigner-restored restore --in /secure/backups/cosigner.enc
@@ -265,16 +275,49 @@ cosigner-cli --home /srv/cosigner-restored restore --in /secure/backups/cosigner
 
 ## Update
 
+Two things get updated, each with its own command and version number:
+
+| What | Command | Released from |
+| --- | --- | --- |
+| The **runtime**: the container that holds the key shares and signs | `cosigner-cli update` | `ghcr.io/fystack/cosigner` |
+| **cosigner-cli**: this tool | `cosigner-cli self-update` | GitHub releases of this repository |
+
+`cosigner-cli version --check` shows both, with the newest release of each.
+
+### Runtime
+
 ```bash
-cosigner-cli update --dry-run                                    # preview
-cosigner-cli update --backup-out /secure/backups/pre-update.enc  # install newest
-cosigner-cli update --version v1.2.3 --backup-out ...            # pin a version
+cosigner-cli update --dry-run                                    # verify and preview the newest release
+cosigner-cli update                                              # checkpoint to ./backups/, then install
+cosigner-cli update --backup-out /secure/backups/pre-update.enc  # checkpoint somewhere else
+cosigner-cli update --version v1.2.3 --yes                       # pin a version, no prompt (scripts)
+cosigner-cli update --check                                      # exit 10 when an update exists
 ```
 
-- Requires a newer release, a valid signature and a compatible runtime contract.
-- Always takes an encrypted checkpoint first. There is no automatic rollback.
+- Requires a newer release, a valid signature and a compatible runtime contract. If the runtime
+  needs a newer CLI, `update` says so: run `self-update` first.
+- Shows the plan (installed version, candidate version, checkpoint path, downtime) and asks before
+  it stops anything. Without a terminal, pass `--yes`.
+- Always takes an encrypted checkpoint first, in `<home>/backups/pre-update-<from>-to-<to>-<time>.enc`
+  by default. There is no automatic rollback. Afterwards it prints the restore command for that checkpoint.
+- Signing pauses from the stop until the new runtime is ready.
 - Pulls from the registry the instance was installed from. Switch with `--repository ghcr.io/fystack/cosigner`.
-- `start`, `restart`, `status` and `doctor` tell you when a new release exists. Disable with `COSIGNER_NO_UPDATE_CHECK=1`.
+
+### cosigner-cli
+
+```bash
+cosigner-cli self-update            # newest release
+sudo cosigner-cli self-update       # when the binary is in a root-owned directory such as /usr/local/bin
+cosigner-cli self-update --check    # exit 10 when an update exists
+```
+
+`self-update` downloads the release binary for this platform and verifies it with cosign against
+this repository's release workflow for that tag. That's the same check `install.sh` makes, and it
+runs even with `COSIGNER_SKIP_IMAGE_SIGNATURE_VERIFICATION=1`. The binary is replaced atomically
+only once it reports the expected version. The running Cosigner is not touched.
+
+`start`, `restart`, `status` and `doctor` tell you when a new runtime or CLI release exists, naming
+which one. Disable with `COSIGNER_NO_UPDATE_CHECK=1`.
 
 ## Security notes
 
diff --git a/cmd/cosigner-cli/main.go b/cmd/cosigner-cli/main.go
index 3d5e2c0..75c51ad 100644
--- a/cmd/cosigner-cli/main.go
+++ b/cmd/cosigner-cli/main.go
@@ -17,7 +17,16 @@ func main() {
 	a := app.New()
 	a.Version, a.Commit = version, commit
 	if err := a.Command().Execute(); err != nil {
+		// Checks such as `update --check` answer with the exit status alone.
+		var exit *app.ExitError
+		if errors.As(err, &exit) {
+			os.Exit(exit.Code)
+		}
 		fmt.Fprintln(os.Stderr, "error:", err)
+		var hinted interface{ Hint() string }
+		if errors.As(err, &hinted) {
+			fmt.Fprintln(os.Stderr, "hint:", hinted.Hint())
+		}
 		var usage *app.UsageError
 		if errors.As(err, &usage) {
 			fmt.Fprint(os.Stderr, usage.Help())
diff --git a/internal/app/app.go b/internal/app/app.go
index f9501c0..735f214 100644
--- a/internal/app/app.go
+++ b/internal/app/app.go
@@ -80,31 +80,44 @@ func (execRunner) Stream(ctx context.Context, name string, args []string, input
 }
 
 type App struct {
-	password        []byte
-	In              io.Reader
-	Out, Err        io.Writer
-	Getenv          func(string) string
-	Runner          Runner
-	Random          io.Reader
-	Tags            func(ctx context.Context, repository string) ([]string, error)
+	password []byte
+	In       io.Reader
+	Out, Err io.Writer
+	Getenv   func(string) string
+	Runner   Runner
+	Random   io.Reader
+	Tags     func(ctx context.Context, repository string) ([]string, error)
+	// LatestCLI returns the newest stable cosigner-cli release tag.
+	LatestCLI func(ctx context.Context) (string, error)
+	// Fetch downloads an HTTPS URL, failing beyond max bytes.
+	Fetch func(ctx context.Context, url string, max int64) ([]byte, error)
+	// Executable is the path of the running cosigner-cli, replaced by self-update.
+	Executable      func() (string, error)
 	Version, Commit string
 }
 
 func New() *App {
-	return &App{In: os.Stdin, Out: os.Stdout, Err: os.Stderr, Getenv: os.Getenv, Runner: execRunner{}, Random: rand.Reader, Tags: registryTags, Version: "dev", Commit: "dev"}
+	return &App{In: os.Stdin, Out: os.Stdout, Err: os.Stderr, Getenv: os.Getenv, Runner: execRunner{}, Random: rand.Reader, Tags: registryTags, LatestCLI: githubLatestRelease, Fetch: httpsFetch, Executable: os.Executable, Version: "dev", Commit: "dev"}
 }
 func (a *App) Command() *cobra.Command {
-	root := &cobra.Command{Use: "cosigner-cli", Short: "Manage a Cosigner installation", SilenceUsage: true, SilenceErrors: true}
+	root := &cobra.Command{Use: "cosigner-cli", Short: "Manage a Cosigner installation", Long: `cosigner-cli installs and runs the Cosigner runtime: the container that holds your
+key shares and signs. The CLI and the runtime are released and versioned separately:
+
+  cosigner-cli version       show both versions (--check looks up the newest)
+  cosigner-cli update        update the runtime (container image)
+  cosigner-cli self-update   update this CLI
+
+Run "cosigner-cli help environment" for the environment variables it reads.`, SilenceUsage: true, SilenceErrors: true}
 	root.SetIn(a.In)
 	root.SetOut(a.Out)
 	root.SetErr(a.Err)
 	root.PersistentFlags().String("home", "", "Instance directory (default: current directory)")
 	root.PersistentFlags().String("docker", "", "Docker command")
-	root.AddCommand(a.setupCommand(), a.startCommand(), a.stopCommand(), a.restartCommand(), a.statusCommand(), a.logsCommand(), a.doctorCommand(), a.infoCommand(), a.backupCommand(), a.restoreCommand(), a.exportCommand(), a.updateCommand(), a.callbackCommand(), a.versionCommand())
+	root.AddCommand(a.setupCommand(), a.startCommand(), a.stopCommand(), a.restartCommand(), a.statusCommand(), a.logsCommand(), a.doctorCommand(), a.infoCommand(), a.backupCommand(), a.restoreCommand(), a.exportCommand(), a.updateCommand(), a.selfUpdateCommand(), a.callbackCommand(), a.versionCommand(), environmentHelp())
 	for _, cmd := range root.Commands() {
 		cmd.Args = cobra.NoArgs
 		switch cmd.Name() {
-		case "version", "logs", "status", "info", "doctor":
+		case "version", "logs", "status", "info", "doctor", "self-update":
 		default:
 			if cmd.RunE != nil {
 				cmd.RunE = a.withInstance(cmd.RunE)
diff --git a/internal/app/app_test.go b/internal/app/app_test.go
index 9566a95..e20a1ad 100644
--- a/internal/app/app_test.go
+++ b/internal/app/app_test.go
@@ -624,16 +624,6 @@ func TestUpdateWithoutVersionUsesNewestRelease(t *testing.T) {
 	require.Empty(t, r.calls)
 }
 
-func TestUpdateRequiresBackupBeforePulling(t *testing.T) {
-	r := &fakeRunner{}
-	a := newTestApp(r)
-	l, _ := fixture(t, a)
-	cmd := a.Command()
-	cmd.SetArgs([]string{"--home", l.home, "update", "--version", "1.2.4"})
-	require.ErrorContains(t, cmd.Execute(), "--backup-out")
-	require.Empty(t, r.calls)
-}
-
 func TestStartupChecksContractWithoutReverifyingSignature(t *testing.T) {
 	r := &fakeRunner{run: func(c runCall) ([]byte, error) {
 		if c.name == "cosign" {
diff --git a/internal/app/commands.go b/internal/app/commands.go
index 1074a21..c45e7e7 100644
--- a/internal/app/commands.go
+++ b/internal/app/commands.go
@@ -612,8 +612,23 @@ func (a *App) logsCommand() *cobra.Command {
 	c.Flags().BoolP("follow", "f", false, "Follow logs")
 	return c
 }
+
+// doctorReport is the JSON shape of `doctor --json`. Failed checks are errors
+// (non-zero exit, message on stderr), not report fields.
+type doctorReport struct {
+	State          string `json:"state"`
+	Profile        string `json:"profile,omitempty"`
+	Image          string `json:"image,omitempty"`
+	RuntimeVersion string `json:"runtime_version,omitempty"`
+	CLIVersion     string `json:"cli_version"`
+}
+
 func (a *App) doctorCommand() *cobra.Command {
-	return &cobra.Command{Use: "doctor", Short: "Check Docker, configuration, and installation state", RunE: func(c *cobra.Command, _ []string) error {
+	c := &cobra.Command{Use: "doctor", Short: "Check Docker, configuration, and installation state", RunE: func(c *cobra.Command, _ []string) error {
+		asJSON, _ := c.Flags().GetBool("json")
+		emit, restore := a.jsonMode(asJSON)
+		defer restore()
+		report := doctorReport{CLIVersion: a.Version}
 		home, err := a.home(c)
 		if err != nil {
 			return err
@@ -629,11 +644,13 @@ func (a *App) doctorCommand() *cobra.Command {
 		}
 		if !fileExists(l.config) {
 			fmt.Fprintln(a.Out, "State: unconfigured")
-			return nil
+			report.State = "unconfigured"
+			return emit(report)
 		}
 		if !fileExists(l.pairing()) {
 			fmt.Fprintln(a.Out, "State: configured but unpaired")
-			return nil
+			report.State = "unpaired"
+			return emit(report)
 		}
 		if err := validatePaired(l, s); err != nil {
 			return err
@@ -655,11 +672,14 @@ func (a *App) doctorCommand() *cobra.Command {
 		if err != nil {
 			return err
 		}
-		fmt.Fprintf(a.Out, "profile: %s\nimage: %s\nruntime_version: %s\n", s.Profile, s.Image, caps.Version)
+		fmt.Fprintf(a.Out, "profile: %s\nimage: %s\nruntime_version: %s\ncli_version: %s\n", s.Profile, s.Image, caps.Version, a.Version)
 		fmt.Fprintln(a.Out, "State: paired (run `cosigner-cli status` for container state)")
 		a.notifyUpdate(c.Context(), s)
-		return nil
+		report.State, report.Profile, report.Image, report.RuntimeVersion = "paired", s.Profile, s.Image, vtag(caps.Version)
+		return emit(report)
 	}}
+	c.Flags().Bool("json", false, "Print the result as JSON on stdout; progress goes to stderr")
+	return c
 }
 func (a *App) infoCommand() *cobra.Command {
 	return &cobra.Command{Use: "info", Short: "Print public Cosigner identity", RunE: func(c *cobra.Command, _ []string) error {
@@ -709,9 +729,3 @@ func (a *App) waitReady(ctx context.Context, docker string, l layout, s Settings
 		}
 	}
 }
-func (a *App) versionCommand() *cobra.Command {
-	return &cobra.Command{Use: "version", Short: "Print host and runtime build identity", RunE: func(*cobra.Command, []string) error {
-		fmt.Fprintf(a.Out, "cosigner-cli %s (commit %s)\n", a.Version, a.Commit)
-		return nil
-	}}
-}
diff --git a/internal/app/cosign.go b/internal/app/cosign.go
index b5e8ab7..4333b0c 100644
--- a/internal/app/cosign.go
+++ b/internal/app/cosign.go
@@ -15,6 +15,12 @@ func (a *App) cosignOK(ctx context.Context) error {
 	if a.Getenv("COSIGNER_SKIP_IMAGE_SIGNATURE_VERIFICATION") == "1" {
 		return nil
 	}
+	return a.cosignInstalled(ctx)
+}
+
+// cosignInstalled checks for cosign regardless of the development skip switch;
+// self-update uses it because a CLI binary is never run unverified.
+func (a *App) cosignInstalled(ctx context.Context) error {
 	err := a.step("Checking Cosign", func() (string, error) {
 		raw, err := a.Runner.Run(ctx, "cosign", []string{"version"}, nil, nil)
 		if v := cosignVersion.FindSubmatch(raw); v != nil {
diff --git a/internal/app/hints.go b/internal/app/hints.go
new file mode 100644
index 0000000..dd1d01d
--- /dev/null
+++ b/internal/app/hints.go
@@ -0,0 +1,53 @@
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// exitUpdateAvailable is the status of `update --check` and
+// `self-update --check` when a newer release exists, so scripts can branch on it.
+const exitUpdateAvailable = 10
+
+// hintError carries the next command an operator (or an agent) should run.
+// main prints it on its own "hint:" line after the error.
+type hintError struct {
+	err  error
+	hint string
+}
+
+func (e *hintError) Error() string { return e.err.Error() }
+func (e *hintError) Unwrap() error { return e.err }
+func (e *hintError) Hint() string  { return e.hint }
+
+func withHint(err error, format string, args ...any) error {
+	return &hintError{err: err, hint: fmt.Sprintf(format, args...)}
+}
+
+// ExitError ends a command with a status code and no message, for checks whose
+// answer is the exit code.
+type ExitError struct{ Code int }
+
+func (e *ExitError) Error() string { return fmt.Sprintf("exit status %d", e.Code) }
+
+// vtag normalises a release version to the vX.Y.Z form used in all output.
+func vtag(version string) string { return "v" + strings.TrimPrefix(version, "v") }
+
+// jsonMode sends human progress to stderr for the rest of the command, so that
+// stdout carries only the JSON document the returned function writes.
+func (a *App) jsonMode(enabled bool) (emit func(any) error, restore func()) {
+	if !enabled {
+		return func(any) error { return nil }, func() {}
+	}
+	stdout := a.Out
+	a.Out = a.Err
+	return func(v any) error { return writeJSON(stdout, v) }, func() { a.Out = stdout }
+}
+
+func writeJSON(w io.Writer, v any) error {
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	return enc.Encode(v)
+}
diff --git a/internal/app/password.go b/internal/app/password.go
index 7d7d70c..8eb3566 100644
--- a/internal/app/password.go
+++ b/internal/app/password.go
@@ -34,6 +34,10 @@ const (
 	passphraseCheckWords = 3
 )
 
+// errNoPasswordInput means a password was needed but there is no terminal and
+// no environment variable to read it from.
+var errNoPasswordInput = errors.New(passwordEnv + " is required in non-interactive mode")
+
 // encryptedKEK is an encrypted, versioned representation of the hex storage
 // KEK. It deliberately contains KDF parameters and salt, but never a password
 // or derived key.
@@ -87,7 +91,7 @@ func (a *App) readPassword(confirm bool) (result []byte, resultErr error) {
 	}
 	file, ok := a.In.(*os.File)
 	if !ok || !isTerminal(file) {
-		return nil, fmt.Errorf("%s is required in non-interactive mode", passwordEnv)
+		return nil, withHint(errNoPasswordInput, "pass it on an open descriptor, for example COSIGNER_PASSWORD_FD=3 3<passphrase-file, or set %s", passwordEnv)
 	}
 	for {
 		fmt.Fprint(a.Out, "Storage encryption passphrase: ")
diff --git a/internal/app/recovery.go b/internal/app/recovery.go
index dd78fc5..d99c600 100644
--- a/internal/app/recovery.go
+++ b/internal/app/recovery.go
@@ -49,7 +49,11 @@ func (a *App) recoveryPassword(confirm bool) ([]byte, error) {
 		return ""
 	}
 	a.progress("Enter the separate recovery password (retain it outside this host).")
-	return copy.readPassword(confirm)
+	password, err := copy.readPassword(confirm)
+	if errors.Is(err, errNoPasswordInput) {
+		return nil, withHint(errors.New("COSIGNER_RECOVERY_PASSWORD is required in non-interactive mode"), "pass it on an open descriptor, for example COSIGNER_RECOVERY_PASSWORD_FD=3 3<recovery-password-file, or set COSIGNER_RECOVERY_PASSWORD")
+	}
+	return password, err
 }
 
 func sealRecovery(password, plaintext []byte) ([]byte, error) {
@@ -210,12 +214,11 @@ func (a *App) backupCommand() *cobra.Command {
 			return errors.New("stop the runtime before backup")
 		}
 		path, _ := c.Flags().GetString("out")
-		path, err = filepath.Abs(path)
-		if err != nil {
-			return err
+		if path == "" {
+			path = a.defaultArchive(l, "backup-"+vtag(s.RuntimeVersion))
 		}
-		if rel, err := filepath.Rel(l.home, path); err != nil || filepath.IsLocal(rel) {
-			return errors.New("write recovery archives outside the instance directory")
+		if path, err = archiveDestination(l, path); err != nil {
+			return err
 		}
 		password, err := a.recoveryPassword(true)
 		if err != nil {
@@ -226,12 +229,84 @@ func (a *App) backupCommand() *cobra.Command {
 			return err
 		}
 		fmt.Fprintf(a.Out, "Verified encrypted recovery archive: %s\nKeep the recovery password and storage unlock credentials separately.\n", path)
+		a.warnIfOnHost(l, path)
 		return nil
 	}}
-	c.Flags().String("out", "", "Output archive outside the instance directory")
-	_ = c.MarkFlagRequired("out")
+	c.Flags().String("out", "", "Output archive (default: <home>/backups/backup-<version>-<time>.enc, or COSIGNER_BACKUP_DIR)")
 	return c
 }
+
+// backupDir is the one folder inside an instance that may hold recovery
+// archives. Snapshots only read config, settings, state/ and secrets/, so
+// archives here are never captured into later archives.
+const backupDir = "backups"
+
+// defaultArchive names a new archive in COSIGNER_BACKUP_DIR or <home>/backups/.
+// The UTC timestamp keeps names unique, since archives are never overwritten.
+func (a *App) defaultArchive(l layout, name string) string {
+	dir := a.Getenv("COSIGNER_BACKUP_DIR")
+	if dir == "" {
+		dir = filepath.Join(l.home, backupDir)
+	}
+	return filepath.Join(dir, name+"-"+time.Now().UTC().Format("20060102T150405Z")+".enc")
+}
+
+// archiveDestination resolves where an archive may be written: outside the
+// instance, or inside its backups/ folder. Symlinks are resolved first, so a
+// backups/ link into state/ is refused like state/ itself.
+func archiveDestination(l layout, path string) (string, error) {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", err
+	}
+	resolved, err := resolveExisting(abs)
+	if err != nil {
+		return "", err
+	}
+	home, err := resolveExisting(l.home)
+	if err != nil {
+		return "", err
+	}
+	rel, err := filepath.Rel(home, resolved)
+	if err != nil {
+		return "", err
+	}
+	if !filepath.IsLocal(rel) {
+		return resolved, nil
+	}
+	if first, rest, _ := strings.Cut(filepath.ToSlash(rel), "/"); first == backupDir && rest != "" {
+		return resolved, nil
+	}
+	return "", withHint(fmt.Errorf("%s is inside the instance directory; recovery archives go outside it or in its %s/ folder", resolved, backupDir), "leave out the path to use %s", filepath.Join(l.home, backupDir))
+}
+
+// resolveExisting evaluates symlinks in the longest existing prefix of path.
+func resolveExisting(path string) (string, error) {
+	rest := ""
+	for p := path; ; {
+		real, err := filepath.EvalSymlinks(p)
+		if err == nil {
+			return filepath.Join(real, rest), nil
+		}
+		if !errors.Is(err, os.ErrNotExist) {
+			return "", err
+		}
+		parent := filepath.Dir(p)
+		if parent == p {
+			return path, nil
+		}
+		rest = filepath.Join(filepath.Base(p), rest)
+		p = parent
+	}
+}
+
+// warnIfOnHost reminds operators that an archive inside the instance shares
+// its disk: it undoes a bad update, but does not survive losing the host.
+func (a *App) warnIfOnHost(l layout, path string) {
+	if rel, err := filepath.Rel(l.home, path); err == nil && filepath.IsLocal(rel) {
+		a.warn("This archive is on the same host as the instance. Copy it off-host; it does not survive losing this disk.")
+	}
+}
 func (a *App) restoreCommand() *cobra.Command {
 	c := &cobra.Command{Use: "restore", Short: "Restore an encrypted backup into an empty directory", RunE: func(c *cobra.Command, _ []string) error {
 		home, err := a.home(c)
@@ -243,7 +318,8 @@ func (a *App) restoreCommand() *cobra.Command {
 			return err
 		}
 		for _, entry := range entries {
-			if entry.Name() != ".cosigner-cli.lock" {
+			// backups/ may hold the very archive being restored.
+			if entry.Name() != ".cosigner-cli.lock" && !(entry.Name() == backupDir && entry.IsDir()) {
 				return errors.New("restore requires an empty instance directory; existing state is never overwritten")
 			}
 		}
diff --git a/internal/app/registry.go b/internal/app/registry.go
index b02163b..45bdf54 100644
--- a/internal/app/registry.go
+++ b/internal/app/registry.go
@@ -10,6 +10,7 @@ import (
 	"net/url"
 	"regexp"
 	"strings"
+	"sync"
 	"time"
 )
 
@@ -43,18 +44,44 @@ func (a *App) newestRelease(ctx context.Context, repository string) (string, err
 }
 
 // notifyUpdate is best-effort and never blocks or fails the calling command.
+// It names the component, because the CLI and the runtime are versioned and
+// updated separately.
 func (a *App) notifyUpdate(ctx context.Context, s Settings) {
-	if a.Tags == nil || a.Getenv("COSIGNER_NO_UPDATE_CHECK") == "1" {
+	if a.Getenv("COSIGNER_NO_UPDATE_CHECK") == "1" {
 		return
 	}
 	ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
 	defer cancel()
-	repository, _, _ := strings.Cut(s.Image, "@")
-	newest, err := a.newestRelease(ctx, repository)
-	if err != nil || !stableVersionAfter(newest, s.RuntimeVersion) {
-		return
+	runtimeLatest, cliLatest := a.latestReleases(ctx, s)
+	if runtimeLatest != "" && stableVersionAfter(runtimeLatest, s.RuntimeVersion) {
+		fmt.Fprintf(a.Err, "==> Runtime update available: %s → %s (run `cosigner-cli update`)\n", vtag(s.RuntimeVersion), vtag(runtimeLatest))
+	}
+	if cliLatest != "" && stableVersionAfter(cliLatest, a.Version) {
+		fmt.Fprintf(a.Err, "==> cosigner-cli update available: %s → %s (run `cosigner-cli self-update`)\n", vtag(a.Version), vtag(cliLatest))
 	}
-	fmt.Fprintf(a.Err, "==> Update available: v%s → v%s (run `cosigner-cli update`)\n", strings.TrimPrefix(s.RuntimeVersion, "v"), strings.TrimPrefix(newest, "v"))
+}
+
+// latestReleases looks up the newest runtime (for an installed instance) and
+// CLI releases in parallel. A lookup that fails returns an empty string.
+func (a *App) latestReleases(ctx context.Context, s Settings) (runtimeLatest, cliLatest string) {
+	var wg sync.WaitGroup
+	if a.Tags != nil && s.Image != "" {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			repository, _, _ := strings.Cut(s.Image, "@")
+			runtimeLatest, _ = a.newestRelease(ctx, repository)
+		}()
+	}
+	if a.LatestCLI != nil && releaseVersion.MatchString(a.Version) {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			cliLatest, _ = a.LatestCLI(ctx)
+		}()
+	}
+	wg.Wait()
+	return runtimeLatest, cliLatest
 }
 
 // registryTags lists tags through the OCI distribution API, fetching an
diff --git a/internal/app/selfupdate.go b/internal/app/selfupdate.go
new file mode 100644
index 0000000..9aa6f98
--- /dev/null
+++ b/internal/app/selfupdate.go
@@ -0,0 +1,232 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+const (
+	cliRepository = "fystack/cosigner-cli"
+	cliBinaryMax  = 128 << 20
+	cliBundleMax  = 1 << 20
+	oidcIssuer    = "https://token.actions.githubusercontent.com"
+)
+
+// cliReport is the JSON shape of `self-update --json`.
+type cliReport struct {
+	Component       string `json:"component"`
+	Installed       string `json:"installed"`
+	Latest          string `json:"latest,omitempty"`
+	UpdateAvailable bool   `json:"update_available"`
+	Path            string `json:"path,omitempty"`
+	Updated         bool   `json:"updated"`
+}
+
+func (a *App) selfUpdateCommand() *cobra.Command {
+	c := &cobra.Command{
+		Use:   "self-update",
+		Short: "Update cosigner-cli itself to a newer signed release (not the runtime)",
+		Long: `Replace this cosigner-cli binary with a newer release from github.com/` + cliRepository + `.
+
+The new binary is verified with cosign against this repository's release workflow
+for that tag (the same check install.sh makes) and must report the expected version
+before it replaces the current one. The running Cosigner runtime is not touched; run
+"cosigner-cli update" to update the runtime.`,
+		Example: `  cosigner-cli self-update
+  cosigner-cli self-update --check            # exit 10 when a newer CLI exists
+  sudo cosigner-cli self-update               # when the binary is in a root-owned directory
+  cosigner-cli self-update --version v1.4.0`,
+		RunE: a.selfUpdate,
+	}
+	c.Flags().String("version", "", "Exact release version (default: newest stable release)")
+	c.Flags().Bool("check", false, "Only report whether a newer CLI exists (exit 10 when it does)")
+	c.Flags().Bool("json", false, "Print the result as JSON on stdout; progress goes to stderr")
+	return c
+}
+
+func (a *App) selfUpdate(c *cobra.Command, _ []string) error {
+	asJSON, _ := c.Flags().GetBool("json")
+	emit, restore := a.jsonMode(asJSON)
+	defer restore()
+	report := cliReport{Component: "cli", Installed: a.Version}
+	if !stableTag.MatchString(a.Version) {
+		return withHint(fmt.Errorf("this cosigner-cli is a development build (%s); self-update only replaces release builds", a.Version), "install a release with install.sh: https://cosigner.fystack.io")
+	}
+	version, _ := c.Flags().GetString("version")
+	if version == "" {
+		a.progress("Checking for the newest cosigner-cli release…")
+		latest, err := a.LatestCLI(c.Context())
+		if err != nil {
+			return fmt.Errorf("find the newest cosigner-cli release: %w", err)
+		}
+		version = latest
+		report.Latest = vtag(latest)
+		if !stableVersionAfter(version, a.Version) {
+			a.progress("cosigner-cli is up to date (" + vtag(a.Version) + ").")
+			return emit(report)
+		}
+	}
+	if !stableTag.MatchString(version) || !stableVersionAfter(version, a.Version) {
+		return errors.New("self-update requires a newer stable version (vX.Y.Z); to install another release, run install.sh --version")
+	}
+	tag := vtag(version)
+	report.UpdateAvailable = true
+	if check, _ := c.Flags().GetBool("check"); check {
+		a.progress(fmt.Sprintf("cosigner-cli update available: %s → %s (run `cosigner-cli self-update`)", vtag(a.Version), tag))
+		if err := emit(report); err != nil {
+			return err
+		}
+		return &ExitError{Code: exitUpdateAvailable}
+	}
+
+	exe, err := a.Executable()
+	if err != nil {
+		return err
+	}
+	if exe, err = filepath.EvalSymlinks(exe); err != nil {
+		return err
+	}
+	report.Path = exe
+	// Stage next to the binary so the final rename is atomic, and so a
+	// read-only directory fails before anything is downloaded.
+	staged, err := os.CreateTemp(filepath.Dir(exe), ".cosigner-cli-update-*")
+	if err != nil {
+		if errors.Is(err, os.ErrPermission) {
+			return withHint(fmt.Errorf("cannot write to %s: %w", filepath.Dir(exe), err), "run `sudo cosigner-cli self-update`")
+		}
+		return err
+	}
+	stagedPath := staged.Name()
+	defer os.Remove(stagedPath)
+	if err := a.cosignInstalled(c.Context()); err != nil {
+		staged.Close()
+		return err
+	}
+
+	asset := "cosigner-cli-" + runtime.GOOS + "-" + runtime.GOARCH
+	base := "https://github.com/" + cliRepository + "/releases/download/" + tag + "/"
+	var binary, bundle []byte
+	err = a.step("Downloading cosigner-cli "+tag+" ("+asset+")", func() (string, error) {
+		var err error
+		if binary, err = a.Fetch(c.Context(), base+asset, cliBinaryMax); err != nil {
+			return "", err
+		}
+		bundle, err = a.Fetch(c.Context(), base+asset+".sigstore.json", cliBundleMax)
+		return "Downloaded cosigner-cli " + tag, err
+	})
+	if err == nil {
+		_, err = staged.Write(binary)
+	}
+	if e := staged.Close(); err == nil {
+		err = e
+	}
+	if err == nil {
+		err = os.Chmod(stagedPath, 0755)
+	}
+	if err != nil {
+		return fmt.Errorf("download cosigner-cli %s: %w", tag, err)
+	}
+	bundleFile, err := os.CreateTemp("", "cosigner-cli-bundle-*.json")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(bundleFile.Name())
+	_, err = bundleFile.Write(bundle)
+	if e := bundleFile.Close(); err == nil {
+		err = e
+	}
+	if err != nil {
+		return err
+	}
+
+	identity := "https://github.com/" + cliRepository + "/.github/workflows/release.yml@refs/tags/" + tag
+	var raw []byte
+	err = a.step("Verifying cosigner-cli signature with Cosign", func() (string, error) {
+		var err error
+		raw, err = a.Runner.Run(c.Context(), "cosign", []string{"verify-blob", stagedPath, "--bundle", bundleFile.Name(), "--certificate-identity", identity, "--certificate-oidc-issuer", oidcIssuer}, nil, nil)
+		return "Signature verified: built by the " + cliRepository + " release workflow for " + tag, err
+	})
+	if err != nil {
+		return fmt.Errorf("signature verification failed for %s %s; nothing was replaced: %w: %s", asset, tag, err, bytes.TrimSpace(raw))
+	}
+	out, err := a.Runner.Run(c.Context(), stagedPath, []string{"version"}, nil, nil)
+	if want := []byte("cosigner-cli " + tag + " "); err != nil || !bytes.HasPrefix(out, want) {
+		return fmt.Errorf("downloaded cosigner-cli does not report %s; nothing was replaced", tag)
+	}
+	if err := os.Rename(stagedPath, exe); err != nil {
+		return err
+	}
+	if err := syncDirectory(filepath.Dir(exe)); err != nil {
+		return err
+	}
+	report.Updated = true
+	a.success(fmt.Sprintf("cosigner-cli updated: %s → %s (%s)", vtag(a.Version), tag, exe))
+	a.progress("The Cosigner runtime was not changed. Run `cosigner-cli update --check` to see whether it has an update.")
+	return emit(report)
+}
+
+// githubLatestRelease asks GitHub for the newest published release, which
+// excludes drafts and pre-releases.
+func githubLatestRelease(ctx context.Context) (string, error) {
+	raw, err := httpsFetch(ctx, "https://api.github.com/repos/"+cliRepository+"/releases/latest", 1<<20)
+	if err != nil {
+		return "", err
+	}
+	var release struct {
+		TagName string `json:"tag_name"`
+	}
+	if err := json.Unmarshal(raw, &release); err != nil {
+		return "", err
+	}
+	if !stableTag.MatchString(release.TagName) {
+		return "", fmt.Errorf("newest release tag %q is not a stable version", release.TagName)
+	}
+	return release.TagName, nil
+}
+
+// httpsFetch downloads url over HTTPS only, following redirects only to HTTPS.
+func httpsFetch(ctx context.Context, url string, max int64) ([]byte, error) {
+	client := &http.Client{Timeout: 5 * time.Minute, CheckRedirect: func(req *http.Request, via []*http.Request) error {
+		if req.URL.Scheme != "https" {
+			return errors.New("refusing a redirect away from HTTPS")
+		}
+		if len(via) >= 10 {
+			return errors.New("too many redirects")
+		}
+		return nil
+	}}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	if req.URL.Scheme != "https" {
+		return nil, errors.New("only HTTPS downloads are allowed")
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("%s returned %s", url, resp.Status)
+	}
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, max+1))
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(raw)) > max {
+		return nil, fmt.Errorf("%s is larger than %d bytes", url, max)
+	}
+	return raw, nil
+}
diff --git a/internal/app/selfupdate_test.go b/internal/app/selfupdate_test.go
new file mode 100644
index 0000000..0c8c743
--- /dev/null
+++ b/internal/app/selfupdate_test.go
@@ -0,0 +1,146 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// selfUpdateApp returns an app whose binary is a temp file and whose newest
+// CLI release is v1.3.0.
+func selfUpdateApp(t *testing.T, r *fakeRunner) (*App, string, *[]string) {
+	t.Helper()
+	exe := filepath.Join(t.TempDir(), "cosigner-cli")
+	require.NoError(t, os.WriteFile(exe, []byte("old binary"), 0755))
+	a := newTestApp(r)
+	a.Executable = func() (string, error) { return exe, nil }
+	a.LatestCLI = func(context.Context) (string, error) { return "v1.3.0", nil }
+	var fetched []string
+	a.Fetch = func(_ context.Context, url string, _ int64) ([]byte, error) {
+		fetched = append(fetched, url)
+		if strings.HasSuffix(url, ".sigstore.json") {
+			return []byte("{}"), nil
+		}
+		return []byte("new binary"), nil
+	}
+	return a, exe, &fetched
+}
+
+func TestSelfUpdateVerifiesThenReplacesBinary(t *testing.T) {
+	var verified []string
+	r := &fakeRunner{}
+	r.run = func(c runCall) ([]byte, error) {
+		if c.name == "cosign" && c.args[0] == "verify-blob" {
+			verified = c.args
+			raw, err := os.ReadFile(c.args[1])
+			require.NoError(t, err)
+			require.Equal(t, "new binary", string(raw), "cosign must check the bytes that get installed")
+			return nil, nil
+		}
+		if strings.Contains(filepath.Base(c.name), "cosigner-cli-update") {
+			return []byte("cosigner-cli v1.3.0 (commit def)\n"), nil
+		}
+		return nil, nil
+	}
+	a, exe, fetched := selfUpdateApp(t, r)
+	cmd := a.Command()
+	cmd.SetArgs([]string{"self-update"})
+	require.NoError(t, cmd.Execute())
+
+	raw, err := os.ReadFile(exe)
+	require.NoError(t, err)
+	require.Equal(t, "new binary", string(raw))
+	info, err := os.Stat(exe)
+	require.NoError(t, err)
+	require.Equal(t, os.FileMode(0755), info.Mode().Perm())
+	require.Contains(t, verified, "https://github.com/fystack/cosigner-cli/.github/workflows/release.yml@refs/tags/v1.3.0")
+	require.Contains(t, verified, "https://token.actions.githubusercontent.com")
+	require.Contains(t, (*fetched)[0], "/releases/download/v1.3.0/cosigner-cli-")
+	leftovers, err := filepath.Glob(filepath.Join(filepath.Dir(exe), ".cosigner-cli-update-*"))
+	require.NoError(t, err)
+	require.Empty(t, leftovers)
+}
+
+func TestSelfUpdateKeepsBinaryWhenVerificationFails(t *testing.T) {
+	for name, run := range map[string]func(runCall) ([]byte, error){
+		"signature": func(c runCall) ([]byte, error) {
+			if c.name == "cosign" && c.args[0] == "verify-blob" {
+				return []byte("no matching signatures"), errors.New("exit status 1")
+			}
+			return nil, nil
+		},
+		"version": func(c runCall) ([]byte, error) {
+			if c.name != "cosign" {
+				return []byte("cosigner-cli v1.2.9 (commit x)\n"), nil
+			}
+			return nil, nil
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			a, exe, _ := selfUpdateApp(t, &fakeRunner{run: run})
+			cmd := a.Command()
+			cmd.SetArgs([]string{"self-update"})
+			require.ErrorContains(t, cmd.Execute(), "nothing was replaced")
+			raw, err := os.ReadFile(exe)
+			require.NoError(t, err)
+			require.Equal(t, "old binary", string(raw))
+		})
+	}
+}
+
+func TestSelfUpdateVerifiesEvenWhenImageVerificationIsSkipped(t *testing.T) {
+	var verified bool
+	r := &fakeRunner{run: func(c runCall) ([]byte, error) {
+		if c.name == "cosign" && c.args[0] == "verify-blob" {
+			verified = true
+			return nil, errors.New("exit status 1")
+		}
+		return nil, nil
+	}}
+	a, _, _ := selfUpdateApp(t, r)
+	a.Getenv = func(k string) string {
+		if k == "COSIGNER_SKIP_IMAGE_SIGNATURE_VERIFICATION" {
+			return "1"
+		}
+		return ""
+	}
+	cmd := a.Command()
+	cmd.SetArgs([]string{"self-update"})
+	require.Error(t, cmd.Execute())
+	require.True(t, verified)
+}
+
+func TestSelfUpdateCheckAndDevelopmentBuilds(t *testing.T) {
+	r := &fakeRunner{}
+	a, exe, fetched := selfUpdateApp(t, r)
+	cmd := a.Command()
+	cmd.SetArgs([]string{"self-update", "--check"})
+	var exit *ExitError
+	require.True(t, errors.As(cmd.Execute(), &exit))
+	require.Equal(t, exitUpdateAvailable, exit.Code)
+	require.Empty(t, *fetched)
+	require.Empty(t, r.calls)
+
+	a.LatestCLI = func(context.Context) (string, error) { return "v1.2.3", nil }
+	cmd = a.Command()
+	cmd.SetArgs([]string{"self-update"})
+	require.NoError(t, cmd.Execute())
+	raw, err := os.ReadFile(exe)
+	require.NoError(t, err)
+	require.Equal(t, "old binary", string(raw))
+
+	a.Version = "dev"
+	cmd = a.Command()
+	cmd.SetArgs([]string{"self-update"})
+	require.ErrorContains(t, cmd.Execute(), "development build")
+
+	a.Version = "v1.2.3"
+	cmd = a.Command()
+	cmd.SetArgs([]string{"self-update", "--version", "v1.2.0"})
+	require.ErrorContains(t, cmd.Execute(), "newer stable version")
+}
diff --git a/internal/app/update.go b/internal/app/update.go
index 92fd1a8..bac9e13 100644
--- a/internal/app/update.go
+++ b/internal/app/update.go
@@ -6,7 +6,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"path/filepath"
 	"regexp"
 	"strconv"
 	"strings"
@@ -90,8 +89,13 @@ func (a *App) runtimeCapabilities(ctx context.Context, docker, image string) (ca
 	if err := json.Unmarshal(raw, &caps); err != nil {
 		return caps, fmt.Errorf("decode runtime contract: %w", err)
 	}
+	// A contract newer than this CLI speaks means the runtime was released for
+	// a newer cosigner-cli, which is the one fix an operator can apply.
+	if caps.OperatorAPI > 2 || caps.UnlockProtocol > 2 || caps.StorageSchema > 1 {
+		return caps, withHint(fmt.Errorf("runtime %s needs a newer cosigner-cli (this is %s)", vtag(caps.Version), a.Version), "run `cosigner-cli self-update`, then run this command again")
+	}
 	if caps.OperatorAPI != 2 || caps.UnlockProtocol != 2 || caps.StorageSchema != 1 || !releaseVersion.MatchString(caps.Version) {
-		return caps, errors.New("runtime is incompatible: require operator API 2, unlock 2, storage schema 1 and a release version")
+		return caps, withHint(errors.New("runtime is incompatible: require operator API 2, unlock 2, storage schema 1 and a release version"), "choose a runtime release made for cosigner-cli %s", a.Version)
 	}
 	return caps, nil
 }
@@ -150,93 +154,196 @@ func (a *App) resolveImage(ctx context.Context, docker, image string) (string, c
 	return pinned, caps, nil
 }
 
+// releaseRef names one release of a component in reports.
+type releaseRef struct {
+	Version string `json:"version"`
+	Image   string `json:"image,omitempty"`
+}
+
+// updateReport is the JSON shape of `update --json`.
+type updateReport struct {
+	Component       string      `json:"component"`
+	Installed       releaseRef  `json:"installed"`
+	Latest          string      `json:"latest,omitempty"`
+	UpdateAvailable bool        `json:"update_available"`
+	Candidate       *releaseRef `json:"candidate,omitempty"`
+	Checkpoint      string      `json:"checkpoint,omitempty"`
+	Updated         bool        `json:"updated"`
+}
+
 func (a *App) updateCommand() *cobra.Command {
-	c := &cobra.Command{Use: "update", Short: "Verify and install a release with an offline recovery checkpoint", RunE: func(c *cobra.Command, _ []string) error {
-		l, s, err := a.installation(c)
-		if err != nil {
-			return err
-		}
-		override, _ := c.Flags().GetString("repository")
-		repository, err := updateRepository(s.Image, override)
-		if err != nil {
+	c := &cobra.Command{
+		Use:   "update",
+		Short: "Update the Cosigner runtime (container image); self-update updates this CLI",
+		Long: `Update the Cosigner runtime: the signed container image that holds the key shares
+and signs. This does not update cosigner-cli itself; run "cosigner-cli self-update" for that.
+
+update verifies the new image's signature and runtime contract, asks for confirmation,
+stops Cosigner, writes an encrypted recovery checkpoint and starts the new image.
+Signing pauses until the new runtime is ready. There is no automatic rollback.
+
+The checkpoint goes to <home>/backups/ unless --backup-out or COSIGNER_BACKUP_DIR names
+another place. Copy it off this host afterwards.`,
+		Example: `  cosigner-cli update --dry-run      # verify and preview the newest release
+  cosigner-cli update                # checkpoint to <home>/backups/, then install it
+  cosigner-cli update --check        # exit 10 when a newer runtime exists
+  cosigner-cli update --version v1.2.3 --backup-out /secure/pre-update.enc --yes`,
+		RunE: a.update,
+	}
+	c.Flags().String("version", "", "Exact runtime release version (default: newest signed release)")
+	c.Flags().String("repository", "", "Image repository to pull the release from (default: the installed image's repository)")
+	c.Flags().Bool("dry-run", false, "Download, verify and show the candidate without changing the installation")
+	c.Flags().Bool("check", false, "Only report whether a newer runtime exists (exit 10 when it does); downloads nothing")
+	c.Flags().String("backup-out", "", "Recovery checkpoint path (default: <home>/backups/pre-update-<from>-to-<to>-<time>.enc)")
+	c.Flags().BoolP("yes", "y", false, "Do not ask for confirmation (required without a terminal)")
+	c.Flags().Bool("json", false, "Print the result as JSON on stdout; progress goes to stderr")
+	return c
+}
+
+func (a *App) update(c *cobra.Command, _ []string) error {
+	l, s, err := a.installation(c)
+	if err != nil {
+		return err
+	}
+	asJSON, _ := c.Flags().GetBool("json")
+	emit, restore := a.jsonMode(asJSON)
+	defer restore()
+	report := updateReport{Component: "runtime", Installed: releaseRef{Version: vtag(s.RuntimeVersion), Image: s.Image}}
+
+	override, _ := c.Flags().GetString("repository")
+	repository, err := updateRepository(s.Image, override)
+	if err != nil {
+		return err
+	}
+	check, _ := c.Flags().GetBool("check")
+	dryRun, _ := c.Flags().GetBool("dry-run")
+	if check && dryRun {
+		return &UsageError{Err: errors.New("--check and --dry-run cannot be combined"), cmd: c}
+	}
+	version, _ := c.Flags().GetString("version")
+	if version == "" {
+		a.progress("Checking for the newest Cosigner runtime release…")
+		if version, err = a.newestRelease(c.Context(), repository); err != nil {
 			return err
 		}
-		version, _ := c.Flags().GetString("version")
-		if version == "" {
-			a.progress("Checking for the newest Cosigner release…")
-			if version, err = a.newestRelease(c.Context(), repository); err != nil {
-				return err
-			}
-			if !stableVersionAfter(version, s.RuntimeVersion) {
-				a.progress("Cosigner is up to date (v" + strings.TrimPrefix(s.RuntimeVersion, "v") + ").")
-				return nil
-			}
-		}
-		if !releaseVersion.MatchString(version) {
-			return errors.New("--version must be a release version")
-		}
+		report.Latest = vtag(version)
 		if !stableVersionAfter(version, s.RuntimeVersion) {
-			return errors.New("update requires a newer stable version; downgrades and mutable replacement tags are not supported")
-		}
-		dryRun, _ := c.Flags().GetBool("dry-run")
-		backupPath, _ := c.Flags().GetString("backup-out")
-		if !dryRun && backupPath == "" {
-			return errors.New("--backup-out outside the instance directory is required")
-		}
-		if err := a.cosignOK(c.Context()); err != nil {
-			return err
-		}
-		docker := a.docker(c, s)
-		a.progress("Pulling Cosigner image " + repository + ":" + strings.TrimPrefix(version, "v") + "…")
-		pinned, caps, err := a.resolveImage(c.Context(), docker, repository+":"+strings.TrimPrefix(version, "v"))
-		if err != nil {
-			return err
-		}
-		fmt.Fprintf(a.Out, "Installed: %s (%s)\nCandidate: %s (%s)\nStorage schema: 1 (no migration)\n", s.RuntimeVersion, s.Image, caps.Version, pinned)
-		if dryRun {
-			return nil
+			a.progress("Cosigner runtime is up to date (" + vtag(s.RuntimeVersion) + ").")
+			return emit(report)
 		}
-		if pinned == s.Image {
-			a.progress("This digest is already installed.")
-			return nil
-		}
-		backupPath, err = filepath.Abs(backupPath)
-		if err != nil {
+	}
+	if !releaseVersion.MatchString(version) {
+		return errors.New("--version must be a release version")
+	}
+	if !stableVersionAfter(version, s.RuntimeVersion) {
+		return errors.New("update requires a newer stable version; downgrades and mutable replacement tags are not supported")
+	}
+	report.UpdateAvailable = true
+	if check {
+		a.progress(fmt.Sprintf("Runtime update available: %s → %s (run `cosigner-cli update`)", vtag(s.RuntimeVersion), vtag(version)))
+		if err := emit(report); err != nil {
 			return err
 		}
-		if rel, err := filepath.Rel(l.home, backupPath); err != nil || filepath.IsLocal(rel) {
-			return errors.New("recovery checkpoint must be outside the instance directory")
-		}
-		password, err := a.recoveryPassword(true)
+		return &ExitError{Code: exitUpdateAvailable}
+	}
+
+	// Settle the checkpoint location before downloading anything, so a bad
+	// path fails fast and the plan shows where the archive will go.
+	backupPath, _ := c.Flags().GetString("backup-out")
+	if backupPath == "" {
+		backupPath = a.defaultArchive(l, fmt.Sprintf("pre-update-%s-to-%s", vtag(s.RuntimeVersion), vtag(version)))
+	}
+	if backupPath, err = archiveDestination(l, backupPath); err != nil {
+		return err
+	}
+	yes, _ := c.Flags().GetBool("yes")
+
+	if err := a.cosignOK(c.Context()); err != nil {
+		return err
+	}
+	docker := a.docker(c, s)
+	image := repository + ":" + strings.TrimPrefix(version, "v")
+	a.progress("Pulling Cosigner runtime image " + image + "…")
+	pinned, caps, err := a.resolveImage(c.Context(), docker, image)
+	if err != nil {
+		return err
+	}
+	report.Candidate = &releaseRef{Version: vtag(caps.Version), Image: pinned}
+	if !dryRun {
+		report.Checkpoint = backupPath
+	}
+	a.printUpdatePlan(s, caps, pinned, backupPath, dryRun)
+	if dryRun {
+		return emit(report)
+	}
+	if pinned == s.Image {
+		a.progress("This digest is already installed.")
+		report.UpdateAvailable = false
+		return emit(report)
+	}
+	if !yes {
+		ok, err := a.confirm(fmt.Sprintf("Stop Cosigner, write the checkpoint and start %s? [y/N]: ", vtag(caps.Version)))
 		if err != nil {
 			return err
 		}
-		defer clear(password)
-		if _, err := a.compose(c.Context(), docker, l, s, "0", "unused", "stop", "cosigner"); err != nil {
-			return err
-		}
-		if err := a.writeRecovery(l, s, backupPath, password); err != nil {
-			return fmt.Errorf("runtime remains stopped; checkpoint failed: %w", err)
-		}
-		next := s
-		next.PreviousImage = s.Image
-		next.Image = pinned
-		next.RuntimeVersion = caps.Version
-		// Persist the candidate before launch so a failed launch is explicitly
-		// recoverable with start. Never restore an older MPC database automatically.
-		if err := saveSettings(l.home, next); err != nil {
-			return err
+		if !ok {
+			return errors.New("update cancelled; nothing was changed")
 		}
-		if err := a.startService(c.Context(), docker, l, next, true); err != nil {
-			return fmt.Errorf("candidate remains selected; no signing-state rollback was performed; inspect logs and recover explicitly: %w", err)
-		}
-		return nil
-	}}
-	c.Flags().String("version", "", "Exact release version (default: newest signed release)")
-	c.Flags().String("repository", "", "Image repository to pull the release from (default: the installed image's repository)")
-	c.Flags().Bool("dry-run", false, "Download, verify and show the candidate without changing the installation")
-	c.Flags().String("backup-out", "", "Encrypted pre-update recovery checkpoint outside the instance")
-	return c
+	}
+	password, err := a.recoveryPassword(true)
+	if err != nil {
+		return err
+	}
+	defer clear(password)
+	if _, err := a.compose(c.Context(), docker, l, s, "0", "unused", "stop", "cosigner"); err != nil {
+		return err
+	}
+	a.progress("Writing recovery checkpoint " + backupPath + "…")
+	if err := a.writeRecovery(l, s, backupPath, password); err != nil {
+		return withHint(fmt.Errorf("runtime remains stopped; checkpoint failed: %w", err), "fix the checkpoint location (--backup-out) and run update again, or run `cosigner-cli start` to resume %s", vtag(s.RuntimeVersion))
+	}
+	a.success("Recovery checkpoint written")
+	next := s
+	next.PreviousImage = s.Image
+	next.Image = pinned
+	next.RuntimeVersion = caps.Version
+	// Persist the candidate before launch so a failed launch is explicitly
+	// recoverable with start. Never restore an older MPC database automatically.
+	if err := saveSettings(l.home, next); err != nil {
+		return err
+	}
+	if err := a.startService(c.Context(), docker, l, next, true); err != nil {
+		return withHint(fmt.Errorf("runtime %s did not start; it stays selected and no signing state was rolled back: %w", vtag(caps.Version), err), "inspect `cosigner-cli logs`, fix the cause and run `cosigner-cli start`; the pre-update installation is in %s", backupPath)
+	}
+	report.Updated = true
+	a.success(fmt.Sprintf("Cosigner runtime updated: %s → %s", vtag(s.RuntimeVersion), vtag(caps.Version)))
+	a.printCheckpointNext(l, backupPath)
+	return emit(report)
+}
+
+// printUpdatePlan shows what update is about to do before anything changes.
+func (a *App) printUpdatePlan(s Settings, caps capabilities, pinned, checkpoint string, dryRun bool) {
+	verified := "signature and runtime contract verified"
+	if a.Getenv("COSIGNER_SKIP_IMAGE_SIGNATURE_VERIFICATION") == "1" {
+		verified = "runtime contract verified; signature NOT checked"
+	}
+	if dryRun {
+		checkpoint = "not written (dry run)"
+	}
+	fmt.Fprintf(a.Out, "\nCosigner runtime update\n")
+	fmt.Fprintf(a.Out, "  Installed   %-9s %s\n", vtag(s.RuntimeVersion), s.Image)
+	fmt.Fprintf(a.Out, "  Candidate   %-9s %s\n", vtag(caps.Version), pinned)
+	fmt.Fprintf(a.Out, "              %s\n", verified)
+	fmt.Fprintf(a.Out, "  Storage     schema %d, no migration\n", caps.StorageSchema)
+	fmt.Fprintf(a.Out, "  Checkpoint  %s\n", checkpoint)
+	fmt.Fprintf(a.Out, "  Downtime    signing pauses from stop until %s is ready\n\n", vtag(caps.Version))
+}
+
+// printCheckpointNext tells the operator where the checkpoint is and how to use it.
+func (a *App) printCheckpointNext(l layout, path string) {
+	fmt.Fprintf(a.Out, "Recovery checkpoint: %s\n", path)
+	a.warnIfOnHost(l, path)
+	fmt.Fprintf(a.Out, "To return to the pre-update installation, restore it into an empty directory:\n  cosigner-cli restore --home <empty-dir> --in %s\n", path)
 }
 
 func stableVersionAfter(candidate, current string) bool {
diff --git a/internal/app/update_test.go b/internal/app/update_test.go
new file mode 100644
index 0000000..6c6b092
--- /dev/null
+++ b/internal/app/update_test.go
@@ -0,0 +1,286 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// candidateRunner answers the pull, inspect and capability calls of an update
+// to v1.2.4 and records every call.
+func candidateRunner(t *testing.T, r *fakeRunner, extra func(runCall) ([]byte, error)) {
+	t.Helper()
+	digest := "fystacklabs/cosigner@sha256:" + strings.Repeat("b", 64)
+	r.run = func(c runCall) ([]byte, error) {
+		switch {
+		case c.name == "cosign":
+			return []byte("verified"), nil
+		case len(c.args) > 0 && c.args[0] == "pull":
+			return nil, nil
+		case len(c.args) > 1 && c.args[0] == "image" && c.args[1] == "inspect" && len(c.args) > 3:
+			return json.Marshal([]string{digest})
+		case len(c.args) > 0 && c.args[len(c.args)-1] == "capabilities":
+			return []byte(`{"operator_api":2,"unlock_protocol":2,"storage_schema":1,"version":"1.2.4"}`), nil
+		}
+		if extra != nil {
+			return extra(c)
+		}
+		return nil, nil
+	}
+}
+
+func composeCall(r *fakeRunner, verb string) bool {
+	for _, c := range r.calls {
+		if len(c.args) > 0 && c.args[0] == "compose" {
+			for _, arg := range c.args {
+				if arg == verb {
+					return true
+				}
+			}
+		}
+	}
+	return false
+}
+
+func TestArchiveDestinationAllowsOnlyOutsideOrBackupsFolder(t *testing.T) {
+	a := newTestApp(&fakeRunner{})
+	l, _ := fixture(t, a)
+	outside := filepath.Join(t.TempDir(), "a.enc")
+	for _, ok := range []string{outside, filepath.Join(l.home, "backups", "a.enc"), filepath.Join(l.home, "backups", "nested", "a.enc")} {
+		_, err := archiveDestination(l, ok)
+		require.NoError(t, err, ok)
+	}
+	for _, bad := range []string{filepath.Join(l.home, "a.enc"), filepath.Join(l.home, "state", "a.enc"), filepath.Join(l.home, "secrets", "a.enc"), filepath.Join(l.home, "backups")} {
+		_, err := archiveDestination(l, bad)
+		require.ErrorContains(t, err, "inside the instance directory", bad)
+	}
+	// A backups/ link into state/ is the state directory, not a backups folder.
+	require.NoError(t, os.Symlink(l.state, filepath.Join(l.home, "backups")))
+	_, err := archiveDestination(l, filepath.Join(l.home, "backups", "a.enc"))
+	require.ErrorContains(t, err, "inside the instance directory")
+}
+
+func TestUpdateRejectsCheckpointInsideInstanceBeforePulling(t *testing.T) {
+	r := &fakeRunner{}
+	a := newTestApp(r)
+	l, _ := fixture(t, a)
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "update", "--version", "1.2.4", "--backup-out", filepath.Join(l.state, "pre.enc")})
+	err := cmd.Execute()
+	require.ErrorContains(t, err, "inside the instance directory")
+	var hinted interface{ Hint() string }
+	require.True(t, errors.As(err, &hinted))
+	require.Contains(t, hinted.Hint(), filepath.Join(l.home, "backups"))
+	require.Empty(t, r.calls)
+}
+
+func TestUpdateWithoutTerminalRequiresYes(t *testing.T) {
+	r := &fakeRunner{}
+	a := newTestApp(r)
+	l, s := fixture(t, a)
+	candidateRunner(t, r, nil)
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "update", "--version", "1.2.4"})
+	require.ErrorContains(t, cmd.Execute(), "--yes")
+	require.False(t, composeCall(r, "stop"), "update must not stop Cosigner before it is confirmed")
+	after, err := loadSettings(l.home)
+	require.NoError(t, err)
+	require.Equal(t, s, after)
+	_, err = os.Stat(filepath.Join(l.home, "backups"))
+	require.ErrorIs(t, err, os.ErrNotExist)
+}
+
+func TestUpdateWritesDefaultCheckpointBeforeStartingCandidate(t *testing.T) {
+	r := &fakeRunner{}
+	a := newTestApp(r)
+	l, s := fixture(t, a)
+	a.Getenv = recoveryPasswordEnv("recovery password")
+	candidateRunner(t, r, nil)
+	var out bytes.Buffer
+	a.Out = &out
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "update", "--version", "1.2.4", "--yes"})
+	// The fixture has no storage passphrase, so the candidate fails to start
+	// after the checkpoint; that is the path where the checkpoint matters.
+	runErr := cmd.Execute()
+	require.ErrorContains(t, runErr, "did not start")
+	require.True(t, composeCall(r, "stop"))
+
+	entries, readErr := os.ReadDir(filepath.Join(l.home, "backups"))
+	require.NoError(t, readErr)
+	require.Len(t, entries, 1)
+	name := entries[0].Name()
+	require.True(t, strings.HasPrefix(name, "pre-update-v1.2.3-to-v1.2.4-"), name)
+	home, err := filepath.EvalSymlinks(l.home)
+	require.NoError(t, err)
+	checkpoint := filepath.Join(home, "backups", name)
+	var hinted interface{ Hint() string }
+	require.True(t, errors.As(runErr, &hinted))
+	require.Contains(t, hinted.Hint(), checkpoint)
+	require.Contains(t, out.String(), "Cosigner runtime update")
+	require.Contains(t, out.String(), "Checkpoint  "+checkpoint)
+
+	after, loadErr := loadSettings(l.home)
+	require.NoError(t, loadErr)
+	require.Equal(t, s.Image, after.PreviousImage)
+	require.Equal(t, "1.2.4", after.RuntimeVersion)
+
+	// The checkpoint restores into a directory that holds only it.
+	target := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(target, "backups"), 0700))
+	require.NoError(t, os.Rename(checkpoint, filepath.Join(target, "backups", name)))
+	cmd = a.Command()
+	cmd.SetArgs([]string{"--home", target, "restore", "--in", filepath.Join(target, "backups", name)})
+	require.NoError(t, cmd.Execute())
+	restored, err := loadSettings(target)
+	require.NoError(t, err)
+	require.Equal(t, s.Image, restored.Image)
+}
+
+func TestUpdateCheckAnswersWithExitStatus(t *testing.T) {
+	r := &fakeRunner{}
+	a := newTestApp(r)
+	l, _ := fixture(t, a)
+	a.Tags = func(context.Context, string) ([]string, error) { return []string{"1.2.3", "1.2.4"}, nil }
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "update", "--check"})
+	var exit *ExitError
+	require.True(t, errors.As(cmd.Execute(), &exit))
+	require.Equal(t, exitUpdateAvailable, exit.Code)
+	require.Empty(t, r.calls, "--check must not pull or verify anything")
+
+	a.Tags = func(context.Context, string) ([]string, error) { return []string{"1.2.3"}, nil }
+	cmd = a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "update", "--check"})
+	require.NoError(t, cmd.Execute())
+}
+
+func TestUpdateJSONKeepsStdoutParseable(t *testing.T) {
+	r := &fakeRunner{}
+	a := newTestApp(r)
+	l, _ := fixture(t, a)
+	candidateRunner(t, r, nil)
+	var stdout, stderr bytes.Buffer
+	a.Out, a.Err = &stdout, &stderr
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "update", "--version", "1.2.4", "--dry-run", "--json"})
+	require.NoError(t, cmd.Execute())
+	var report updateReport
+	require.NoError(t, json.Unmarshal(stdout.Bytes(), &report), stdout.String())
+	require.Equal(t, "runtime", report.Component)
+	require.Equal(t, "v1.2.3", report.Installed.Version)
+	require.True(t, report.UpdateAvailable)
+	require.Equal(t, "v1.2.4", report.Candidate.Version)
+	require.False(t, report.Updated)
+	require.Contains(t, stderr.String(), "Cosigner runtime update")
+}
+
+func TestRuntimeNeedingNewerCLIPointsAtSelfUpdate(t *testing.T) {
+	a := newTestApp(&fakeRunner{run: func(runCall) ([]byte, error) {
+		return []byte(`{"operator_api":3,"unlock_protocol":2,"storage_schema":1,"version":"2.0.0"}`), nil
+	}})
+	_, err := a.runtimeCapabilities(context.Background(), "docker", testImage)
+	require.ErrorContains(t, err, "runtime v2.0.0 needs a newer cosigner-cli")
+	var hinted interface{ Hint() string }
+	require.True(t, errors.As(err, &hinted))
+	require.Contains(t, hinted.Hint(), "self-update")
+}
+
+func TestVersionShowsCLIAndRuntime(t *testing.T) {
+	a := newTestApp(&fakeRunner{})
+	a.Commit = "abc123"
+	l, s := fixture(t, a)
+	var out bytes.Buffer
+	a.Out = &out
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "version"})
+	require.NoError(t, cmd.Execute())
+	lines := strings.Split(out.String(), "\n")
+	require.Equal(t, "cosigner-cli v1.2.3 (commit abc123)", lines[0], "install.sh parses this line")
+	require.Equal(t, "runtime      v1.2.3 ("+s.Image+")", lines[1])
+
+	out.Reset()
+	a.LatestCLI = func(context.Context) (string, error) { return "v1.3.0", nil }
+	a.Tags = func(context.Context, string) ([]string, error) { return []string{"1.2.3"}, nil }
+	cmd = a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "version", "--check", "--json"})
+	require.NoError(t, cmd.Execute())
+	var report versionReport
+	require.NoError(t, json.Unmarshal(out.Bytes(), &report))
+	require.Equal(t, "v1.3.0", report.CLI.Latest)
+	require.True(t, report.CLI.UpdateAvailable)
+	require.Equal(t, "v1.2.3", report.Runtime.Latest)
+	require.False(t, report.Runtime.UpdateAvailable)
+
+	out.Reset()
+	cmd = a.Command()
+	cmd.SetArgs([]string{"--home", t.TempDir(), "version"})
+	require.NoError(t, cmd.Execute())
+	require.Contains(t, out.String(), "runtime      not installed here")
+}
+
+func TestBackupDefaultsToBackupsFolder(t *testing.T) {
+	r := &fakeRunner{}
+	a := newTestApp(r)
+	l, _ := fixture(t, a)
+	a.Getenv = recoveryPasswordEnv("recovery password")
+	cmd := a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "backup"})
+	require.NoError(t, cmd.Execute())
+	entries, err := os.ReadDir(filepath.Join(l.home, "backups"))
+	require.NoError(t, err)
+	require.Len(t, entries, 1)
+	require.True(t, strings.HasPrefix(entries[0].Name(), "backup-v1.2.3-"))
+	info, err := os.Stat(filepath.Join(l.home, "backups"))
+	require.NoError(t, err)
+	require.Equal(t, os.FileMode(0700), info.Mode().Perm())
+
+	dir := t.TempDir()
+	a.Getenv = func(k string) string {
+		if k == "COSIGNER_BACKUP_DIR" {
+			return dir
+		}
+		return recoveryPasswordEnv("recovery password")(k)
+	}
+	cmd = a.Command()
+	cmd.SetArgs([]string{"--home", l.home, "backup"})
+	require.NoError(t, cmd.Execute())
+	entries, err = os.ReadDir(dir)
+	require.NoError(t, err)
+	require.Len(t, entries, 1)
+
+	// A later backup never captures earlier archives.
+	bundle, err := snapshotInstallation(l, Settings{Image: testImage})
+	require.NoError(t, err)
+	for _, f := range bundle.Files {
+		require.False(t, strings.HasPrefix(f.Path, "backups/"), f.Path)
+	}
+}
+
+func TestRecoveryPasswordWithoutTerminalNamesRecoveryVariables(t *testing.T) {
+	a := newTestApp(&fakeRunner{})
+	_, err := a.recoveryPassword(false)
+	require.ErrorContains(t, err, "COSIGNER_RECOVERY_PASSWORD is required")
+	var hinted interface{ Hint() string }
+	require.True(t, errors.As(err, &hinted))
+	require.Contains(t, hinted.Hint(), "COSIGNER_RECOVERY_PASSWORD_FD")
+}
+
+func TestHelpEnvironmentListsEveryVariable(t *testing.T) {
+	a := newTestApp(&fakeRunner{})
+	var out bytes.Buffer
+	a.Out = &out
+	cmd := a.Command()
+	cmd.SetArgs([]string{"help", "environment"})
+	require.NoError(t, cmd.Execute())
+	for _, name := range []string{"COSIGNER_HOME", "COSIGNER_BACKUP_DIR", "COSIGNER_PASSWORD_FD", "COSIGNER_PASSWORD", "COSIGNER_RECOVERY_PASSWORD_FD", "COSIGNER_RECOVERY_PASSWORD", "COSIGNER_NO_UPDATE_CHECK", "COSIGNER_SKIP_IMAGE_SIGNATURE_VERIFICATION"} {
+		require.Contains(t, out.String(), name)
+	}
+}
diff --git a/internal/app/version.go b/internal/app/version.go
new file mode 100644
index 0000000..e51db8f
--- /dev/null
+++ b/internal/app/version.go
@@ -0,0 +1,126 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// componentVersion is one entry of `version --json`.
+type componentVersion struct {
+	Version         string `json:"version"`
+	Commit          string `json:"commit,omitempty"`
+	Image           string `json:"image,omitempty"`
+	Latest          string `json:"latest,omitempty"`
+	UpdateAvailable bool   `json:"update_available,omitempty"`
+}
+
+type versionReport struct {
+	CLI     componentVersion  `json:"cli"`
+	Runtime *componentVersion `json:"runtime,omitempty"`
+}
+
+func (a *App) versionCommand() *cobra.Command {
+	c := &cobra.Command{
+		Use:   "version",
+		Short: "Print the cosigner-cli and Cosigner runtime versions",
+		Long: `Print the version of cosigner-cli (this tool) and of the Cosigner runtime installed
+in the instance directory. They are released separately: "update" updates the
+runtime and "self-update" updates the CLI.`,
+		Example: `  cosigner-cli version
+  cosigner-cli version --check         # also look up the newest releases
+  cosigner-cli version --check --json`,
+		RunE: a.version,
+	}
+	c.Flags().Bool("check", false, "Also look up the newest CLI and runtime releases (needs network)")
+	c.Flags().Bool("json", false, "Print JSON")
+	return c
+}
+
+func (a *App) version(c *cobra.Command, _ []string) error {
+	report := versionReport{CLI: componentVersion{Version: a.Version, Commit: a.Commit}}
+	var s Settings
+	var settingsErr error
+	if home, err := a.home(c); err == nil && fileExists(filepath.Join(home, "cosigner-cli.yaml")) {
+		if s, settingsErr = loadSettings(home); settingsErr == nil {
+			report.Runtime = &componentVersion{Version: vtag(s.RuntimeVersion), Image: s.Image}
+		}
+	}
+	if check, _ := c.Flags().GetBool("check"); check {
+		ctx, cancel := context.WithTimeout(c.Context(), 10*time.Second)
+		defer cancel()
+		runtimeLatest, cliLatest := a.latestReleases(ctx, s)
+		if cliLatest != "" {
+			report.CLI.Latest = vtag(cliLatest)
+			report.CLI.UpdateAvailable = stableVersionAfter(cliLatest, a.Version)
+		}
+		if report.Runtime != nil && runtimeLatest != "" {
+			report.Runtime.Latest = vtag(runtimeLatest)
+			report.Runtime.UpdateAvailable = stableVersionAfter(runtimeLatest, s.RuntimeVersion)
+		}
+	}
+	if asJSON, _ := c.Flags().GetBool("json"); asJSON {
+		return writeJSON(a.Out, report)
+	}
+	// install.sh parses the first line; keep it "cosigner-cli <version> (commit <commit>)".
+	fmt.Fprintf(a.Out, "cosigner-cli %s (commit %s)%s\n", a.Version, a.Commit, latestNote(report.CLI, "self-update"))
+	switch {
+	case report.Runtime != nil:
+		fmt.Fprintf(a.Out, "runtime      %s (%s)%s\n", report.Runtime.Version, report.Runtime.Image, latestNote(*report.Runtime, "update"))
+	case settingsErr != nil:
+		fmt.Fprintf(a.Out, "runtime      unknown (%v)\n", settingsErr)
+	default:
+		fmt.Fprintln(a.Out, "runtime      not installed here (pass --home or set COSIGNER_HOME)")
+	}
+	return nil
+}
+
+func latestNote(v componentVersion, command string) string {
+	switch {
+	case v.UpdateAvailable:
+		return fmt.Sprintf("  ← %s available: run `cosigner-cli %s`", v.Latest, command)
+	case v.Latest != "":
+		return "  (latest)"
+	}
+	return ""
+}
+
+// environmentHelp is the `cosigner-cli help environment` topic.
+func environmentHelp() *cobra.Command {
+	return &cobra.Command{
+		Use:   "environment",
+		Short: "Environment variables cosigner-cli reads",
+		Long: `Environment variables cosigner-cli reads.
+
+Instance
+  COSIGNER_HOME                    Instance directory, like --home (default: current directory)
+  COSIGNER_BACKUP_DIR              Folder for archives that update and backup write when no
+                                   path is given (default: <home>/backups)
+
+Storage passphrase (manual profile: up, start, restart)
+  COSIGNER_PASSWORD_FD             Read the passphrase from this open descriptor (>= 3), for
+                                   example COSIGNER_PASSWORD_FD=3 3<passphrase-file
+  COSIGNER_PASSWORD                The passphrase itself. Prefer COSIGNER_PASSWORD_FD: values in
+                                   the environment are visible to other processes of this user.
+
+Recovery password (backup, restore, update)
+  COSIGNER_RECOVERY_PASSWORD_FD    Read the recovery password from this open descriptor (>= 3)
+  COSIGNER_RECOVERY_PASSWORD       The recovery password itself
+
+Update checks
+  COSIGNER_NO_UPDATE_CHECK=1       Do not look for CLI or runtime updates after start, restart,
+                                   status and doctor
+
+Development only
+  COSIGNER_SKIP_IMAGE_SIGNATURE_VERIFICATION=1
+                                   Run runtime images without checking their signature. Never
+                                   set this on a host that holds real key shares. It does not
+                                   apply to self-update.
+
+Without a terminal, commands never prompt: they fail and say which variable or flag
+(such as --yes) to set.`,
+	}
+}