Using CLI

Note

The examples in this section use AWS Parameter Store and Secrets Manager through the bare suve param / suve stage aliases. Those aliases exist only when AWS is the only active backend for the service (see Bare Aliases). Otherwise, use the explicit group, such as suve aws param show. See Google Cloud and Azure for those backends.

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 Stage Lifecycle.

Tip

Staged values live in encrypted files under ~/.suve/staging/. Use suve stage export to write them to portable snapshot files and suve stage import to restore them later. See Export / Import Commands for the forms each backend supports.

1. Stage changes (takes the value as an argument or from stdin with --value-stdin, or opens an editor in a terminal):

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 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 Parameter Store...
✓ Parameter Store: Created /app/config/new-param
✓ Parameter Store: Updated /app/config/database-url
✓ Parameter Store: 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

Important

The directory form (suve stage export <dir> / suve stage import <dir>) is AWS-only. On Azure, export and import each service to its own file (suve stage secret export <file>, suve stage param export <file>). Google Cloud is secret-only, so suve stage export <file> exports its one service.

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 Stage Lifecycle for detailed staging documentation.