suve

Secret Unified Versioning Explorer

for   　　

[!NOTE] This project was written by AI (Claude Code).

A Git-like CLI/TUI/GUI for AWS Parameter Store / Secrets Manager, Google Cloud Secret Manager, and Azure Key Vault / App Configuration. Familiar commands like show, log, diff, and a staging workflow for safe, reviewable changes.

Features

• Git-like commands: show, log, diff, ls, tag
• Staging workflow: edit → status → diff → apply (review changes before applying), plus export / import for portable, per-service snapshots
• Version navigation: #VERSION, ~SHIFT, :LABEL syntax
• Colored diff output: Easy-to-read unified diff format
• Multi-cloud: AWS SSM Parameter Store / Secrets Manager, Google Cloud Secret Manager, and Azure Key Vault / App Configuration
• Secure staging: Working staging state is encrypted at rest with a data key stored in the OS keychain (override with SUVE_STAGING_KEY). When no key is available (no keychain backend and no SUVE_STAGING_KEY), an interactive session falls back to plaintext with a warning, while a non-interactive one refuses to write unencrypted unless SUVE_STAGING_ALLOW_PLAINTEXT is set. Exported snapshot files carry a separately passphrase-encrypted payload (Argon2 + AES-GCM; an empty passphrase writes plaintext).
• TUI mode: Keyboard-driven terminal UI via --tui flag (built with Bubble Tea); ships in every build, including the dependency-free CLI/TUI-only one
• GUI mode: Desktop application via --gui flag (built with Wails)

Metadata terminology

suve uses AWS-friendly terms and maps each backend's native concept onto three axes. Mind two naming traps: Google Cloud "labels" are suve tags (key=value metadata), and Azure App Configuration's "label" is suve's namespace (an identity axis, --namespace/--ns) — neither is the other.

All key=value metadata is unified as tags; suve adds no per-provider command or flag aliases. For the App Configuration label axis, see Namespaces.

Installation

[!NOTE] On Linux, suve requires GTK3 and WebKit2GTK for GUI support. Use the CLI/TUI-only version if you don't need the desktop GUI. The keyboard-driven TUI (--tui) is pure Go and ships in every build, including the CLI/TUI-only one — only the desktop GUI (--gui) needs the GTK3/WebKit2GTK dependencies.

Using mise (macOS/Linux/Windows)

suve is installable directly from GitHub Releases via mise's github backend — no extra registry required:

# Full version (CLI/TUI + GUI)
mise use -g "github:mpyw/suve"

# CLI/TUI-only version (no GUI dependencies, recommended for Linux. Not available on macOS/Windows)
mise use -g "github:mpyw/suve[matching=cli]"

[!TIP] Committing to a shared mise.toml used across OSes? Use a single cross-platform rule instead:

[tools]
"github:mpyw/suve" = { version = "latest", matching_regex = "(darwin|windows|cli_[0-9.]+_linux)" }

Using aqua (macOS/Linux/Windows)

suve is available in the standard aqua registry:

aqua g -i mpyw/suve

The registry picks the right asset per platform automatically: the self-contained GUI build on macOS/Windows, and the dependency-free CLI/TUI-only static build on Linux (so --gui is not available via aqua on Linux).

Using Homebrew (macOS/Linux)

# Full version (CLI/TUI + GUI)
brew install mpyw/tap/suve

# CLI/TUI-only version (no GUI dependencies, recommended for Linux)
brew install mpyw/tap/suve-cli

Using Scoop (Windows)

scoop bucket add mpyw https://github.com/mpyw/scoop-bucket.git
scoop install suve

Using npm (macOS/Linux/Windows)

# Global install
npm install -g @mpyw/suve

# Or run without installing
npx @mpyw/suve --version

The right prebuilt binary is pulled in automatically per platform: the self-contained GUI build on macOS/Windows, and the dependency-free CLI/TUI-only static build on Linux (so --gui is not available via npm on Linux).

Linux (.deb / .rpm)

Download packages from GitHub Releases:

Debian/Ubuntu (.deb):

export VERSION=0.0.0
export ARCH=amd64  # or arm64
export WEBKIT_SUFFIX=""  # use "_webkit2_41" for Ubuntu 24.04+

