Vault Command

The vault command provides secure encrypted storage for sensitive data like API keys, credentials, and passwords.

Overview

Rumour Vault uses AES-256-GCM encryption to securely store secrets. All secrets are encrypted using a key derived from a master password via Argon2 before being saved to disk at ~/.rumour/vault.enc.

Actions

The vault command supports three subcommands:

Subcommand	Description
set	Store or update a secret
get	Retrieve and decrypt a stored secret
list	List all stored secret keys

Set a Secret

Store a new secret or overwrite an existing one:

rumour vault set <KEY> <VALUE> [OPTIONS]

• <KEY> — The name of the secret (e.g., github_token).
• <VALUE> — The sensitive value to encrypt.

If the master password is not passed via options or the environment, you will be prompted for it interactively.

Example 1 — Set a New Secret (Interactive Password Prompt)

Use this when you want to enter the master password securely without typing it in plain text on the command line.

rumour vault set github_token "ghp_xxxxxxxxxxxx"

When the key does not yet exist in the vault, you'll be prompted once for the master password:

Vault Master Password: [hidden input]
PASS Secret 'github_token' stored in vault.

What happens:

• If the vault file doesn't exist yet (~/.rumour/vault.enc), it is created and a random salt is generated.
• The value is encrypted using AES-256-GCM with a key derived from your master password via Argon2.
• The encrypted ciphertext is written to ~/.rumour/vault.enc.

Example 2 — Set with Inline Master Password (-p)

Use this to supply the master password non-interactively, useful in scripts or when the password is already in a variable.

rumour vault set github_token "ghp_xxxxxxxxxxxx" -p "my-master-password"

Output:

PASS Secret 'github_token' stored in vault.

What happens:

• The -p flag bypasses the interactive password prompt entirely.
• If RUMOUR_VAULT_PASS is also set in your environment, -p takes precedence over it.

Example 3 — Overwrite an Existing Key Without Confirmation (-y)

If the key already exists in the vault, Rumour will prompt you to confirm the overwrite. The -y flag skips this confirmation.

# Without -y: Rumour prompts for confirmation
rumour vault set github_token "ghp_NEW_VALUE" -p "my-master-password"

Secret 'github_token' already exists. Overwrite? [y/N] N
Aborted.

# With -y: skips the confirmation prompt entirely
rumour vault set github_token "ghp_NEW_VALUE" -p "my-master-password" -y

Output:

PASS Secret 'github_token' stored in vault.

What happens:

• Without -y, Rumour detects the key already exists and asks for confirmation (default is No).
• With -y, the overwrite proceeds immediately with no prompt.

Get a Secret

Retrieve and decrypt a stored secret by name:

rumour vault get <KEY> [OPTIONS]

• <KEY> — The name of the secret to retrieve.

If the master password is not passed via -p or the RUMOUR_VAULT_PASS environment variable, you will be prompted for it interactively.

Example 1 — Get Interactively (Interactive Password Prompt)

Use this when you want to enter the master password securely at runtime without exposing it in the command line.

rumour vault get github_token

You'll be prompted for the master password:

Vault Master Password: [hidden input]
ghp_UPDATED_xxxxxxxxxxxx

What happens:

• Rumour reads ~/.rumour/vault.enc, decrypts the stored ciphertext using your master password, and prints the plaintext value to stdout.
• The output is the raw secret value — ready to be piped or captured by scripts.

Example 2 — Get with Inline Master Password (-p)

Supply the master password non-interactively to avoid the prompt.

rumour vault get github_token -p "my-master-password"

Output:

ghp_UPDATED_xxxxxxxxxxxx

What happens:

• The -p flag bypasses the interactive prompt entirely.
• If RUMOUR_VAULT_PASS is also set in the environment, -p takes precedence over it.

Example 3 — Get Using Environment Variable

You can also supply the master password via the RUMOUR_VAULT_PASS environment variable. This is the recommended approach for scripting and CI/CD pipelines.

RUMOUR_VAULT_PASS="my-master-password" rumour vault get github_token

Output:

ghp_UPDATED_xxxxxxxxxxxx

What happens:

• Rumour automatically reads RUMOUR_VAULT_PASS from the environment when neither the -p flag is provided nor an interactive terminal is available.
• The value is printed to stdout on a single line, making it easy to capture with $(...) in shell scripts.

Error Cases

Wrong password:

rumour vault get github_token -p "WRONG_PASSWORD"

FAIL Failed to retrieve secret: Decryption failed (check password): aead::Error

