Quick Start

Set up your Kosh vault and store, retrieve and manage your first credential in a few minutes.

Kosh is a local-first, end-to-end encrypted, offline-only CLI password manager. You own your data — nothing ever leaves your machine.

This guide takes you from a fresh install to a working vault. It should take about five minutes.

Set up your vault

Initialize the vault
Section titled “Initialize the vault”

Kosh stores everything in an encrypted SQLite file under ~/.kosh. Create it with:
Terminal window
```
kosh init
```
You will be prompted for a master password, twice. This password is combined with a random salt and fed through Argon2id to derive the key that encrypts your vault’s private key.
```
(default) [?] enter master password:
(default) [?] confirm master password:
(default) [✓] vault initialized successfully
```
The (default) prefix is the active profile. Every line Kosh prints carries it, so you always know which vault you are talking to.

Kosh is zero-knowledge: the master password is never stored, never transmitted, and cannot be reset.
If you lose it, every credential in that vault becomes permanently inaccessible. Write it down and keep it somewhere safe and offline.

kosh init is safe to re-run — if the vault already exists it reports vault already initialized and exits without touching your data.
Add your first credential
Section titled “Add your first credential”
Terminal window
```
kosh add
```
Everything is collected through interactive prompts, so no secret ever reaches your shell history:
```
(default) [?] enter master password:
(default) [?] enter credential label: github
(default) [?] enter credential user: alice
(default) [?] enter credential secret:
(default) [?] confirm credential secret:
(default) [✓] credential saved successfully
```
A credential is identified by its label and user together, so one label can hold several accounts — github/alice and github/alice-work are two distinct entries.
Let Kosh generate a password instead
Section titled “Let Kosh generate a password instead”

Rather than inventing a password yourself, have Kosh generate a cryptographically random one and store it in a single step:
Terminal window
```
kosh generate github alice-work
```
The generated secret is copied to your clipboard and encrypted into the vault. It is never printed to the terminal.
Terminal window
```
# 32 characters, no symbols
kosh generate -l 32 --symbol=false server root

# a throwaway password — clipboard only, nothing saved
kosh generate --no-save
```

See what you have stored

kosh list

  ID   Label    User         Access Count   Last Used     Last Updated   Created At
  --   -----    ----         ------------   ---------     ------------   ----------
  01   github   alice        005 times      02d 04h ago   14d 06h ago    Mon, 21 Jul 2025 14:02:11 IST
  02   github   alice-work   000 times      never         just now       Tue, 05 Aug 2025 09:11:47 IST

kosh list shows metadata only — no secret is ever decrypted here, which is why it does not ask for your master password. The ID column is what update, delete and copy take as their argument.

Retrieve a credential
Section titled “Retrieve a credential”

If you know the exact label and user, use get:
Terminal window
```
kosh get github alice
```
If you only remember part of it, just type it — any argument that is not a subcommand is treated as a search query:
Terminal window
```
kosh github
```
Either way Kosh asks for your master password, decrypts the secret, and copies it to your clipboard:
```
(default) [?] enter master password:
(default) [✓] credential copied to clipboard
```
Secrets are never printed to the terminal. They only ever go to the clipboard.
Try the interactive search
Section titled “Try the interactive search”

Run kosh with no arguments at all:
Terminal window
```
kosh
```
This opens a live picker — type to filter your vault, press enter to select. Kosh’s search tolerates typos and abbreviations, so gpat finds git_personal_access_token.

Where your data lives

Directory~/.kosh/
- config.json which profile is active — {"active_profile":"default"}
- Directoryprofiles/
  - default.db your encrypted vault

~/.kosh is created with 0700 permissions and config.json with 0600. Nothing else is written anywhere, and Kosh makes no network requests at any point.

Keep work and personal separate

Everything above operated on the default profile. A profile is a separate vault, with its own file, its own master password, and its own credentials:

kosh profile create work   # creates it, switches to it, sets its master password
kosh add                   # this now goes into the work vault
kosh use default           # switch back

Profiles are cryptographically isolated — unlocking one gives you no access to another.

Where to go next

Storing Credentialsadd, generate, and the full flag reference for password generation.

Retrieving Credentialsget vs. search, the interactive picker, and typo/abbreviation matching.

ProfilesSeparate, isolated vaults for work, personal, and anything else.

Command ReferenceEvery command, argument and flag in one place.

Quick Start

Set up your vault

Initialize the vault

Add your first credential

Let Kosh generate a password instead

See what you have stored

Retrieve a credential

Try the interactive search

Where your data lives

Keep work and personal separate

Where to go next