Keep your service keys in csec.

An access key is a password that lets software use an online service. csec keeps those values in encrypted storage on your computer so a tool can retrieve a key when it needs it.

This is a terminal tool. A developer or someone comfortable with your computer's command line can help with setup.

1. Install

The first installation trusts this download source and HTTPS. It downloads and runs software on your computer. Later updates are checked against a signing key inside the installed tool.

macOS or Linux

curl -fsSL https://csec.limbs.dev/install | bash

Windows PowerShell

irm https://csec.limbs.dev/install.ps1 | iex

Follow the installer's path instructions if your terminal cannot find csec. Then check:

csec version

2. Save a key

First obtain a key from the service you want to use. Replace SERVICE_API_KEY below with the name your tool expects:

csec set SERVICE_API_KEY

Enter the value at the hidden prompt. This saves it locally. Keep the actual value out of chat, project files and the command itself.

To see saved names without printing their values:

csec ls

Save a multiline value

For a PEM key, JSON configuration or another multiline value, read a private local file instead of putting its contents in an argument:

csec set SERVICE_CONFIG < config.json

This preserves internal line endings and removes exactly one final LF or CRLF. The local input limit is 1 MiB after that removal. An oversized value or a read failure is refused without saving partial input. Keep the source file private; storing its contents does not remove it. Local input capacity is separate from the shared 640 KiB repository publication limit described below. Check installed help for this input mode.

3. Connect the tool that needs it

Follow that tool's credential setup. ahh, for example, retrieves its configured service keys from csec. A tool that is not integrated with csec needs an explicit retrieval step.

csec get NAME prints the secret value. Use it only where you intend that value to be visible, and do not paste its output into a shared report. Use csec --help for the commands supported by your installed version.

4. Update or remove a key

Run csec set SERVICE_API_KEY again to replace a saved value. If a key was exposed or is no longer needed, revoke it at the service that issued it; deleting a local copy does not revoke access.

csec rm SERVICE_API_KEY

Removal affects this computer only. With synchronisation enabled, a later sync can restore the value from another snapshot. Replace revoked keys with their new values and synchronise every client.

Use the same keys on another computer

This optional setup uses a dedicated private GitHub repository containing encrypted, signed snapshots. Install Git and GitHub CLI on each computer, then authenticate with gh auth login. On the first computer:

csec sync setup

Save the repository name and the generated 24-word recovery phrase somewhere private and separate from the computer. The phrase is shown during setup; do not put it in chat or a shared log. On another computer, use the repository name printed by setup:

csec sync join OWNER/REPOSITORY

Enter the recovery phrase when prompted. Run csec sync on each computer when you want to publish or retrieve changes; synchronisation is explicit. For conflicts, history, restore, rotation and encrypted offline export/import, read csec sync help.

Ordinary changes made on only one side sync automatically. Different edits to the same key need a choice between this machine and the repository. The prompt describes changes since the last sync and the available remote block time, without showing value fragments. Older snapshots do not record a writer name, and the local store does not record a separate edit time for each key. A checkpoint time may be later than the original edit. Skipping a conflict keeps each side's value while unrelated changes continue.

Choose a side for each conflict

For an intentional scripted resolution, select the local value of one key and the repository value of another:

csec sync --resolve-key API_KEY=local --resolve-key DATABASE_URL=remote

The arguments contain names and choices, not secret values. --resolve local|remote|skip supplies a policy for remaining conflicts. Skipped conflicts remain open and return exit 1 while unrelated changes can still synchronise. Check csec sync status and the reported pulled, published, conflicted and restored counts before treating reconciliation as complete. Use the current binary on every client; an upgraded client without a recorded merge base may need an initial choice.

Keep all clients updated. Older clients cannot read the current repository metadata format. SSH/SFTP synchronisation and the old --migrate setup flag are no longer supported; their old files are left untouched.

A legacy client may have published a name that current clients cannot store. Current sync skips such names with a warning and keeps reading the valid entries. Use csec sync repair-names --dry-run to preview a clean checkpoint, then csec sync repair-names to publish it. This keeps the local store, recovery phrase and retained history. Upgrade every writer so an old client does not reintroduce those names.

Repository capacity applies to the whole signed snapshot: 640 KiB including JSON encoding, signature and metadata. There is no fixed per-key allowance. A larger value can be kept locally; set and import warn when the cached sync configuration shows it cannot publish. csec sync status shows current publication usage, and an oversized outgoing snapshot still permits incoming changes. Reduce the named largest entries before retrying publication.

Keep an encrypted offline copy

After repository sync is configured, export a snapshot to a new file:

csec sync export backup.age

Keep the archive and recovery material in separate safe places. On a computer that has joined the same repository, merge an archive back with:

csec sync import backup.age

The archive contains encrypted values, but cannot recover them without the matching identity. Keep the repository and recovery phrase available, and retain the recovery material needed by older archives when rotating keys. Import merges values rather than deleting names absent from the archive.

What to know before using it

• Encryption protects stored values. Programs running as your operating-system user can still retrieve them; csec does not make a compromised computer safe.
• On Linux without a desktop keyring, a file restricted to your account holds the master key. Disk encryption remains useful.
• Synchronisation is a separate setup step. It uses encrypted snapshots in a private Git repository. Do not copy store.enc alone to another computer: its master key stays on the original machine.
• A local deletion can be restored by a later sync. Read csec sync help before changing a synchronised collection.
• Current repository conflict prompts show names and change metadata, not value suffixes or lengths. Legacy archive conflict diagnostics and older clients can still reveal the final four characters and length of longer values. Some history fingerprints can help test guesses for weak values if the rest of a snapshot is known. Keep diagnostics private and review them before sharing.

Automatic update checks send the publisher your operating-system username, hostname, platform and csec version; the server also sees connection information such as your IP address. Set CSEC_UPDATE_DISABLE=1 for processes where you want these automatic checks disabled.

If something fails

Read the reported error before changing files. A missing or unreadable key does not mean the encrypted store should be deleted or replaced. Preserve the store and any recovery material while you investigate.

If repository sync was configured, an intact repository and its recovery phrase let a new computer join. Without a working local key or a usable backup and its recovery material, csec cannot reconstruct lost secrets. Do not treat a copy of store.enc by itself as a portable backup.