Skip to content
Kosh Docs
Menu
HomeQuick StartCommandsSecurityDownload
Start Here
InstallationQuick StartUpgrading to v0.3.0
Guides
Storing CredentialsRetrieving CredentialsManaging CredentialsProfiles
Reference
Configuration & FilesTroubleshooting
Technical Documentation
ArchitectureEncryption ArchitectureAdaptive Search Algorithm

Managing Credentials

List, filter, update and permanently delete the credentials in your Kosh vault.

Once credentials are in the vault, list, update and delete are how you keep them tidy. All three operate on the active profile.

List what you have

Section titled “List what you have”
Terminal window
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
  03   aws      ops-team     042 times      03h 12m ago   01M 08d ago    Fri, 27 Jun 2025 18:33:02 IST
Column Meaning
ID The numeric handle update, delete and copy take
Label / User The pair that identifies the credential
Access Count How many times the secret has been retrieved
Last Used Relative time since the last retrieval, or never
Last Updated Relative time since the last change
Created At Absolute creation timestamp

Relative times show the two most significant units — 02d 04h ago, 03h 12m ago, just now, never. The table sizes its columns to the content, so nothing is truncated.

An empty vault, or a filter that matches nothing, prints an empty table.

Filtering

Section titled “Filtering”
Terminal window
kosh list --label github     # labels containing "github"
kosh list --user alice       # users containing "alice"
kosh list -l aws -u ops      # both must match

These are plain substring filters, not the fuzzy search used by kosh search. Combining --label and --user requires both to match.

Update a credential

Section titled “Update a credential”
Terminal window
kosh update <id>

Take the ID from kosh list. After your master password is verified, you choose one field to change — label, user, or secret — and confirm before anything is written.

Terminal window
kosh list -l github
kosh update 7
(default) [?] enter master password:
(default) [•] select the credential field to update
    1. label
    2. user
    3. secret

Renaming a label or user

Section titled “Renaming a label or user”

Renaming cannot produce a duplicate. If the resulting label and user pair is already taken by another credential, the update is aborted with credential already exists.

The confirmation for a rename is neutral, because a rename is reversible — you can just rename it back:

(default) [?] enter 'update label from github to gh' to confirm or anything else to cancel:

Changing the secret

Section titled “Changing the secret”

Changing the secret re-encrypts it with a fresh ephemeral key and nonce. The previous value is gone for good, and the confirmation says so:

(default) [!] this operation is permanent and cannot be undone

Delete a credential

Section titled “Delete a credential”
Terminal window
kosh delete <id>
Terminal window
kosh list -l github
kosh delete 7

The flow is deliberately slow:

  1. Your master password is verified.

  2. The exact credential to be deleted is shown.

  3. A caution block appears:

      | /!\ CAUTION: DESTRUCTIVE ACTION
      | This credential will be deleted PERMANENTLY.
      | The operation is IRREVERSIBLE and the secret is IRRECOVERABLE.

  4. You must type an exact confirmation phrase:

    (default) [!] delete this credential permanently?
    (default) [?] enter 'delete github alice' to confirm or anything else to cancel:

Anything other than the exact phrase cancels and reports operation aborted.

Moving credentials between profiles

Section titled “Moving credentials between profiles”

To put a copy of a credential into another vault:

Terminal window
kosh list                  # find the ID
kosh profile list          # find the target profile name
kosh copy 7 personal

The original stays where it is — copy is a copy, not a move. To finish a move, delete the original afterwards. See the Profiles guide for the details.

What’s next

Section titled “What’s next”