Keep command output to the README's stdout and stderr rules (closes #224)

The startup banner moves from stdout to stderr, so a `completion`
script, a `config get` value and the hidden `__complete` command print
only their own output. `--quiet`, `--cron` and `--json` still suppress
it.

A failing `remote info`, `prune` or `snapshot remove` under `--json`
now reports its error on stderr. Their reporters returned early under
`--json`, so the failure reached neither stream.

`snapshot verify --quiet` writes no report. A failure is still
returned and printed on stderr, with the same exit status.

Judgement call: the banner's stream, posted on the issue for the owner.

Model: opus-5-5

internal/cli/app.go

@@ -200,10 +200,10 @@ func RunApp(ctx context.Context, app *fx.App) error {
 }
 
 // errReported marks a failure the operation has already shown the user
-// (and deliberately withheld under --json). Entry turns it into a
-// non-zero exit status without printing anything further, so the error
-// line is not doubled. It flows up from RunOperation through cobra to
-// Entry.
+// (or, under `snapshot verify --json`, put in its document). Entry
+// turns it into a non-zero exit status without printing anything
+// further, so the error line is not doubled. It flows up from
+// RunOperation through cobra to Entry.
 var errReported = errors.New("operation failed")
 
 // RunOperation runs op against the Vaultik instance inside the fx app
@@ -220,10 +220,10 @@ var errReported = errors.New("operation failed")
 // interrupt OnStop cancels op and waits for the goroutine to return, so
 // op's cleanup (removing decrypted scratch files) runs before the
 // process exits; the wait is bounded by shutdownTimeout. report is