# CLI/TUI-only (recommended, no GUI dependencies)
curl -LO "https://github.com/mpyw/suve/releases/download/v${VERSION}/suve-cli_${VERSION}-1_${ARCH}.deb"
sudo dpkg -i "suve-cli_${VERSION}-1_${ARCH}.deb"

# Full version (CLI/TUI + GUI, requires GTK3 and WebKit2GTK)
curl -LO "https://github.com/mpyw/suve/releases/download/v${VERSION}/suve${WEBKIT_SUFFIX}_${VERSION}-1_${ARCH}.deb"
sudo dpkg -i "suve${WEBKIT_SUFFIX}_${VERSION}-1_${ARCH}.deb"

Note: Ubuntu 22.04/Debian uses webkit2gtk-4.0 (default). Ubuntu 24.04+ uses webkit2gtk-4.1 (set WEBKIT_SUFFIX="_webkit2_41").

Red Hat/Fedora (.rpm):

export VERSION=0.0.0
export ARCH=x86_64  # or aarch64
export WEBKIT_SUFFIX=""  # use "_webkit2_41" for Fedora 40+

# CLI/TUI-only (recommended, no GUI dependencies)
curl -LO "https://github.com/mpyw/suve/releases/download/v${VERSION}/suve-cli-${VERSION}-1.${ARCH}.rpm"
sudo rpm -i "suve-cli-${VERSION}-1.${ARCH}.rpm"

# Full version (CLI/TUI + GUI, requires GTK3 and WebKit2GTK)
curl -LO "https://github.com/mpyw/suve/releases/download/v${VERSION}/suve${WEBKIT_SUFFIX}-${VERSION}-1.${ARCH}.rpm"
sudo rpm -i "suve${WEBKIT_SUFFIX}-${VERSION}-1.${ARCH}.rpm"

Note: Fedora 39 and earlier uses webkit2gtk-4.0 (default). Fedora 40+ uses webkit2gtk-4.1 (set WEBKIT_SUFFIX="_webkit2_41").

Using go install (CLI/TUI only)

go install github.com/mpyw/suve/cmd/suve@latest

Note: go install builds the CLI/TUI only. The desktop GUI requires pre-built assets that are not included in the Go module. For GUI support, use a package manager or build from source.

Using go tool (CLI/TUI only, Go 1.25+)

# Add to go.mod as a tool dependency
go get -tool github.com/mpyw/suve/cmd/suve@latest

# Run via go tool
go tool suve param show /my/param

Building from Source

For platforms without pre-built packages (e.g., Arch Linux) or if you need the latest development version with GUI:

Requires Go 1.25+.

git clone https://github.com/mpyw/suve.git
cd suve

CLI/TUI only:

mise build-cli
# Binary: bin/suve

CLI/TUI + GUI (requires Node.js for the frontend build):

mise build-gui
# Binary: bin/suve  (run `suve --gui`)

Build dependencies for GUI:

Platform	Dependencies
All	Node.js (for frontend build)
macOS	Xcode Command Line Tools
Windows	WebView2 Runtime (usually pre-installed)

Linux build dependencies and webkit2gtk-4.1 support

Linux requires GTK3 and WebKit2GTK:

Platform	Dependencies
Ubuntu 22.04/Debian	sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev
Ubuntu 24.04+	sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
Fedora 39	sudo dnf install gtk3-devel webkit2gtk4.0-devel
Fedora 40+	sudo dnf install gtk3-devel webkit2gtk4.1-devel
Arch Linux	sudo pacman -S gtk3 webkit2gtk-4.1

For webkit2gtk-4.1 (Ubuntu 24.04+, Fedora 40+, Arch Linux), add the webkit2_41 build tag via SUVE_GUI_TAGS:

SUVE_GUI_TAGS=production,webkit2_41 mise build-gui

Shell Completion

suve can generate completion scripts for bash, zsh, fish, and PowerShell. Source the output to enable completion for commands, subcommands, and flags.

# bash — add to ~/.bashrc
source <(suve completion bash)

# zsh — add to ~/.zshrc
source <(suve completion zsh)

# fish
suve completion fish > ~/.config/fish/completions/suve.fish

# PowerShell — add to $PROFILE
suve completion pwsh | Out-String | Invoke-Expression

Authentication

suve talks to each cloud's data plane using that cloud's own SDK credential chain — the same one the native CLI (aws / gcloud / az) uses. There is nothing suve-specific to configure: sign in the normal way, then point suve at the resource with an environment variable (or the equivalent flag).

