This page explains how you use klav, Klav’s command line, day to day: unlock once with klavd, find and read items without printing secrets by accident, add and edit them, get one-time codes, generate passwords and check your vault’s health. It runs on macOS and Linux. To install it and sign in, see Install Klav and Create an account. Commands for secrets in your own scripts and projects are in Use secrets without seeing them.
Unlock once with klavd
Without klavd, every command asks for your master password. klav unlock starts klavd, Klav’s background service, and keeps your vault unlocked in memory:
klav unlockUnlocked with password (klavd, pid …); locks after 15m without use. `klav lock` locks now.- On a Mac where Touch ID is enrolled,
klav unlockuses it;--passworduses the master password. klavdlocks after 15 minutes without use (--idle-lockchanges it when it starts) and when the computer sleeps. Listing items, agents or requests andklav statusaren’t use; showing or copying a value, a one-time code or a change are.klav locklocks now;klav lock --stopalso stopsklavd.- The browser extension and the Mac app use the same
klavd: unlocking or locking one unlocks or locks all of them. - In a script,
--password-stdinreads the master password from the first line of standard input.
klav status shows the account, this device and klavd, without a password:
klav statushome: /Users/you/Library/Application Support/klav
server: https://klav.example.com
account: you@example.com (…)
device: my-mac (…)
words: cedar deafening creamed spindle expend humble
daemon: unlocked with password (pid …), locks in 899sKlav keeps this device’s state in ~/Library/Application Support/klav on macOS and ~/.config/klav on Linux. KLAV_HOME chooses another folder.
Find an item
Every item has a reference, klav://Vault/Project/Item. Commands take a reference, the item’s title or its ID.
klav item lsITEM TYPE USERNAME
klav://Personal/General/GitHub login you@example.com
klav://Personal/General/Stripe api-keyklav item lsfilters with--vault,--project,--kind,--tag, and--codesfor items with a one-time code.klav item search gitlooks in titles, usernames, sites and tags.
Read an item
klav item get shows an item with its secret values hidden:
klav item get GitHubGitHub (login)
klav://Personal/General/GitHub
id: …
version: 2
username: you@example.com
password: •••••••• (hidden; use --reveal)
totp: •••••••• (hidden; use --reveal)
urls: https://github.com--field prints one value. A secret value needs --reveal, so a script doesn’t print one by accident:
klav item get GitHub --field passwordklav: password is secret: add --reveal to print itklav item get GitHub --field password --reveal
klav item get klav://Personal/General/GitHub/usernameThe CLI has no copy command: pipe the value where it goes, or use klav run to put it in a command’s environment.
Add and edit
klav item add login --title GitHub --username you@example.com --url https://github.com -g passwordAdded klav://Personal/General/GitHub- Kinds:
login,card,identity,ssh-key,totp,noteandapi-key. Items go to Personal / General unless you pass--vaultand--project. -g passwordfills the field with a generated password.-s <field>asks for a secret on the terminal without showing it, and--secret-stdin <field>reads it from standard input. No option takes a secret value as an argument.-f name=valuesets a field that isn’t secret,--urland--tagadd a site or a tag, and--notes-stdinreads the notes.- Titles are unique in a project:
klavrefuses a repeated title unless you pass--allow-duplicate.
klav item edit takes the same field options (-g, -s, --secret-stdin, -f, --url, --tag, --notes-stdin), plus --title to rename and --rm-field to remove a field. A one-time code is a secret field: paste the setup key or the otpauth:// link the site gives you.
klav item edit GitHub --secret-stdin totpklav item attach stores a file, such as a certificate or a key, as an encrypted attachment.
Previous passwords
When a password changes, the old one is kept:
klav item history GitHubN FIELD FROM UNTIL VALUE
0 Password 2026-11-12 23:47:08Z ••••••••
Use --reveal N to print one.Sites an agent added
When an agent adds a website to a login, Klav doesn’t fill that login there until you confirm it. klav item sites <item> lists them; --confirm confirms them all, and --remove <url> removes one.
One-time codes
klav totp GitHub683163
(valid for 3 s)Generate a password
klav generate~EN*vl2^@?9oF$T~_^k;
(~126 bits, very strong)--site apple.comfollows that site’s password rules, and--rulestakes a field’spasswordrulestext.-t random,-t memorable(or-w 4for four words) and-t pin.-lsets the length of a random password, and--pin-lengththe digits of a PIN.--separatorsets what goes between the words of a memorable passphrase (-by default): 1 to 8 bytes, with no ASCII letters or digits and no control or invisible characters, so that vault health can still read the words back and spot a weak passphrase. A space,.,·or_all work, and one that starts with a hyphen is written with=, as in--separator=--. An empty separator,xor1is a usage error (exit code 2) with any--type.
With klavd running, every generated password goes to the generator history before you see it, so a failed sign-up doesn’t lose it. --no-history skips it.
klav generated lsN GENERATED SITE PENDING SAVED IN
0 2026-11-12 23:47:40Z yesklav generated show N prints one, and klav generated rm deletes entries.
Vault health
klav healthChecked 3 passwords in 4 items.
Reused: 1 group
1. same password in 2 items:
Forum forum.example.com
Shop shop.example.com
Weak: 2
ITEM SITE WHY
Forum forum.example.com strength 0/4
Shop shop.example.com strength 0/4
Old (unchanged for over a year): 0
Breached: not checked (the breach check is off)
See `klav health breach-check` for what it sends before turning it on.It never prints a password. The breach check is off by default and is a setting of this device:
klav health breach-checkBreach check: off
The breach check asks Have I Been Pwned (api.pwnedpasswords.com) about each password. Only the first 5 characters of the password's SHA-1 hash are sent, never the password or the full hash, and the answer is padded so its size gives nothing away. Have I Been Pwned sees your IP address and the time of the check. The setting applies to this device only.
Turn it on with `klav health breach-check on`.klav health --fix-with <agent> offers an agent a task to change your reused passwords; see Approvals and tasks.
The trash
klav item rm Stripe-oldMoved klav://Personal/General/Stripe-old to the trash (kept 30 days).klav item ls --trash lists the trash. No Klav app or command can restore an item from it yet.
Sync and offline
Commands read this device’s copy and sync in the background; klav sync pulls changes now. If the server sends older data than this device already saw, Klav refuses it as a rollback and exits with code 3.
More
- Import from another password manager: Import your passwords.
- Your account, devices and emergency kit: Create an account and Add a device.
- Secrets in commands and files (
klav.toml,klav run,klav inject): Use secrets without seeing them. - Agents: How agents work.