-// called with a non-canceled failure so the caller can log it (and
-// suppress it under --json) before it becomes errReported. A context
-// cancellation is the interrupt path, not a failure: it is neither
-// reported nor counted as one.
+// called with a non-canceled failure so the caller can show it to the
+// user before it becomes errReported. A context cancellation is the
+// interrupt path, not a failure: it is neither reported nor counted as
+// one.
 func RunOperation(
 	ctx context.Context, opts AppOptions,
 	op func(v *vaultik.Vaultik) error, report func(err error),
@@ -293,13 +293,12 @@ func RunOperation(
 // runVaultikApp runs the standard single-operation command lifecycle
 // shared by the snapshot list/purge/remove and remote nuke subcommands:
 // resolve the config, then run op against the Vaultik instance through
-// RunOperation, reporting a failure prefixed with failMsg (suppressed
-// while suppressErrors is true, e.g. under --json). mode says whether the
-// command takes the PID lock. jsonOutput marks a command whose stdout is a
-// JSON document: it quiets the UI but, unlike Quiet, leaves the stderr log
-// level alone.
+// RunOperation, reporting a failure prefixed with failMsg on stderr. mode
+// says whether the command takes the PID lock. jsonOutput marks a command
+// whose stdout is a JSON document: it quiets the UI but, unlike Quiet,
+// leaves the stderr log level alone.
 func runVaultikApp(
-	cmd *cobra.Command, mode lockMode, jsonOutput, suppressErrors bool,
+	cmd *cobra.Command, mode lockMode, jsonOutput bool,
 	failMsg string, op func(v *vaultik.Vaultik) error,
 ) error {
 	configPath, err := ResolveConfigPath()
@@ -319,10 +318,6 @@ func runVaultikApp(
 		},
 		Mode: mode,
 	}, op, func(err error) {
-		if suppressErrors {
-			return
-		}
-
 		log.Error(failMsg, "error", err)
 		ReportErrorf("%s: %v", failMsg, err)
 	})

internal/cli/entry.go

@@ -16,16 +16,18 @@ import (
 const shortCommitLen = 12
 
 // Entry is the main entry point for the CLI application.
-// It prints the startup banner to stdout (unless a banner-suppressing
+// It prints the startup banner to stderr (unless a banner-suppressing
 // flag is present in os.Args — see bannerSuppressedInArgs), executes the
 // root cobra command, and routes any returned error through the
 // ui.Writer so the user sees a properly formatted "🛑 ERROR:" line.
+// The banner goes to stderr because stdout carries only the output the
+// user asked for, such as a completion script or a `config get` value.
 //
 // It returns the process exit code (0 on success, 1 on error) rather
 // than calling os.Exit, so that main's deferred profile writers run
 // before the process ends. See run in cmd/vaultik/main.go.
 func Entry() int {
-	emitStartupBanner(os.Args[1:], os.Stdout)
+	emitStartupBanner(os.Args[1:], os.Stderr)
 
 	rootCmd := NewRootCommand()
 	rootCmd.SilenceErrors = true
@@ -33,8 +35,9 @@ func Entry() int {
 	err := rootCmd.Execute()
 	if err != nil {
 		// An operation that ran inside the fx app has already reported
-		// its own failure (and suppressed it under --json); errReported
-		// says so. Printing it again here would double the error line.
+		// its own failure (`snapshot verify --json` puts it in the
+		// document instead); errReported says so. Printing it again
+		// here would double the error line.
 		// Every other error — bad arguments, a config that would not
 		// load — reaches Entry unreported, so it is shown here.
 		if !errors.Is(err, errReported) {
@@ -49,9 +52,8 @@ func Entry() int {
 
 // emitStartupBanner writes the startup banner to w unless args (the
 // argument vector with the program name already stripped) contains a
-// flag that suppresses it. Split out of Entry so that the decision — the
-// only thing standing between a --json invocation and a parseable
-// stdout — is reachable from a test without running the whole CLI.
+// flag that suppresses it. Split out of Entry so that the decision is
+// reachable from a test without running the whole CLI.
 func emitStartupBanner(args []string, w io.Writer) {
 	if bannerSuppressedInArgs(args) {
 		return
@@ -86,8 +88,7 @@ func ReportErrorf(format string, args ...any) {
 // --json is a subcommand flag rather than a persistent one, but so is
 // --cron (it exists only on `snapshot create`), so this adds no new
 // class of imprecision. The only cost of a false positive is a missing
-// decorative banner; the cost of a false negative is a corrupt document
-// on stdout, so the scan errs deliberately in that direction.
+// decorative banner.
 func bannerSuppressedInArgs(args []string) bool {
 	for _, a := range args {
 		if a == "--" {

internal/cli/entry_banner_test.go

@@ -81,7 +81,7 @@ var jsonArgumentVectors = map[string][]string{
 // internal/vaultik's TestListSnapshots_JSONStdoutIsOnlyTheDocument
 // guards the same contract one layer down, but it calls the library
 // function directly and so cannot see Entry, which is where the
-// contamination was: the startup banner is written to stdout before
+// contamination was: the startup banner was written to stdout before
 // cobra parses anything, and the suppression scan did not know about
 // --json. The two banner lines and the blank line landed ahead of the
 // document and `jq` refused the result.
@@ -247,9 +247,8 @@ func TestEntryJSONStdoutIsExactlyOneDocument(t *testing.T) {
 // captureProcessStdout redirects the process's own stdout to a pipe for
 // the duration of fn and returns what was written to it. The redirection
 // has to be at the file-descriptor level rather than through an injected
-// writer, because the banner and the JSON encoder reach os.Stdout
-// independently and the point of the test is that both land in the same
-// place.
+// writer, because Entry and the commands it runs each reach os.Stdout
+// directly.
 //
 // Not parallel-safe: os.Stdout is process-global.
 func captureProcessStdout(t *testing.T, fn func()) string {

internal/cli/entry_status_test.go

@@ -15,8 +15,8 @@ import (
 // run, so a failing command must come back with a non-zero code rather
 // than ending the process here.
 //
-// Stdout is captured only to keep the banner and command output off the
-// test log; the assertion is on the returned code.
+// Stdout and stderr are captured only to keep the banner and command
+// output off the test log; the assertion is on the returned code.
 //
 //nolint:paralleltest // replaces os.Args and rootFlags
 func TestEntryReturnsStatusCode(t *testing.T) {
@@ -50,7 +50,7 @@ func TestEntryReturnsStatusCode(t *testing.T) {
 
 			var code int
 
-			_ = captureProcessStdout(t, func() { code = Entry() })
+			_, _ = captureProcessStdoutAndStderr(t, func() { code = Entry() })
 
 			assert.Equal(t, testCase.want, code)
 		})

internal/cli/entry_stdout_stderr_test.go

@@ -0,0 +1,152 @@
+package cli //nolint:testpackage // shares hermeticConfig and the capture helpers
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/adrg/xdg"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
+)
+
+// TestEntryCompletionStdoutIsTheScript runs `vaultik completion bash`,
+// whose stdout the README tells the user to source. The script has to
+// start on the first line.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout and os.Stderr
+func TestEntryCompletionStdoutIsTheScript(t *testing.T) {
+	code, stdout, _ := runEntry(t, "completion", "bash")
+
+	require.Equal(t, 0, code)
+
+	firstLine, _, _ := strings.Cut(stdout, "\n")
+	assert.True(t, strings.HasPrefix(firstLine, "# bash completion"),
+		"the first line of stdout must be the script's, got %q", firstLine)
+}
+
+// TestEntryConfigGetStdoutIsTheValue runs `vaultik config get`, whose
+// stdout a script reads as the value and nothing else.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout and os.Stderr
+func TestEntryConfigGetStdoutIsTheValue(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	require.NoError(t, os.WriteFile(configPath,
+		[]byte("hostname: test-host\n"), configFileMode))
+
+	code, stdout, _ := runEntry(t,
+		flagConfig, configPath, "config", "get", "hostname")
+
+	require.Equal(t, 0, code)
+	assert.Equal(t, "test-host\n", stdout)
+}
+
+// TestEntryJSONFailureIsReportedOnStderr runs each --json command that
+// writes no document when it fails, against a destination it cannot
+// use. The error must reach stderr, and stdout must stay empty.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntryJSONFailureIsReportedOnStderr(t *testing.T) {
+	for _, testCase := range []struct {
+		name         string
+		args         []string
+		wantOnStderr string
+	}{
+		{
+			name:         "remote info",
+			args:         []string{cmdRemote, cmdInfo, flagJSON},
+			wantOnStderr: "Failed to get remote info",
+		},
+		{
+			name:         "prune",
+			args:         []string{cmdPrune, flagJSON},
+			wantOnStderr: "Prune failed",
+		},
+		{
+			name:         "snapshot remove",
+			args:         []string{cmdSnapshot, cmdRemove, someSnapshotID, flagJSON},
+			wantOnStderr: "Failed to remove snapshot",
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			configPath := writeUnusableDestinationConfig(t)
+
+			code, stdout, stderr := runEntry(t,
+				append([]string{flagConfig, configPath}, testCase.args...)...)
+
+			assert.Equal(t, 1, code)
+			assert.Empty(t, stdout,
+				"a failed --json command has no document to write")
+			assert.Contains(t, stderr, testCase.wantOnStderr,
+				"the failure must be reported on stderr")
+		})
+	}
+}
+
+// writeUnusableDestinationConfig builds a config whose destination
+// directory does not exist, which fails `remote info`, and whose local
+// index is bound to another destination, which fails `prune` and
+// `snapshot remove` (a missing destination alone only makes `snapshot
+// remove` warn). Returns the config path.
+func writeUnusableDestinationConfig(t *testing.T) string {
+	t.Helper()
+
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.yml")
+	indexPath := filepath.Join(dir, "index.sqlite")
+
+	contents := fmt.Sprintf(hermeticConfig,
+		filepath.Join(dir, "source"),
+		filepath.Join(dir, "missing-store"),
+		indexPath)
+
+	require.NoError(t,
+		os.WriteFile(configPath, []byte(contents), configFileMode))
+
+	// The PID lock lives under xdg.DataHome, which xdg resolves at
+	// package init; point it at the temp dir so the test neither
+	// touches nor collides with the real one.
+	t.Setenv("XDG_DATA_HOME", filepath.Join(dir, "data"))
+	xdg.Reload()
+	t.Cleanup(xdg.Reload)
+
+	ctx := context.Background()
+
+	db, err := database.New(ctx, indexPath)
+	require.NoError(t, err)
+
+	defer func() { require.NoError(t, db.Close()) }()
+
+	require.NoError(t, database.NewRepositories(db).LocalMeta.Set(ctx,
+		database.LocalMetaKeyStorageURL, "file://"+filepath.Join(dir, "other")))
+
+	return configPath
+}
+
+// runEntry runs Entry with args after the program name and returns its
+// exit code and what it wrote to stdout and stderr.
+//
+// Not parallel-safe: it replaces os.Args, os.Stdout and os.Stderr.
+func runEntry(t *testing.T, args ...string) (int, string, string) {
+	t.Helper()
+
+	previousArgs := os.Args
+
+	t.Cleanup(func() {
+		os.Args = previousArgs
+		rootFlags = RootFlags{}
+	})
+
+	os.Args = append([]string{programName}, args...)
+
+	var code int
+
+	stdout, stderr := captureProcessStdoutAndStderr(t,
+		func() { code = Entry() })
+
+	return code, stdout, stderr
+}

internal/cli/prune.go

@@ -48,10 +48,6 @@ work (e.g. after a crashed backup or to reclaim storage).`,
 			}, func(v *vaultik.Vaultik) error {
 				return v.Prune(opts)
 			}, func(err error) {
-				if opts.JSON {
-					return
-				}
-
 				log.Error("Prune operation failed", "error", err)
 				ReportErrorf("Prune failed: %v", err)
 			})

internal/cli/remote.go

@@ -45,7 +45,7 @@ This is destructive and irreversible. Requires --force.`,
 				return errNukeNeedsForce
 			}
 
-			return runVaultikApp(cmd, mutating, false, false, "Remote nuke failed",
+			return runVaultikApp(cmd, mutating, false, "Remote nuke failed",
 				func(v *vaultik.Vaultik) error {
 					return v.NukeRemote(true)
 				})
@@ -92,10 +92,6 @@ func newRemoteInfoCommand() *cobra.Command {
 			}, func(v *vaultik.Vaultik) error {
 				return v.RemoteInfo(jsonOutput)
 			}, func(err error) {
-				if jsonOutput {
-					return
-				}
-
 				log.Error("Failed to get remote info", "error", err)
 				ReportErrorf("Failed to get remote info: %v", err)
 			})

internal/cli/snapshot.go

@@ -126,7 +126,7 @@ func newSnapshotListCommand() *cobra.Command {
 		Long:    "Lists all snapshots with their ID, timestamp, and compressed size",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			return runVaultikApp(cmd, readOnly, false, false,
+			return runVaultikApp(cmd, readOnly, false,
 				"Failed to list snapshots",
 				func(v *vaultik.Vaultik) error {
 					return v.ListSnapshots(jsonOutput)
@@ -162,7 +162,7 @@ restrict the operation to specific snapshot names.`,
 				return errPurgeCriteriaBoth
 			}
 
-			return runVaultikApp(cmd, mutating, false, false,
+			return runVaultikApp(cmd, mutating, false,
 				"Failed to purge snapshots",
 				func(v *vaultik.Vaultik) error {
 					return v.PurgeSnapshotsWithOptions(opts)
@@ -265,7 +265,7 @@ To wipe the entire destination store and start over, use 'vaultik remote
 nuke --force' — it is the single supported entry point for that.`,
 		Args: requireSnapshotIDArg,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runVaultikApp(cmd, mutating, opts.JSON, opts.JSON,
+			return runVaultikApp(cmd, mutating, opts.JSON,
 				"Failed to remove snapshot",
 				func(v *vaultik.Vaultik) error {
 					_, err := v.RemoveSnapshot(args[0], opts)

internal/vaultik/snapshot.go

@@ -727,7 +727,7 @@ func (v *Vaultik) VerifySnapshotWithOptions(
 	result.BlobCount = manifest.BlobCount
 	result.TotalSize = manifest.TotalCompressedSize
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Snapshot information:\n")
 		v.stdoutf("  Blob count:   %d\n", manifest.BlobCount)
 		v.stdoutf("  Total size:   %s\n", ubytes(manifest.TotalCompressedSize))
@@ -782,7 +782,7 @@ func (v *Vaultik) printVerifyHeader(snapshotID string, opts *VerifyOptions) {
 		snapshotTime = t
 	}
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Verifying snapshot %s\n", snapshotID)
 
 		if !snapshotTime.IsZero() {
@@ -822,7 +822,7 @@ func (v *Vaultik) verifyManifestBlobs(
 		stat, err := v.Storage.Stat(v.ctx, blobPath)
 		switch {
 		case err != nil:
-			if !opts.JSON {
+			if !opts.JSON && !v.UI.Quiet() {
 				v.stdoutf("  Missing: %s (%s)\n",
 					blob.Hash, ubytes(blob.CompressedSize))
 			}
@@ -830,7 +830,7 @@ func (v *Vaultik) verifyManifestBlobs(
 			missing++
 			missingSize += blob.CompressedSize
 		case stat.Size != blob.CompressedSize:
-			if !opts.JSON {
+			if !opts.JSON && !v.UI.Quiet() {
 				v.stdoutf("  Wrong size: %s (store has %s, manifest lists %s)\n",
 					blob.Hash, ubytes(stat.Size), ubytes(blob.CompressedSize))
 			}
@@ -862,6 +862,22 @@ func (v *Vaultik) formatVerifyResult(
 		return v.outputVerifyJSON(result)
 	}
 
+	// Under --quiet a failure is still returned, and the cli layer
+	// prints it on stderr.
+	if !v.UI.Quiet() {
+		v.printVerifySummary(result, failure)
+	}
+
+	if failure != "" {
+		return fmt.Errorf("%w: %s", errSnapshotVerifyFailed, failure)
+	}
+
+	return nil
+}
+
+// printVerifySummary prints the counts and the status line that end the
+// human-readable shallow verify report. failure is empty when it passed.
+func (v *Vaultik) printVerifySummary(result *VerifyResult, failure string) {
 	v.stdoutf("\nVerification complete:\n")
 	v.stdoutf("  Present with listed size: %d blobs\n", result.Verified)
 
@@ -883,14 +899,12 @@ func (v *Vaultik) formatVerifyResult(
 	if failure != "" {
 		v.stdoutf("FAILED - %s\n", failure)
 
-		return fmt.Errorf("%w: %s", errSnapshotVerifyFailed, failure)
+		return
 	}
 
 	// Report only what was actually checked: presence and size, not contents.
 	v.stdoutf("OK - all %d blobs listed in the manifest are present with the "+
 		"listed size; contents not checked (use --deep)\n", result.Verified)
-
-	return nil
 }
 
 // shallowVerifyFailure returns a human-readable description of everything

internal/vaultik/verify.go

@@ -103,7 +103,7 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 
 	log.Info("Starting snapshot verification", "snapshot_id", snapshotID, "mode", "deep")
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Deep verification of snapshot: %s\n\n", snapshotID)
 	}
 
@@ -143,10 +143,13 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 
 	log.Info("✓ Verification completed successfully",
 		"snapshot_id", snapshotID, "mode", "deep", "blobs_verified", len(dbBlobs))
-	v.stdoutf("\n✓ Verification completed successfully\n")
-	v.stdoutf("  Snapshot:       %s\n", snapshotID)
-	v.stdoutf("  Blobs verified: %d\n", len(dbBlobs))
-	v.stdoutf("  Total size:     %s\n", ubytes(totalSize))
+
+	if !v.UI.Quiet() {
+		v.stdoutf("\n✓ Verification completed successfully\n")
+		v.stdoutf("  Snapshot:       %s\n", snapshotID)
+		v.stdoutf("  Blobs verified: %d\n", len(dbBlobs))
+		v.stdoutf("  Total size:     %s\n", ubytes(totalSize))
+	}
 
 	return nil
 }
@@ -170,7 +173,7 @@ func (v *Vaultik) loadVerificationData(
 	// remote manifests; see its doc comment.
 	log.Info("Downloading manifest", "remote_key", remoteKey)
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Downloading manifest...\n")
 	}
 
@@ -185,7 +188,7 @@ func (v *Vaultik) loadVerificationData(
 		"manifest_blob_count", manifest.BlobCount,
 		"manifest_total_size", ubytes(manifest.TotalCompressedSize))
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Manifest loaded: %d blobs (%s)\n",
 			manifest.BlobCount, ubytes(manifest.TotalCompressedSize))
 		v.stdoutf("Downloading and decrypting database...\n")
@@ -215,7 +218,7 @@ func (v *Vaultik) loadVerificationData(
 		"db_blob_count", len(dbBlobs),
 		"db_total_size", ubytes(dbTotalSize))
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Database loaded: %d blobs (%s)\n",
 			len(dbBlobs), ubytes(dbTotalSize))
 	}
@@ -273,7 +276,7 @@ func (v *Vaultik) runVerificationSteps(
 	totalSize int64,
 	identities []age.Identity,
 ) error {
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Verifying manifest against database...\n")
 	}
 
@@ -282,7 +285,7 @@ func (v *Vaultik) runVerificationSteps(
 		return v.deepVerifyFailure(result, opts, err.Error(), err)
 	}
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("Manifest verified.\n")
 		v.stdoutf("Checking blob existence in remote storage...\n")
 	}
@@ -292,7 +295,7 @@ func (v *Vaultik) runVerificationSteps(
 		return v.deepVerifyFailure(result, opts, err.Error(), err)
 	}
 
-	if !opts.JSON {
+	if !opts.JSON && !v.UI.Quiet() {
 		v.stdoutf("All blobs exist.\n")
 		v.stdoutf("Downloading and verifying blob contents (%d blobs, %s)...\n",
 			len(dbBlobs), ubytes(totalSize))
@@ -748,7 +751,7 @@ func (v *Vaultik) performDeepVerificationFromDB(
 			"eta", eta.Round(time.Second),
 		)
 
-		if !opts.JSON {
+		if !opts.JSON && !v.UI.Quiet() {
 			v.stdoutf("  Verified %d/%d blobs (%d remaining) - %s/%s - elapsed %s, eta %s\n",
 				i+1, len(blobs), remaining,
 				ubytes(bytesProcessed),

internal/vaultik/verify_quiet_test.go

@@ -0,0 +1,92 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// TestVerify_QuietSuppressesReport is the --quiet contract for
+// `snapshot verify`: neither shallow nor deep verify writes its report,
+// a failed verify still returns its error (which the cli layer prints
+// on stderr), and the --json document still emits.
+func TestVerify_QuietSuppressesReport(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+
+	dataDir := filepath.Join(tempDir, "source")
+	storeDir := filepath.Join(tempDir, "remote")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	chunkSize := int64(32 * 1024)
+	maxBlobSize := int64(128 * 1024)
+
+	require.NoError(t, fs.MkdirAll(dataDir, 0o755))
+	require.NoError(t, afero.WriteFile(fs,
+		filepath.Join(dataDir, "data.bin"),
+		bytesPattern("quiet-", int(maxBlobSize*2)), 0o644))
+
+	ctx := context.Background()
+
+	cfg, storer, snapshotID := runFileStorageBackup(
+		ctx, t, fs, dataDir, storeDir, dbPath, chunkSize, maxBlobSize)
+
+	// The UI writes to the same buffer as Stdout, as both write to the
+	// process's stdout in production.
+	var stdout bytes.Buffer
+
+	newQuietVerifier := func() *vaultik.Vaultik {
+		v := &vaultik.Vaultik{
+			Config:  cfg,
+			Storage: storer,
+			Fs:      fs,
+			Stdout:  &stdout,
+			Stderr:  io.Discard,
+			UI:      ui.NewWithColor(&stdout, false),
+		}
+		v.SetContext(ctx)
+		v.UI.SetQuiet(true)
+
+		return v
+	}
+
+	require.NoError(t, newQuietVerifier().VerifySnapshotWithOptions(
+		snapshotID, &vaultik.VerifyOptions{}))
+	require.Empty(t, stdout.String(),
+		"shallow verify must write no report under --quiet")
+
+	require.NoError(t, newQuietVerifier().VerifySnapshotWithOptions(
+		snapshotID, &vaultik.VerifyOptions{Deep: true}))
+	require.Empty(t, stdout.String(),
+		"deep verify must write no report under --quiet")
+
+	require.NoError(t, newQuietVerifier().VerifySnapshotWithOptions(
+		snapshotID, &vaultik.VerifyOptions{JSON: true}))
+	require.Equal(t, "ok", decodeVerifyResult(t, stdout.Bytes()).Status,
+		"the --json document must still emit under --quiet")
+
+	// A snapshot without its encrypted database fails shallow verify.
+	require.NoError(t, os.Remove(filepath.Join(storeDir, "metadata",
+		snapshot.RemoteSnapshotKey(snapshotID), "db.zst.age")))
+
+	stdout.Reset()
+
+	require.Error(t, newQuietVerifier().VerifySnapshotWithOptions(
+		snapshotID, &vaultik.VerifyOptions{}),
+		"--quiet must not change the outcome of a failed verify")
+	require.Empty(t, stdout.String(),
+		"a failed verify must write no report under --quiet")
+}