aws sso login \
  --profile prod

export AWS_PROFILE=prod
export AWS_REGION=us-east-1

gcloud auth \
  application-default \
  login

export GOOGLE_CLOUD_PROJECT=my-project

az login

# secret
export AZURE_KEYVAULT_NAME=my-vault
# param
export AZURE_APPCONFIG_NAME=my-store

[!NOTE]

• Every value has a flag equivalent: --profile/--region, --project, --vault-name/--store-name.
• AWS — the standard credential chain: SSO, static keys, ~/.aws/credentials, or an IAM role. With aws-vault: aws-vault exec prod -- suve param show /my/param.
• Google Cloud — Application Default Credentials; or a service-account key via GOOGLE_APPLICATION_CREDENTIALS.
• Azure — the DefaultAzureCredential chain; or a service principal via AZURE_CLIENT_ID / AZURE_CLIENT_SECRET / AZURE_TENANT_ID. az login sets no environment variables — it caches credentials under ~/.azure, which suve reuses. The Key Vault / App Configuration name is a globally-unique endpoint, so no subscription or resource group is needed.

Getting Started

Basic Commands

user@host:~$ suve param show /app/config/database-url
Name: /app/config/database-url
Version: 3
Type: SecureString
Modified: 2024-01-15T10:30:45Z

  postgres://db.example.com:5432/myapp

user@host:~$ suve param show --raw /app/config/database-url
postgres://db.example.com:5432/myapp

The show command displays value with metadata; --raw outputs raw value for piping:

# Use in scripts
DB_URL=$(suve param show --raw /app/config/database-url)

# Pipe to file
suve param show --raw /app/config/ssl-cert > cert.pem

Version History with log

View version history, just like git log:

user@host:~$ suve param log /app/config/database-url
Version 3 (current)
Date: 2024-01-15T10:30:45Z
postgres://db.example.com:5432/myapp...

Version 2
Date: 2024-01-14T09:20:30Z
postgres://old-db.example.com:5432/myapp...

Version 1
Date: 2024-01-13T08:10:00Z
postgres://localhost:5432/myapp...

Use --patch to see what changed in each version:

user@host:~$ suve param log --patch /app/config/database-url

Output will look like:

Version 3 (current)
Date: 2024-01-15T10:30:45Z

--- /app/config/database-url#2
+++ /app/config/database-url#3
@@ -1 +1 @@
-postgres://old-db.example.com:5432/myapp
+postgres://db.example.com:5432/myapp

Version 2
Date: 2024-01-14T09:20:30Z

--- /app/config/database-url#1
+++ /app/config/database-url#2
@@ -1 +1 @@
-postgres://localhost:5432/myapp
+postgres://old-db.example.com:5432/myapp

[!TIP] Add --parse-json to pretty-print JSON values before diffing. This normalizes formatting and sorts keys alphabetically, so you can focus on the actual content changes rather than formatting differences:

suve param log --patch --parse-json /app/config/credentials

Comparing Versions with diff

Compare previous version with latest (most common use case):

user@host:~$ suve param diff /app/config/database-url~

Output will look like:

--- /app/config/database-url#2
+++ /app/config/database-url#3
@@ -1 +1 @@
-postgres://old-db.example.com:5432/myapp
+postgres://db.example.com:5432/myapp

Compare any two specific versions:

user@host:~$ suve param diff /app/config/database-url#1 /app/config/database-url#3

Output will look like:

--- /app/config/database-url#1
+++ /app/config/database-url#3
@@ -1 +1 @@
-postgres://localhost:5432/myapp
+postgres://db.example.com:5432/myapp

Staging Workflow

[!NOTE] The staging workflow lets you prepare changes locally, review them, and apply when ready—just like git add → git diff --staged → git commit. For detailed documentation, see Staging State Transitions.

[!TIP] Staged values live in encrypted files under ~/.suve/staging/. Use suve stage export <dir> to write them to portable snapshot files and suve stage import <dir> to restore them later.

1. Stage changes (opens editor or accepts value directly):

[!TIP] To use VSCode or Cursor as your editor, set export VISUAL='code --wait' or export VISUAL='cursor --wait' in your shell profile.

user@host:~$ suve stage param add /app/config/new-param "my-value"
✓ Staged for creation: /app/config/new-param

