suve

Secret Unified Versioning Explorer

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

A Git-like CLI/GUI for AWS Parameter Store and Secrets Manager. Familiar commands like show, log, diff, and a staging workflow for safe, reviewable changes.

Features

• Git-like commands: show, log, diff, ls, tag, stash
• Staging workflow: edit → status → diff → apply (review changes before applying)
• Version navigation: #VERSION, ~SHIFT, :LABEL syntax
• Colored diff output: Easy-to-read unified diff format
• Both services: SSM Parameter Store and Secrets Manager
• Secure staging: In-memory daemon with mlock, encrypted stash (Argon2 + AES-GCM)
• GUI mode: Desktop application via --gui flag (built with Wails)

Installation

Using Homebrew (macOS/Linux)

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

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

[!NOTE] On Linux, suve requires GTK3 and WebKit2GTK for GUI support. Use suve-cli if you only need CLI functionality.

Using Scoop (Windows)

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

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

# CLI-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 + 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"

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

# CLI-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 + 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"

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

# 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

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

make build
# Binary: bin/suve

go install github.com/wailsapp/wails/v2/cmd/wails@latest
cd gui && wails build -tags production -skipbindings
# Binary: gui/build/bin/gui

cd gui && wails build -tags production,webkit2_41 -skipbindings

[!TIP] Using with aws-vault: Wrap commands with aws-vault exec for temporary credentials:

aws-vault exec my-profile -- suve param show /my/param

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 and Staging Agent/Daemon.

[!TIP] Staged values are stored in secure memory (daemon process). Use suve stage stash to save changes to an encrypted file for later restoration.

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 (stash):

# Save staged changes to file (prompts for passphrase)
suve stage stash

# Restore from file
suve stage stash pop

# Preview stashed changes
suve stage stash show

# Delete stash without restoring
suve stage stash drop

[!NOTE] See Staging Agent/Daemon for detailed stash command documentation.

Version Specification

Navigate versions with Git-like syntax.

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)

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

Command Reference

Services

SSM Parameter Store

Staging commands (under suve stage param):

Secrets Manager

Staging commands (under suve stage secret):

Global Stage Commands

Stash Commands

Agent Commands

[!NOTE] See Staging Agent/Daemon for detailed documentation on daemon architecture and stash commands.

Environment Variables

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.

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

Development

# Run tests
make test

# Run linter
make lint

# Build CLI (without GUI)
make build

# Build with GUI support
go build -tags production -o bin/suve ./cmd/suve

# Run E2E tests (requires Docker)
make e2e

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

Local Development with Localstack

To test against localstack instead of real AWS:

# Start localstack
SUVE_LOCALSTACK_EXTERNAL_PORT=4566 docker compose up -d

# Run commands with localstack
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

# GUI with localstack
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 --gui

# Stop localstack
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.

License

MIT License