Core concepts

A handful of ideas explain how everything in Klef fits together.

Workspaces

A workspace is the top level grouping of projects. Everyone has a personal workspace by default. Create additional workspaces to group projects for a team or a client.

klef workspace list
klef workspace create "Acme Inc"

Projects

A project maps to one application or repository. It holds one or more environments. You create a project with klef init, which writes a .klef file to the current directory, or link an existing directory to a project with klef link.

klef init my-app
klef projects list

Environments

An environment is the unit of encryption. Each environment (for example development, staging, production) has its own symmetric key, so secrets in one environment cannot be decrypted with another environment's key.

klef env list
klef env create staging --name "Staging"

Most commands act on the project's default environment. Override it per command with -e, --env:

klef pull --env production
klef get DATABASE_URL --env staging

To change the default for the whole directory, switch it once with klef env use:

klef env use staging

Secrets

A secret is a single key and value, for example DATABASE_URL. The key name is stored in plaintext so you can list and search it. The value is always encrypted with the environment key.

klef set API_KEY sk-123
klef get API_KEY
klef list

The .klef file

.klef is a small JSON file written by klef init or klef link. It records the project id and the default environment. It holds no secrets and is meant to be committed to git, so anyone who clones the repo can run klef pull and get the right secrets.

Your .env* files, by contrast, hold plaintext values and should stay out of git.

The background agent

Typing your encryption password on every command gets tedious. The optional background agent (klef-agent) caches your derived keys in memory between commands so you unlock once and keep working.

• Keys live in the agent's memory only, never on disk.
• They expire after 1 hour of inactivity, with an 8 hour hard cap.
• klef lock clears the cache. klef agent stop stops the agent entirely.
• Set KLEF_NO_AGENT=1 to disable it.

klef agent status
klef lock