user@host:~$ suve stage param edit /app/config/database-url
✓ Staged: /app/config/database-url

user@host:~$ suve stage param delete /app/config/old-param
✓ Staged for deletion: /app/config/old-param

2. Review staged changes:

user@host:~$ suve stage status
Staged SSM Parameter Store changes (3):
  A /app/config/new-param
  M /app/config/database-url
  D /app/config/old-param

user@host:~$ suve stage diff

Output will look like:

--- /app/config/database-url#3 (AWS)
+++ /app/config/database-url (staged)
@@ -1 +1 @@
-postgres://db.example.com:5432/myapp
+postgres://new-db.example.com:5432/myapp

--- /app/config/new-param (not in AWS)
+++ /app/config/new-param (staged for creation)
@@ -0,0 +1 @@
+my-value

--- /app/config/old-param#2 (AWS)
+++ /app/config/old-param (staged for deletion)
@@ -1 +0,0 @@
-deprecated-value

3. Apply changes:

user@host:~$ suve stage apply
Applying SSM Parameter Store parameters...
✓ Created /app/config/new-param
✓ Updated /app/config/database-url
✓ Deleted /app/config/old-param

Reset if needed:

# Unstage specific parameter
suve stage param reset /app/config/database-url

# Unstage all
suve stage reset --all

[!TIP] suve stage apply prompts for confirmation before applying. Use --yes to skip the prompt.

Save changes for later (export / import):

# Export staged changes to a directory as one file per service
# (param.json / secret.json); prompts for a passphrase.
# By default the working staging area is cleared; use --keep to retain it.
suve stage export ./backup

# Restore them into the working staging area later
suve stage import ./backup

# Export a single service to a specific file
suve stage param export ./param-backup.json

# Import a single service from a specific file
suve stage param import ./param-backup.json

[!NOTE] export writes the working area out wholesale (no merge). import prompts to Merge or Overwrite only when the working area already holds changes; pass --merge / --overwrite to choose non-interactively.

[!NOTE] See Staging State Transitions for detailed staging documentation.

Version Specification

Navigate versions with Git-like syntax.

AWS SSM Parameter Store

[!NOTE] SSM Parameter Store uses numeric version numbers (1, 2, 3, ...) that auto-increment on each update.