Key not found:

rumour vault get nonexistent_key -p "my-master-password"

FAIL Failed to retrieve secret: Secret 'nonexistent_key' not found

---

List Secrets

List all stored secret keys (without revealing their values):

rumour vault list [OPTIONS]

[!NOTE] vault list only shows key names — not their decrypted values. This is safe to run even in shared terminal sessions.

Example 1 — List Interactively (Interactive Password Prompt)

rumour vault list

You'll be prompted for the master password, then your keys are displayed:

Vault Master Password: [hidden input]
--- VAULT SECRETS ---
github_token
api_key
db_password

What happens:

• Rumour reads the vault file and lists all stored key names.
• Values are never decrypted or printed during a list operation.

Example 2 — List with Inline Master Password (-p)

Use -p to supply the password non-interactively:

rumour vault list -p "my-master-password"

Output:

--- VAULT SECRETS ---
github_token
api_key
DB_PASS
SECURE_KEY
another_token

What happens:

• The -p flag bypasses the interactive prompt.
• Keys are listed in the order they appear in the vault file (insertion order is not guaranteed to be sorted).

Example 3 — List Using Environment Variable

RUMOUR_VAULT_PASS="my-master-password" rumour vault list

Output:

--- VAULT SECRETS ---
github_token
api_key
DB_PASS
SECURE_KEY
another_token

What happens:

• Same as -p but the password is read from RUMOUR_VAULT_PASS.
• This form is ideal in shell scripts and CI pipelines where you'd rather not pass the password as an argument on the same line as the command.

Command Options

These options apply to the subcommands above:

Option	Short	Description
--password	p	Master password (overrides RUMOUR_VAULT_PASS env)
--yes	y	Auto-confirm key overwrite (only applicable to set)

Variable Resolution in Workflows

To use vault secrets in your request files, reference them using the vault. prefix:

1. In Request TOML Files

Reference the secret directly in the URL, headers, or body using the double-braces syntax:

[request]
url = "https://api.github.com/user"
headers = { Authorization = "Bearer {{vault.github_token}}" }

[!IMPORTANT] Always use a dot (.) to reference vault keys (e.g., {{vault.github_token}}). The colon syntax ({{vault:github_token}}) is not supported.

2. In Environment Files (.env.toml)

You can map vault secrets into environment variables for clean environments configuration:

workspace.env.toml

# Root level configuration
base_url = "https://api.example.com"
github_token = "{{vault.github_token}}"

# Or inside the [variables] block
[variables]
db_password = "{{vault.prod_db_pass}}"

[!NOTE] Rumour uses recursive variable resolution (up to 3 levels deep). When a request references {{github_token}}, it resolves it to {{vault.github_token}}, which is then automatically decrypted using your vault password.

Running with Vault Secrets

When executing workflows (via rumour run or rumour watch) that reference vault variables, the Rumour execution engine must be able to decrypt the vault. You must provide the master password via the RUMOUR_VAULT_PASS environment variable.

You can supply this environment variable in two ways:

1. Prefixed Inline Command (Recommended for one-off runs)

Pass the environment variable directly on the command line preceding the execution. This avoids keeping the password in your shell's history:

RUMOUR_VAULT_PASS="mypassword123" rumour run requests/01_get.toml -tv

2. Exported Session Variable (Convenient for watch/development loops)

Export the variable in your current terminal session so that subsequent commands automatically pick it up:

# Export the password
export RUMOUR_VAULT_PASS="mypassword123"

# Run or watch normally without prefixing
rumour run requests/
rumour watch requests/

If RUMOUR_VAULT_PASS is not set or is incorrect, the engine will fail to resolve the vault keys, treating them as empty or throwing resolution errors.

Security Details

Aspect	Technical Details
Encryption Algorithm	AES-256-GCM (Authenticated Encryption with Associated Data)
Key Derivation Function	Argon2id
Salt	Randomly generated per vault on initialization
Storage Location	~/.rumour/vault.enc

Troubleshooting

"Decryption failed (check password)"

The master password provided is incorrect or the vault file is corrupted. Double-check your password:

rumour vault get github_token
Vault Master Password: ****************
FAIL Failed to retrieve secret: Decryption failed (check password)

Resetting the Vault

If you forget your master password and need to start fresh (deleting all existing secrets):

# Delete the encrypted vault file
rm ~/.rumour/vault.enc

# Create a new secret (this initializes a fresh vault with your new password)
rumour vault set first_key "value"