Command Reference

Command Reference

Complete reference for all rsenv commands.

Global Options

rsenv [OPTIONS] <COMMAND>

Option	Description
-v, --verbose	Enable verbose output
-C, --project-dir <PATH>	Context directory (see note below)
--version	Show version
--help	Show help

Note on -C: -C always specifies the project directory. Use --vault-base for global operations to override the vaults directory.

Vault Requirements

Some commands require an initialized vault (rsenv init vault), while others work standalone with just .env files.

Standalone Commands (No Vault Required)

Command	Description
env build	Build environment from hierarchy
env envrc	Write to .envrc (requires rsenv section)
env tree	Show environment tree
env select	Interactive environment selection
env files	List files in hierarchy
env link	Link parent-child files
env unlink	Remove parent link
env leaves	List leaf files
env branches	Show all branches
env edit	Edit environment file
env edit-leaf	Edit leaf and parents
env tree-edit	Side-by-side editing
init vault	Create new vault
config show	Show merged configuration
config path	Show config file paths
config init --global	Create global config
config edit --global	Edit global config
sops * --global	All sops commands with --global flag
completion	Generate shell completions

Commands Requiring Vault

Command	Description
guard add	Guard a file (move to vault)
guard list	List guarded files
guard restore	Restore guarded file
swap init	Initialize file for swapping
swap in	Swap files in
swap out	Swap files out
swap delete	Delete swap configuration
sops encrypt	Encrypt vault files (without --global)
sops decrypt	Decrypt vault files (without --global)
sops clean	Clean plaintext files (without --global)
sops status	Encryption status (without --global)
config edit	Edit vault config (without --global)
info	Show project/vault status
init reset	Reset (restore files, remove symlink)
init reconnect	Reconnect to existing vault

Note: swap status and swap out --global gracefully return empty results if no vault is found.

init

Initialize and manage vault for a project.

rsenv init <COMMAND>

Command	Description
vault	Create vault for project
reset	Undo init: restore files, remove .envrc symlink
reconnect	Reconnect project to existing vault

init vault

Create a vault for a project.

rsenv init vault [OPTIONS] [PROJECT]

Argument	Description
PROJECT	Project directory (defaults to current)

Option	Description
--absolute	Use absolute paths for symlinks (default: relative)

Examples:

rsenv init vault
rsenv init vault ~/myproject
rsenv init vault --absolute

init reset

Undo initialization: restore guarded files, remove .envrc symlink.

rsenv init reset [PROJECT]

Argument	Description
PROJECT	Project directory (defaults to current)

Note: The vault directory is NOT deleted.

init reconnect

Reconnect a project to an existing vault (re-create .envrc symlink).

rsenv init reconnect <ENVRC_PATH>

Argument	Description
ENVRC_PATH	Path to the dot.envrc file in the vault

Example:

rsenv init reconnect ~/.rsenv/vaults/myproject-abc123/dot.envrc

env

Environment variable hierarchy management.

env build

Build hierarchical environment variables.

rsenv env build <FILE>

Argument	Description
FILE	Leaf env file to build from

Example:

rsenv env build $RSENV_VAULT/envs/local.env
source <(rsenv env build local.env)

env envrc

Write environment to .envrc file (direnv integration).

rsenv env envrc <FILE> [OPTIONS]

Argument	Description
FILE	Leaf env file to build from

Option	Description
-e, --envrc <PATH>	Target .envrc file (default: ./.envrc)

env files

List all files in environment hierarchy.

rsenv env files <FILE>

env select

Interactively select an environment (fuzzy finder).

rsenv env select [DIR]

Argument	Description
DIR	Directory to search for env files

env tree

Show environment hierarchy as tree.

rsenv env tree [DIR]

env branches

Show all branches (linear representation).

rsenv env branches [DIR]

env edit

Edit an environment file (FZF select).

rsenv env edit [DIR]

env edit-leaf

Edit a leaf file and all its parents.

rsenv env edit-leaf <FILE>

