Command Line Guide

1. Overview

cipherpaths is a command-line front end for the same portable encryption core used by the CipherPaths Windows GUI (see the Users Guide). It reads and writes the exact same vault format, so a vault can be opened with either tool interchangeably — create it in the GUI and script it from the CLI, or the other way around.

The CLI has no separate --flag-style options. Instead it works like git or docker: a single executable, one command word (init, ls, setpw, …), then positional arguments. Every command below is documented in full in the quick reference table.

• Same source file builds unmodified for Windows and Linux (x86_64 / ARM64) — no per-platform CLI code.
• Every command that touches a vault unlocks it first — a deliberately slow, memory-hard Argon2id derivation designed to resist password brute-forcing.
• Two ways to run commands: single-shot (one process, one unlock, per command) or interactive (unlock once, run many commands) — see Interactive mode.

2. Getting the CLI

Download the CLI from the Download page — one ZIP with Windows builds (x64 and ARM64) and a Linux build (x64); macOS is under consideration. Each platform's folder in the ZIP also includes runnable example scripts (demo-vault.cmd/demo-vault-interactive.ps1 for Windows, demo-vault.sh/demo-vault-interactive.sh for Linux) that walk through creating a vault, adding several sites, and reading everything back — in both single-shot and interactive style — more extensive than the short snippets on this page, and a good starting point to copy and adapt.

The executable is named cipherpaths.exe on Windows and cipherpaths on Linux. Confirm it runs with:

cipherpaths version
# cipherpaths-cli 0.9.3 (OpenSSL 3.5.5 ...)

Running the executable with no arguments prints the same command list as the quick reference below.

System requirements

3. Quick reference

Every command, straight from cipherpaths's own built-in help. <angle-bracket> arguments are required, [square-bracket] arguments are optional, and a|b means "one of a or b".

4. Vaults & the master password

A vault is an ordinary folder; init creates one and prints a recovery key exactly once — write it down, it cannot be shown again (see the Users Guide's recovery key section). Every other command needs the master password to unlock the vault first, either typed at a prompt or supplied via an environment variable.

cipherpaths init ./myvault
# Create master password: ********
# Password strength: Strong
# ==================== RECOVERY KEY ====================
# XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
# ========================================================

5. Browsing & files

Logical paths inside a vault always start with / and mirror the folder structure you'd see in the GUI. Any account (or sub-folder) can also hold encrypted files, not just a credential:

cipherpaths mkdir ./myvault /Taxes/2025
cipherpaths add ./myvault /Taxes/2025 ./payslip.pdf
cipherpaths ls ./myvault /Taxes/2025

Bring a file back out to plaintext with export, or print a text file straight to the terminal with cat:

cipherpaths export ./myvault /Taxes/2025/payslip.pdf ./restored
cipherpaths cat ./myvault /Taxes/2025/notes.txt

6. Credentials, notes & search

setpw creates the top-level folder automatically if it doesn't exist yet, tagged as a web-login record — no mkdir needed first:

cipherpaths setpw ./myvault /GitHub https://github.com/login me@example.com 'Tr0ub4dor&3' totp
cipherpaths getpw ./myvault /GitHub

Attach a note to the same folder, and search across every decrypted field in the vault:

cipherpaths note ./myvault /GitHub "Recovery codes are printed and stored in the safe."
cipherpaths search ./myvault github

setcc (credit card) and setcontact (contact details) work the same way with their own field lists — see the quick reference for the full argument order.

7. Secrets: environment variables & the "-" prompt

Typing a password directly as a command-line argument puts it in your shell history and makes it visible to other processes on the machine (e.g. ps -ef on Linux, or anything reading /proc/<pid>/environ). The CLI gives you two ways around that:

• Pass - in place of any password / card-number / CVV argument to be prompted for it interactively instead, with the terminal echo suppressed.
• Set an environment variable so the master password isn't typed at all — useful for scripting, at the cost of the value being readable from the process environment while the script runs.

cipherpaths setpw ./myvault /Bank https://bank.example jsmith -
# Password: ****************

8. Interactive mode (open)

Every command in the quick reference re-unlocks the vault from scratch and exits — fine for one-off use, but each unlock is a deliberately expensive Argon2id derivation, so a script issuing many commands back to back pays that cost every single time. open unlocks once and drops into a prompt where the same commands run repeatedly against the already-unlocked vault, with the leading <vault-dir> argument omitted:

cipherpaths open ./myvault
# Master password: ********
# Vault opened: ./myvault
# Type 'help' for commands, 'exit' or 'quit' to leave.
cipherpaths> setpw /GitHub https://github.com/login me@example.com 'Tr0ub4dor&3'
cipherpaths> getpw /GitHub
cipherpaths> exit

• Type help for the in-session command list, exit or quit to leave (Ctrl+D / Ctrl+Z also works).
• changepw works inside a session too — the vault stays open and usable straight afterwards.
• init and open are not valid inside a session; a vault must already be open.
• Quote any argument containing spaces, e.g. setpw "/Chase bank" ... — there is no shell inside the prompt to split it for you.

A whole batch of commands can be piped in at once, which is the fast way to script many changes — one unlock instead of one per command:

# bash — commands.txt has one command per line, ending in "exit"
cat commands.txt | cipherpaths open ./myvault

9. Quoting on different shells

The CLI's own argument parsing is identical everywhere — the differences below come entirely from how each shell tokenizes a command line before cipherpaths ever sees it. This matters most for a folder name with a space, or a password containing shell-special characters.

# bash / PowerShell — nothing needs escaping inside single quotes
cipherpaths setpw ./myvault "/Chase bank" https://chase.com jsmith '!@#$%^&*()'

# cmd.exe — a literal % must be doubled, even inside quotes
cipherpaths setpw .\myvault "/Chase bank" https://chase.com jsmith "!@#$%%^&*()"

10. Exit codes & scripting

All of a command's normal output goes to standard output; errors go to standard error prefixed with Error: or Unexpected error:, so scripts can check $? / %ERRORLEVEL% / $LASTEXITCODE and keep stdout clean for parsing.

11. See also

• The Users Guide — the same vault concepts (recovery key, credential types, folders) from the GUI's point of view.
• The GUI's own command-line option — a single argument to CipherPathsWin.exe that jumps straight to one vault's unlock screen. That's a different, much smaller feature from the full CLI documented on this page.
• The FAQ for general questions, and Download for current platform availability.