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 init`	Initialize a new encrypted vault
`kosh add`	Add a new credential interactively
`kosh list`	List stored credentials
`kosh get <label> <user>`	Retrieve (decrypt) a credential
`kosh search <label> [user]` / `kosh <label>`	Adaptive fuzzy search
`kosh delete <id>`	Permanently delete a credential
`kosh generate [flags] <label> <user>`	Generate a strong password
`kosh update <id>`	Update fields of an existing credential
`kosh completion`	Generate shell autocompletion script

`kosh init`

Initialize a new encrypted SQLite vault.

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`

Interactively add a new credential to the vault.

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.

`kosh list`

Show a list of saved credentials.

kosh list [flags]

Flags

Flag	Description
`-l, --label`	Filter credentials whose label contains the given string
`-u, --user`	Filter credentials whose user contains the given string

Examples

List all entries

kosh list

Filter by label

kosh list --label github

Filter by user

kosh list --user alice

Combined filters

kosh list --label github --user alice

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

`kosh get <label> <user>`

Retrieve (decrypt) a credential by exact match.

kosh get <label> <user>

Behavior:

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

Example

kosh get github alice

`kosh search <label> [user]`

Search your vault using Kosh’s adaptive fuzzy matching.

kosh search <label> [user]

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

Single-argument search

Searches across both label and username:

kosh search git

Any argument that doesn’t match an existing command name also falls back to search, so this is equivalent:

kosh git

Two-argument search

Provide separate fuzzy queries for label and user:

kosh search github alice

Equivalent to fuzzy-matching both fields independently.

`kosh delete <id>`

Permanently delete a credential from the vault.

kosh delete <id>

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.

Example

kosh delete 42

`kosh update <id>`

Update fields (label, user, or secret) of an existing credential.

kosh update <id>

Process:

Prompts for master password
Shows the exact credential to be updated
Prompts for which field to update
Requires a typed confirmation phrase
Updates the specified field in the vault

Warning: Updates are irreversible.

Example

kosh update 42

`kosh generate`

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

kosh generate [flags] <label> <user>

The generated password is:

Cryptographically random
Encrypted before storage
Automatically copied to your clipboard

Arguments

Argument	Description
`label`	Identifier for the credential (e.g. `github`, `email`). Ignored with `--no-save`.
`user`	Username or account associated with the credential. Ignored with `--no-save`.

Flags

Flag	Description	Default
`-l, --length int`	Length of the generated password	`20`
`--upper`	Include uppercase letters (A–Z)	`true`
`--lower`	Include lowercase letters (a–z)	`true`
`--digit`	Include digits (0–9)	`true`
`--symbol`	Include special symbols	`true`
`-r, --require string`	Enforce minimum character counts per group (e.g. `upper=2,digit=3`)
`-n, --no-save`	Generate password but do not save it to the vault	`false`

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 length, Kosh will prompt to automatically increase it.
If --no-save is used, the password is generated and copied to clipboard without requiring a label, user, or master password.
If a credential with the same label + user already exists, overwrite confirmation is required.
Master password verification is required before saving (unless --no-save is used).
Requirements cannot contradict disabled character groups (e.g. --symbol=false with symbol=2 is invalid).

Examples

Generate a default password

kosh generate github alice

Generate a 32-character password

kosh generate -l 32 email personal

Enforce strict character requirements

kosh generate --require "upper=2,lower=10,digit=5,symbol=3" email alice

Generate a password without symbols

kosh generate --symbol=false server root

Generate a temporary password without saving

kosh generate --no-save

`kosh completion`

Generate the autocompletion script for the specified shell.

kosh completion [shell]

Supported shells: bash, zsh, fish, powershell.

Run kosh completion --help for shell-specific installation instructions.

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Authentication failure (wrong 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.