env tree-edit

Edit all environment hierarchies side-by-side.

rsenv env tree-edit [DIR]

env leaves

List all leaf environment files.

rsenv env leaves [DIR]

env link

Link parent-child env files.

rsenv env link <FILES>...

Argument	Description
FILES	Files to link (first is root, each subsequent links to previous)

Examples:

# Link parent to child
rsenv env link base.env local.env

# Create chain: root <- middle <- leaf
rsenv env link base.env cloud.env prod.env

env unlink

Remove parent link from env file.

rsenv env unlink <FILE>

guard

Guard sensitive files (symlink to vault).

guard add

Add a file to guard (move to vault, create symlink).

rsenv guard add <FILE> [OPTIONS]

Argument	Description
FILE	File to guard

Option	Description
--absolute	Use absolute paths for symlinks

guard list

List guarded files.

rsenv guard list

guard restore

Restore a guarded file from vault.

rsenv guard restore <FILE>

Argument	Description
FILE	File to restore

swap

Swap files in/out between project and vault.

Scope Levels

Scope	Command	Description
Vault	swap out	All files in current project's vault (default)
File	swap out <files>	Operate on specific files
Global	swap out --global	All vaults under base_dir/vaults

swap init

Initialize: move project files to vault (first-time setup).

rsenv swap init <FILES>...

swap in

Swap files in (replace with vault versions).

rsenv swap in <FILES>...

swap out

Swap files out (restore originals).

rsenv swap out [OPTIONS] [FILES]...

Argument	Description
FILES	Files to swap out (if empty, swaps out all files in current vault)

Option	Description
-g, --global	Swap out all vaults
--vault-base <PATH>	Override vaults directory (requires --global)

Examples:

# Vault-level (default, like sops)
rsenv swap out

# File-level
rsenv swap out config.yml docker-compose.yml

# Global (all vaults)
rsenv swap out --global

# Global with custom vault base
rsenv swap out --global --vault-base ~/my-rsenv/vaults

swap status

Show swap status.

rsenv swap status [OPTIONS]

Option	Description
--absolute	Show absolute paths (default: relative)
-g, --global	Show status across all vaults
-s, --silent	Exit code only: 0=clean, 1=has active swaps (requires --global)
--vault-base <PATH>	Override vaults directory (requires --global)

Examples:

# Project status
rsenv swap status

# Global status
rsenv swap status --global

# Script-friendly check
rsenv swap status --global --silent && echo "All clean"

swap delete

Delete swap files from vault (remove override + backup).

rsenv swap delete <FILES>...

Argument	Description
FILES	Files to delete from swap management

Safety: Refuses if any file is currently swapped in. All-or-nothing validation prevents partial deletions.

sops

SOPS encryption/decryption.

Scope Levels

Scope	Command	Description
File	sops encrypt <file>	Encrypt/decrypt single file
Vault	sops encrypt	All matching files in current vault
Global	sops encrypt --global	All vaults under base_dir/vaults

sops encrypt

Encrypt files matching config patterns (or single file).

rsenv sops encrypt [OPTIONS] [FILE]

Argument	Description
FILE	Single file to encrypt (optional)

Option	Description
-d, --dir <PATH>	Directory to encrypt
-g, --global	Encrypt all vaults
--vault-base <PATH>	Override vaults directory (requires --global)

Examples:

# Single file
rsenv sops encrypt secrets.env

# Project vault (default)
rsenv sops encrypt

# All vaults
rsenv sops encrypt --global

sops decrypt

Decrypt .enc files (or single file).

rsenv sops decrypt [OPTIONS] [FILE]

Argument	Description
FILE	Single file to decrypt (optional)

Option	Description
-d, --dir <PATH>	Directory to decrypt
-g, --global	Decrypt all vaults
--vault-base <PATH>	Override vaults directory (requires --global)

sops clean

Delete plaintext files matching encryption patterns.

rsenv sops clean [OPTIONS]

