Retrieving Credentials

Retrieving a credential means decrypting a stored secret with your master password and copying it to your system clipboard.

Secrets never touch your terminal

Kosh does not print secrets — not to stdout, not to logs, not on --help. A retrieved secret only ever goes to the clipboard.

There are two ways to retrieve:

	Command	Use when
Exact match	kosh get <label> <user>	You know exactly what it is called
Fuzzy search	kosh search [label] [user]	You only remember part of it

---

Exact match with get

kosh get github alice

Both arguments are matched literally — no fuzzy matching, no partial matches. This is the right command for scripts, and for when several credentials share a similar name and you need the one you asked for.

Labels or users containing spaces must be quoted:

kosh get "aws prod" "ops-team"

A successful lookup bumps the credential’s access count, which nudges it higher in future searches.

---

Fuzzy search

kosh search github

Any argument that is not a known subcommand is passed to search, so the subcommand name is optional:

kosh github

Kosh scores every credential in the vault and picks the best match. You are asked for your master password only after a match is found — a search that finds nothing never prompts.

Narrowing with a user

Give a second argument to search the label and user fields separately:

kosh search github alice

The first argument is matched against the label, the second against the user. This is how you pick between several accounts under the same label.

You can also search by user alone — a query that matches no label but matches a username will still surface the credential, just with a lower score.

Interactive search

Run search with no arguments — or just run kosh on its own:

kosh search
kosh

This opens a live picker. Type to filter the vault as you go, use ↑/↓ to move through the top matches, enter to select, and esc to cancel. Cancelling reports operation aborted; it is not an error.

---

Search is forgiving

Matching is approximate, which means partial and misspelled queries still work.

Typos, including swapped letters

Kosh measures string distance with Damerau-Levenshtein, which counts a swap of two adjacent characters as a single mistake rather than two. Transposition is the most common category of typo, so this matters more than it sounds:

kosh crat        # matches "cart"
kosh recieve     # matches "receive"
kosh githbu      # matches "github"

Abbreviations

Kosh rewards queries whose characters appear in order inside the target, even with large gaps. That turns long, underscore-heavy credential names into three-keystroke lookups:

kosh gpat        # matches "git_personal_access_token"
kosh awsprod     # matches "aws_production_key"
kosh dbpw        # matches "database_password"

Case and whitespace

Matching is case-insensitive and surrounding whitespace is trimmed on both the query and the stored value, so GitHub, github and github all behave identically.

---

How results are ranked

Results are ranked on how closely the label and user match your query. Recently and frequently used credentials are boosted, but usage can never promote a credential above a closer match.

The ordering of match quality, strongest first:

exact  >  prefix  >  substring  >  ordered subsequence  >  fuzzy edit-distance

So github beats githubby beats my-github-token beats ghb beats gitbub.

Credentials scoring below a minimum threshold are discarded entirely rather than shown as weak matches.

The full scoring model is documented in Adaptive Search Algorithm.

---

What happens on a successful retrieval

1. Your master password is verified.
2. The vault’s private key is decrypted.
3. The credential’s per-entry key is recomputed and the secret decrypted.
4. The secret is copied to the clipboard.
5. The access count is incremented and the last-used timestamp updated.

The clipboard write happens before the metadata update, so the secret lands on your clipboard even if the bookkeeping write is slow or fails.

Clipboard hygiene

Kosh does not clear your clipboard afterwards. Paste what you need and clear it yourself if you are on a shared machine.

On Linux, the clipboard requires a running display server (X11 or Wayland). On a bare TTY or a display-less SSH session, retrieval will fail at the copy step.