CLI reference

KeepInVault CLI

A command-line tool (nicknamed kiv) for reading and managing your vault from a terminal — useful for scripting, automating logins in a CI pipeline, or just looking up a password without opening a browser. It's built for developers and anyone comfortable typing commands, but this guide assumes no prior CLI experience and walks through every step.

Before you start

What you'll need

The CLI is published on npm, so installing it is a single command. You need:

•Node.js 22.11 or newer and the npm command it installs alongside it — check with node -v. Get it from nodejs.org if you don't have it.
•A terminal app — Terminal on macOS, Windows Terminal or PowerShell on Windows, or any terminal on Linux — to type the commands below into.

Step 1

Install the CLI

Install @keepinvault/cli globally from npm, so the kiv command works from any folder.

npm install -g @keepinvault/cli
kiv --version

If kiv --version prints a version number, it installed correctly. Update later with the same npm install -g command.

Permission errors on macOS/Linux

If the global install fails with EACCES, your Node was installed system-wide. Use a version manager such as nvm, or run it once without installing: npx @keepinvault/cli <command>.

Step 2

Log in

Same account, same vault as the web and mobile apps. Your master password is turned into encryption keys on your own machine and never sent anywhere — only a derived, one-way authentication key is. The session is then stored in your OS's credential manager (macOS Keychain, Windows Credential Manager, or the Linux Secret Service), the same way the desktop and mobile apps protect it — not in a plaintext file.

kiv login
kiv whoami

kiv login will prompt for your email and master password right there in the terminal (it's never accepted as a command-line flag, so it can't leak into your shell history). kiv whoami confirms which account you're logged into.

Self-hosting, or multiple accounts?

Point the CLI at your own server once with kiv config set-api-url https://your-server/api. To juggle more than one account (e.g. personal and work), add --profile <name> before any command — each profile keeps its own login session and API URL, so kiv --profile work login and kiv --profile work list stay separate from your default profile.

Step 3

Try the everyday commands

Every command below accepts an item by name (not just its internal ID) — kiv get Gmail works as well as the exact ID, and if more than one item matches, the CLI lists the candidates instead of guessing.

kiv listList every vault item.

kiv find <query>Search items by name, username, or domain.

kiv get <item> --field password --copyCopy a field to the clipboard (auto-clears after 20s).

kiv add --name Gmail --username me@gmail.com --generateAdd a login with a freshly generated password.

kiv edit <item> --notes '...'Update one or more fields on an item.

kiv rm <item>Delete an item (asks to confirm).

Also handy

Generate a password

Print (or copy) a strong random password on its own, without creating a vault item — handy for setting a password on a site you haven't added to your vault yet, or piping into another tool.

kiv generate --length 24 --copyGenerate a 24-character password and copy it to the clipboard.

Uses the same generator as kiv add --generate and the web app — cryptographically random, never a weaker fallback, and guarantees at least one character from each class you leave enabled (letters, digits, symbols).

Also handy

Authenticator (TOTP) codes

Store an authenticator secret on an item and print its rotating 6-digit code — no phone required.

kiv totp add <item> --uri 'otpauth://totp/...'Add a secret from an otpauth:// URI (what a QR code encodes).

kiv totp <item> --copyCopy the current code to the clipboard.

If something goes wrong

Troubleshooting

"Not logged in", right after `kiv login` succeeded

Make sure you're passing the same --profile to both commands — sessions are stored per profile, and the default profile is used whenever --profile is omitted.

"Could not reach <url>"

The configured API URL is wrong, or the server isn't running. Check it with kiv config show.

Clipboard commands (`--copy`) do nothing on Linux

Clipboard access needs xclip, xsel, or wl-clipboard installed, depending on your display server.

"This command needs an interactive terminal"

The master-password prompt needs a real terminal window to hide your keystrokes — run kiv login directly, not from a script or an automated job.

Under the hood

Zero-knowledge, same as everywhere else

The CLI reuses the exact same encryption package (@keepinvault/crypto-core) as the web app, mobile app, and browser extension. The server only ever stores ciphertext — it never sees a vault item's plaintext contents or your encryption key, whether you're using the CLI or any other client.

Every command and flag in detail: docs/CLI_Reference.md in the project repository.

Integrating KeepInVault into your own project instead of using the terminal directly? See the developer guide.