Option	Description
-d, --dir <PATH>	Directory to clean
-g, --global	Clean all vaults
--vault-base <PATH>	Override vaults directory (requires --global)

Without options: cleans project's vault only.

sops status

Show encryption status.

rsenv sops status [OPTIONS]

Option	Description
-d, --dir <PATH>	Directory to check
-g, --global	Check all vaults
--check	Exit with code 1 if files need encryption (for scripting/hooks)
--vault-base <PATH>	Override vaults directory (requires --global)

Without options: shows status for project's vault only.

Status categories:

• pending_encrypt: Plaintext without encrypted version
• stale: Encrypted exists but hash differs (modified since encryption)
• current: Encrypted with matching hash (up-to-date)
• orphaned: Encrypted without plaintext

sops gitignore-sync

Sync .gitignore with configured encryption patterns.

rsenv sops gitignore-sync [OPTIONS]

Option	Description
-y, --yes	Skip confirmation prompt
--global	Sync global gitignore only

Without options: syncs per-vault gitignore only (requires vault).

sops gitignore-status

Show gitignore sync status.

rsenv sops gitignore-status [OPTIONS]

Option	Description
--global	Show global gitignore status only

Without options: shows per-vault gitignore status only (requires vault).

sops gitignore-clean

Remove rsenv-managed section from .gitignore.

rsenv sops gitignore-clean [OPTIONS]

Option	Description
--global	Clean global gitignore only

Without options: cleans per-vault gitignore only (requires vault).

hook

Git pre-commit hook management to prevent committing with unencrypted files.

hook install

Install pre-commit hook in a git repository.

rsenv hook install [OPTIONS]

Option	Description
--dir <PATH>	Target git repo (default: base_dir)
-f, --force	Force overwrite if hook exists

Default location: base_dir (typically ~/.rsenv).

hook remove

Remove rsenv pre-commit hook.

rsenv hook remove [OPTIONS]

Option	Description
--dir <PATH>	Target git repo (default: base_dir)

Safety: Only removes hooks installed by rsenv (checks for rsenv signature).

hook status

Show hook installation status.

rsenv hook status [OPTIONS]

Option	Description
--dir <PATH>	Target git repo (default: base_dir)

config

Configuration management.

config show

Show effective configuration.

rsenv config show

config init

Create template config file.

rsenv config init [OPTIONS]

Option	Description
-g, --global	Create global config (~/.config/rsenv/rsenv.toml)

Without --global: creates config in project's vault directory.

config edit

Edit configuration in editor.

rsenv config edit [OPTIONS]

Option	Description
-g, --global	Edit global config (~/.config/rsenv/rsenv.toml)

Without --global: edits vault-local config (requires initialized vault). Creates template if config doesn't exist. After editing, automatically syncs gitignore patterns.

config path

Show config file paths.

rsenv config path

info

Show project and vault status.

rsenv info

Options

Option	Description
--check	Silent mode: exit code only (0=valid vault, 1=no/invalid vault)

Scripting

Use --check for shell scripts and CI:

if rsenv info --check 2>/dev/null; then
    echo "Valid vault found"
else
    echo "No vault or invalid vault"
fi

completion

Generate shell completions.

rsenv completion <SHELL>

Argument	Values
SHELL	bash, zsh, fish, powershell, elvish

Examples:

rsenv completion bash > ~/.local/share/bash-completion/completions/rsenv
rsenv completion zsh > ~/.zfunc/_rsenv
rsenv completion fish > ~/.config/fish/completions/rsenv.fish

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
64	Usage error
65	Data error
66	No input
74	I/O error
78	Configuration error

Environment Variables

Variable	Description
RSENV_VAULT	Path to current project's vault (set by rsenv)
RSENV_SWAPPED	Set to 1 when files are swapped in (managed by rsenv)
RSENV_BASE_DIR	Override base directory
RSENV_EDITOR	Override editor
RSENV_SOPS__GPG_KEY	Override SOPS GPG key

See Configuration for all environment variables.