Command Reference

Kosh provides a small, focused set of commands designed for secure, local-first credential management. This page documents all CLI commands, their arguments, behaviors, and examples.

Command	Purpose
`kosh help`	Show help and usage
`kosh init`	Initialize a new encrypted vault
`kosh add`	Add or update a credential
`kosh list`	List stored credentials
`kosh get <label> <user>`	Retrieve (decrypt) a credential
`kosh search <query>` / `kosh <query>`	Adaptive fuzzy search
`kosh delete <id>`	Permanently delete a credential

`kosh help`

Display help, available commands, and usage details.

kosh help

`kosh init`

Initialize a new encrypted SQLite vault in the current directory.

kosh init

Prompts you for:

Master password (used to derive your encryption key via Argon2id)

Notes:

The vault is created as a local SQLite file.
Master password cannot be changed after initialization.

`kosh add`

Add a new credential or update an existing one.

kosh add

Interactive prompts:

Label
Username
Password (hidden input)
Confirm password

If a credential with the same label + username already exists, it will be securely overwritten.

Below is a drop-in command reference section for kosh generate, written to match the style, tone, and structure of your existing documentation. You can paste this directly into the same page.

`kosh generate`

Generate a strong random password and store it securely in the vault.

kosh generate [options] <label> <user>

The generated password is:

Cryptographically random
Encrypted before storage
Automatically copied to your clipboard

Arguments

label Identifier for the credential (e.g. github, email). Must not conflict with an existing command name.
user Username or account associated with the credential.

Options

-length int
      Length of the generated password (default: 20)

-upper
      Include uppercase letters (A–Z) (default: true)

-lower
      Include lowercase letters (a–z) (default: true)

-digit
      Include digits (0–9) (default: true)

-symbol
      Include special symbols (default: true)

-require string
      Enforce minimum character counts per group.
      Format: group=count[,group=count...]

Valid requirement groups

Group	Description
`lower`	Lowercase letters
`upper`	Uppercase letters
`digit`	Digits
`symbol`	Special symbols

Behavior

If the total required characters exceed the requested password length, Kosh will prompt to automatically increase the length.
If a credential with the same label + user already exists:
- Overwrite confirmation is required
- A typed confirmation phrase is required
Master password verification is required before saving.

Examples

Generate a default password

kosh generate github pluto

Generate a longer password

kosh generate -length 32 email personal

Enforce strict character requirements

kosh generate -require "upper=2,lower=10,digit=4,symbol=2" bank main

Generate a password without symbols

kosh generate -symbol=false server root

Notes

Requirements cannot contradict disabled character groups (e.g. -symbol=false with symbol=2 is invalid).
Passwords are generated locally; no network access is ever used.
Clipboard handling is platform-specific but automatic.

If you want, I can also:

Add kosh generate to the command table at the top with a short purpose line
Normalize wording across all commands (add/get/generate consistency)
Produce a man-page (kosh-generate(1)) version of this section

`kosh list`

List credentials stored in the vault.

List all entries

kosh list

Substring filter

kosh list github

Matches label or user via simple substring matching.

Field-specific filters

kosh list --label github
kosh list --user pluto

Combined filters

kosh list --label github --user pluto

Shows entries where both label and user contain the given substrings.

`kosh get <label> <user>`

Retrieve (decrypt) a credential by exact match.

kosh get github pluto

Behavior:

Prompts for master password.
Decrypts the credential.
Copies the password to your clipboard.

`kosh search <query>`

Single-Argument Search

Search your vault using Kosh’s adaptive fuzzy matching.

kosh search git

Or use the shorthand:

kosh git

Searches across:

Label
Username

Returns the best-scoring match based on fuzzy distance, prefix/substr boosts, recency, and usage frequency.

Two-Argument Search

Provide separate fuzzy queries for label and user:

kosh search github pluto
kosh search mail personal

Equivalent to fuzzy-matching both fields independently.

`kosh delete <id>`

Permanently delete a credential from the vault.

kosh delete 42

Process:

Prompts for master password
Shows the exact credential to be deleted
Requires a typed confirmation phrase (delete <label> <user>)
Securely deletes the row and overwrites freed memory

Warning: Deletion is irreversible.

Exit Codes

Kosh uses standard exit code conventions:

0 – success
1 – general errors
2 – invalid arguments
3 – authentication failure (incorrect master password)
4 – vault not found

Environment Notes

Clipboard handling is platform-specific but abstracted away internally.
Vault is always local; Kosh never performs any network requests.
Works on Linux, macOS, and Windows.