<name>[#VERSION][~SHIFT]*
where ~SHIFT = ~ | ~N  (repeatable, cumulative)

AWS Secrets Manager

[!NOTE] Secrets Manager uses UUID version IDs and staging labels instead of numeric versions. AWSCURRENT and AWSPREVIOUS are special labels automatically managed by AWS—AWSCURRENT always points to the latest version.

<name>[#VERSION | :LABEL][~SHIFT]*
where ~SHIFT = ~ | ~N  (repeatable, cumulative)

[!IMPORTANT] When specifying version-only syntax like '#3' or ':AWSPREVIOUS', you must use quotes to prevent shell interpretation of the # (comment) or : characters.

[!TIP] ~ without a number means ~1. You can chain them: ~~ = ~1~1 = ~2

Google Cloud Secret Manager

[!NOTE] Google Cloud Secret Manager uses integer version numbers (1, 2, 3, ...) plus the latest alias. There are no staging labels, so :LABEL syntax does not apply.

Azure Key Vault

[!NOTE] Azure Key Vault versions are opaque version IDs. There are no staging labels, so :LABEL syntax does not apply.

Azure App Configuration

[!NOTE] Azure App Configuration is unversioned. #, ~, and : are valid key characters — the whole argument is the literal key name, not a version spec — and log reports that history is unsupported.

Command Reference

Providers

Each backend lives under a provider group; the group names take aliases:

Group aliases are interchangeable with the group name (e.g. suve az kv show). Under azure stage, the secret / param subgroups take the same aliases as their read/write forms (kv / keyvault, appconfig / ac / appcfg).

Services

Each backend is a service under its provider group, with its own aliases:

Staging is the same for every backend — <group> stage (alias stg), i.e. aws stage, gcloud stage, azure stage.

Bare form: when exactly one backend is active for a service (see Provider selection), drop the group prefix — every alias still works. So suve param / suve ssm, suve secret / suve kv, suve stage / suve stg, … resolve to the uniquely-active backend.

Provider selection

Every backend has an explicit command group that is always available, regardless of environment:

suve aws param    ...  # AWS Parameter Store
suve aws secret   ...  # AWS Secrets Manager
suve aws stage    ...  # AWS staging
suve gcloud secret ... # Google Cloud Secret Manager
suve gcloud stage  ... # Google Cloud staging
suve azure secret  ... # Azure Key Vault
suve azure param   ... # Azure App Configuration
suve azure stage   ... # Azure staging (secret = Key Vault, param = App Configuration)

For convenience, suve also exposes bare top-level aliases — suve param, suve secret, suve stage — but only when the environment makes the target unambiguous. param, secret, and stage are each resolved independently. All backends support staging, so stage follows the same "exactly one active backend" rule (Azure is staging-active when either AZURE_KEYVAULT_NAME or AZURE_APPCONFIG_NAME is set):

1. A backend is active when its identifying environment variable is set:

   Backend	Active when set
   AWS	AWS_ACCESS_KEY_ID, AWS_VAULT, AWS_PROFILE, or an ambient-credential variable from AWS-managed compute (CloudShell / ECS / IRSA — see Cloud Shell support)
   Google Cloud	GOOGLE_CLOUD_PROJECT
   Azure Key Vault (secret)	AZURE_KEYVAULT_NAME
   Azure App Configuration (param)	AZURE_APPCONFIG_NAME

2. The bare alias for a service appears only when exactly one backend is active for it. Zero or two-plus active → no alias, use the explicit group. There is no priority order — ambiguity is never resolved silently.

3. AWS fallback: if no backend is active via env at all, AWS is accepted via ~/.aws/credentials (or $AWS_SHARED_CREDENTIALS_FILE). If that is also absent, there are no bare aliases.

Examples (— = alias not exposed):

suve --help lists which aliases are active in the current environment.

TUI mode

--tui launches a keyboard-driven terminal UI over the same use cases as the CLI and GUI. It is pure Go (no GTK/WebKit) and ships in every build. The provider and scope are fixed for the session at launch — switch provider by relaunching.

Launch forms:

suve --tui                 # only when exactly one provider is active (see Provider selection)
suve aws --tui             # explicit provider group (always available)
suve gcloud --tui
suve azure --tui
suve aws param --tui       # a service subgroup preselects that tab (Param / Secret)
suve azure secret --tui    # opens on the Key Vault tab

• Unique-provider rule: bare suve --tui follows the same detection as the bare aliases — it launches only when exactly one provider is active across the union of the param/secret/stage axes (AWS is also accepted via ~/.aws/credentials, or an ambient-credential variable in a cloud shell — see Cloud Shell support). With two or more active, it lists the explicit suve <group> --tui forms instead; there is no silent priority.
• Scope / env: the TUI consumes the same scope inputs as the CLI — GOOGLE_CLOUD_PROJECT for Google Cloud, --vault-name / AZURE_KEYVAULT_NAME and --store-name / AZURE_APPCONFIG_NAME (plus --namespace / AZURE_APPCONFIG_NAMESPACE) for Azure. AWS uses the ambient shared config.
• Azure tab gating: the Param (App Configuration) and Secret (Key Vault) tabs appear only for the services the launch scope resolves — set --vault-name for the Key Vault tab, --store-name for the App Configuration tab, either or both as needed. The Staging tab is always present.
• Shared staging area: staged edits made in the TUI use the same per-scope staging store as the CLI/GUI, so suve stage status sees them and stage apply from either side applies the same working set.
• The TUI adds no new commands and does not cover export/import (use the CLI/GUI for those). It requires an interactive terminal (a TTY on stdin and stdout).

Keymap (the in-app ? toggles full help, which is the source of truth):

JSON values are always pretty-printed automatically (parity with --parse-json), so there is no format toggle. Mutations are staged by default where the backend supports staging: completing a create, edit, or delete opens a Stage / Apply confirmation popup (←/→ choose, enter confirms, esc returns to the form); on a backend without staging the write is always immediate. Operation markers and unsupported controls follow each backend's capabilities. Rendering honors NO_COLOR and degrades gracefully on narrow terminals.

Cloud Shell support

suve runs in the browser-based cloud shells, with two environment-specific behaviors worth knowing.

Provider auto-selection. In AWS CloudShell, credentials are delivered through a container-credentials endpoint rather than AWS_ACCESS_KEY_ID / AWS_PROFILE or a ~/.aws/credentials file, so AWS is detected from the ambient-credential variables that AWS-managed compute sets:

Any of these marks AWS active for the bare param / secret / stage aliases (and bare suve --tui), exactly like AWS_PROFILE. Detection reads environment variables only — no network calls — so shell completion stays instant. Google Cloud Shell and Azure Cloud Shell auto-select through their existing variables (GOOGLE_CLOUD_PROJECT; AZURE_KEYVAULT_NAME / AZURE_APPCONFIG_NAME).

A bare EC2 instance profile delivers credentials only over IMDS, which sets no environment marker, so it is not auto-detected — use the explicit suve aws ... group there.

TUI rendering. The --tui renderer relies on a terminal scroll-region optimization that some browser terminals (notably CloudShell's xterm.js) mishandle, corrupting the display while scrolling. suve detects the known cloud shells — AWS_EXECUTION_ENV=CloudShell, CLOUD_SHELL=true (Google), AZUREPS_HOST_ENVIRONMENT=cloud-shell/… (Azure) — and forces a clean full repaint on scroll there (lists, history, value/diff panes, staging, dialogs, and the create/edit/tag forms), leaving native terminals on the fast path untouched. If you hit scroll corruption in another browser-based terminal, set SUVE_TUI_FULL_REPAINT=1 to opt into the same full-repaint behavior; resizing the terminal once also clears a corrupted frame.

Feature support

Read/write operations (show, log, diff, list, create, update, delete, tag, untag) are available on every backend, with these caveats: restore is available on AWS Secrets Manager and Azure Key Vault (soft-delete recovery); on Azure App Configuration log reports history unsupported and #/~/: are treated as literal key characters (not version specifiers). Only AWS Secrets Manager has staging labels (:AWSCURRENT etc.).

¹ App Configuration's PUT replaces the whole key-value, so tag writes are a GET-merge-PUT with an ETag precondition (azappconfig/v2): tag/untag preserve the value and other tags, and a value write (update) preserves existing tags.

² App Configuration is unversioned, so staging uses last-write-wins (no modified-after conflict check); tag/untag are available.

AWS SSM Parameter Store

Staging commands (under suve stage param):

AWS Secrets Manager

Staging commands (under suve stage secret):

Google Cloud Secret Manager

Uses integer version numbers (with the latest alias) and has no staging labels. Select the project with --project or the GOOGLE_CLOUD_PROJECT environment variable. Authentication uses Application Default Credentials (ADC). See docs/gcloud.md for details.

[!NOTE] Google Cloud Secret Manager calls key=value metadata "labels"; suve surfaces them under its cross-provider term tags (tag / untag). See Metadata terminology.

Staging commands (under suve gcloud stage; Google Cloud is secret-only, so staging operates on secrets directly):

Azure Key Vault

Secrets are versioned by opaque IDs and have no staging labels. Select the vault with --vault-name or the AZURE_KEYVAULT_NAME environment variable — the vault name is a globally-unique endpoint, so no subscription or resource group is needed. Authentication uses the DefaultAzureCredential chain (environment, managed identity, Azure CLI, ...). See docs/azure.md for details.

Staging commands (under suve azure stage secret):

Azure App Configuration

Unversioned key-value store. #, ~, and : are valid key characters — the whole argument is the literal key name, not a version spec — and log reports that history is unsupported. tag / untag are supported via a GET-merge-PUT (see footnote ¹). Select the store with --store-name or the AZURE_APPCONFIG_NAME environment variable — the store name is a globally-unique endpoint, so no subscription or resource group is needed. See docs/azure.md for details.

Namespaces

App Configuration addresses a setting by (key, label). This label axis is an identity dimension — a flat partition of the key space, like a Kubernetes namespace — not key=value metadata. Because "label" almost everywhere else means metadata (which suve unifies as tags), suve calls this axis a namespace; Azure App Configuration calls it a "label".

Select the namespace with --namespace (alias --ns) or the AZURE_APPCONFIG_NAMESPACE environment variable (precedence: flag > env > default). The default is the null namespace (App Configuration's unlabeled/default settings); a dev namespace never surfaces prod settings in list/show.

The value is interpreted by context:

• List/read (list, show) forward the value to App Configuration's label filter, so * (all), dev* (prefix), and dev,prod (OR-list) work natively; an empty value maps to the null-namespace filter.
• Single-item ops (show, create, update, delete, staging) need exactly one namespace: \ escapes are decoded, and any unescaped * or , is a usage error (it names all/multiple namespaces). This is also how you address a namespace literally named * / , / \ — e.g. --namespace "\*".
• The namespace is a separate flag/env channel; the positional argument stays the whole key, so colon keys like Logging:LogLevel:Default are unaffected. The filter grammar (* , \) lives only inside the --namespace value.

Staging commands (under suve azure stage param; unversioned → last-write-wins, no tag/untag):

Aggregate stage commands

suve stage <command> (and suve <backend> stage <command>) operate across every service of the active backend — AWS Parameter Store + Secrets Manager, or Azure Key Vault + App Configuration (Google Cloud is secret-only). The backend is resolved by the same provider selection rules, and a backend that is not configured is skipped.

Export / Import Commands

Export writes the working staging area out to portable snapshot files (one per service) and import reads them back. Each file is a plaintext JSON envelope ({version, provider, scope, service, payload}) whose payload is passphrase-encrypted (Argon2id) or plaintext when the passphrase is empty. The full scope is embedded and validated on import.

• export writes the working area out wholesale; there is no --merge / --overwrite. By default it clears the working staging area; --keep retains it. --yes / --force skip the overwrite confirmation.
• Directory export is not atomic across files. suve stage export <dir> writes param.json and secret.json as separate files. If the first write succeeds and the second fails (for example a full disk or a permissions error), the command aborts with an error and leaves a partial directory — a freshly written param.json alongside a stale or missing secret.json. Your working staging area is never touched, so no staged changes are lost; just re-run the export once the underlying problem is resolved and it overwrites the directory cleanly. Because each snapshot file embeds and validates its own scope on import, a later stage import <dir> restores whatever files are present per service without silently merging a mismatched pair; still, avoid importing a directory left behind by a failed export.
• import has no --keep (it is read-only on the file). --merge / --overwrite are mutually exclusive and only matter when the working area already holds changes; otherwise the file is applied directly. --allow-scope-mismatch imports even when the file's embedded scope differs from the current scope.

Environment Variables

Providers

Each backend is selected and authenticated from its own environment variables (all also settable via flags; see Provider selection).

AWS

Google Cloud

Azure

Authentication uses the DefaultAzureCredential chain (az login, environment, managed identity, ...). The Key Vault / App Configuration name is a globally-unique endpoint, so no subscription or resource group is needed.

Timezone

suve respects the TZ environment variable for date/time formatting:

# Show times in UTC
TZ=UTC suve param show /app/config

# Show times in Japan Standard Time
TZ=Asia/Tokyo suve param show /app/config

All timestamps are formatted in RFC3339 format with the local timezone offset applied. If TZ is not set, the system's local timezone is used. Invalid timezone values fall back to UTC.

General

Debugging

Pass the global --debug flag (or set SUVE_DEBUG=1) to trace what suve is doing on stderr. This is designed for the "command produces empty or unexpected output" case: it shows the decisions suve made before calling any API, the effective cloud configuration, each SDK request/response, and how many results each step produced:

suve secret ls --debug          # flag works in any position
SUVE_DEBUG=1 suve secret ls      # or via environment

Each entry starts with a [suve debug <time>] prefix (multi-line HTTP dumps are prefixed on their first line). The output includes:

• CLI decisions — the suve version and which provider each flat alias (param / secret / stage) resolved to.
• Effective configuration — for AWS, the resolved region, profile, and credentials source (the usual suspects when a listing is unexpectedly empty); for Google Cloud, the queried projects/... parent; for Azure, the credential the DefaultAzureCredential chain selected.
• SDK requests/responses — AWS HTTP request/response dumps (bodyless) with retries, gRPC calls with resource paths and durations for Google Cloud, and azcore request/response/retry/authentication events for Azure.
• Result counts — items returned per API page, and how many names survived the client-side prefix/regex filters, so "the API returned nothing" and "my filter dropped everything" are distinguishable.

Only request/response metadata is printed — secret values are never logged: AWS uses the bodyless log modes, and because the dump is taken after request signing, suve shows only an allowlist of non-sensitive headers (Host, X-Amz-Target, request IDs, …) and redacts every other header value — so the signing Authorization header, the session token, and any future credential-bearing header fail closed rather than leaking. The gRPC interceptor never prints request/reply messages; azcore redacts headers outside its own allowlist and never logs bodies (error events may include the service's error document, the same text normal error output already shows). Debug output goes to stderr, so it never contaminates piped stdout.

Unredacted output (--no-redaction)

When the redacted default hides too much — e.g. you need to see the exact secret value a request returned, or the raw payload of a failing call — add --no-redaction (or set SUVE_NO_REDACTION=1) alongside --debug:

suve secret show my-secret --debug --no-redaction

This switches AWS to the with-body log modes and stops masking headers, and turns on azcore body logging for Azure, so full request/response bodies and credentials — including secret values and the signing Authorization header — are written to stderr. Use it only for deliberate, local debugging and never where the log could be captured or shared; a one-line warning is printed to stderr whenever it is active. It has no effect without --debug (you'll get a hint saying so), and no effect on Google Cloud, whose gRPC interceptor logs no message bodies at all.

Staging

AWS Configuration

suve uses standard AWS SDK configuration:

Authentication (in order of precedence):

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. Shared credentials file (~/.aws/credentials) and config (~/.aws/config)
   • Use AWS_PROFILE to specify which profile to load (default: default)
3. IAM role (EC2, ECS, Lambda)

Region:

• AWS_REGION or AWS_DEFAULT_REGION environment variable
• ~/.aws/config file

[!WARNING] Ensure your IAM role/user has appropriate permissions:

• SSM: ssm:GetParameter, ssm:GetParameters, ssm:GetParameterHistory, ssm:PutParameter, ssm:DeleteParameter, ssm:DescribeParameters, ssm:AddTagsToResource, ssm:RemoveTagsFromResource
• SM: secretsmanager:GetSecretValue, secretsmanager:ListSecretVersionIds, secretsmanager:ListSecrets, secretsmanager:CreateSecret, secretsmanager:PutSecretValue, secretsmanager:UpdateSecret, secretsmanager:DeleteSecret, secretsmanager:RestoreSecret, secretsmanager:TagResource, secretsmanager:UntagResource

[!NOTE] The gcloud and azure commands use their own credential chains: Google Cloud uses Application Default Credentials (ADC), and Azure uses DefaultAzureCredential (environment, managed identity, Azure CLI, ...). See docs/gcloud.md and docs/azure.md for details.

Development

# Run tests
mise test

# Run linter
mise lint

# Build CLI (without GUI)
mise build-cli

# Build with GUI support — builds the frontend first, then embeds it into
# bin/suve. (A bare `go build -tags production` skips the frontend build, so the
# binary aborts at `suve --gui` with "no index.html could be found".)
mise build-gui

# Run E2E tests (requires Docker)
mise e2e-aws

# Coverage (unit + E2E combined)
mise coverage-all

Local Development with Emulators

mise run bash starts the selected cloud's emulator(s) and opens a shell with the right environment injected, so suve (and suve --gui) talk to the local emulators and auto-detect the active provider. Flags combine freely (0–4):

mise run bash --aws               # AWS (localstack: SSM + Secrets Manager)
mise run bash --gcloud            # Google Cloud Secret Manager
mise run bash --azure-appconfig   # Azure App Configuration
mise run bash --azure-keyvault    # Azure Key Vault
mise run bash --azure             # both Azure services
mise run bash --aws --gcloud --azure   # everything at once

# inside the shell:
suve --gui        # auto-detects the active provider
suve param ls
suve secret list

Containers keep running after you exit the shell; stop them with docker compose down (or mise run clean).

Every cloud is behind a docker compose profile (aws / gcloud / azure), so nothing starts by default. To drive the AWS emulator manually instead of the shell above:

SUVE_LOCALSTACK_EXTERNAL_PORT=4566 docker compose --profile aws up -d
AWS_ENDPOINT_URL=http://127.0.0.1:4566 \
AWS_ACCESS_KEY_ID=dummy \
AWS_SECRET_ACCESS_KEY=dummy \
AWS_DEFAULT_REGION=us-east-1 \
suve param ls
docker compose down

[!IMPORTANT] Dummy credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) are required to prevent the SDK from attempting IAM role credential fetching. The mise run bash --aws shell sets these for you.

License

MIT License