CopyBuffer user guide: every shortcut, vault and cbvault

Installation and permissions

1. Move the downloaded CopyBuffer.app to your Applications folder and open it. A clipboard icon appears in the menu bar.
2. Press ⌘⇧V in any app and pick an item. The first time, CopyBuffer asks for Accessibility permission. Turn on CopyBuffer in System Settings ▸ Privacy & Security ▸ Accessibility.
3. To start it automatically when you log in: menu bar icon ▸ Settings ▸ General ▸ Launch at login.

The app's interface follows your macOS language (System Settings ▸ General ▸ Language & Region) and is available in English, Korean, Japanese, Simplified Chinese, Traditional Chinese, Spanish, German, French and Hindi.

Panel basics

Press ⌘⇧V and the panel opens under your text caret. Just start typing to search; type several words separated by spaces and only items containing all of them remain (file names and paths, and text inside images, are searched too).

Your usual ⌘V still pastes the last thing you copied. Text pasted from the list carries no formatting, so ⌘⇧V → ↩ is effectively macOS's "Paste and Match Style". To paste the current clipboard as plain text right away, press ⌥⇧⌘V in any app (Paste as plain text in the menu bar menu; one second after pasting, the clipboard goes back to what it was).

Clipboard shortcuts

Clipboard history is split into All · Text · Images · Files tabs. Each tab shows how many items match the current search, and CopyBuffer remembers the tab you picked last.

How each type is stored

Copying the same thing again moves it to the top instead of adding a duplicate. Images are compared by content hash.

Paste transforms

Select an item and press ⌘T to get a list of transforms with a preview of the result. Transforms that don't apply to that item (such as JSON formatting for something that isn't JSON) or wouldn't change it are hidden.

Paste in sequence

1. In the list, mark the items you want to paste, in order, with ⌘↩ (they get numbered).
2. Press ↩ to paste the first one; the rest go into the paste queue. The number left is shown next to the menu bar icon.
3. Move to the next field and press ⌃⌘V each time to paste the next item.

To paste them all at once joined together, mark them and press ⇧↩. Clear the queue from the menu bar menu ▸ Cancel paste queue. ⌃⌘V is only captured while there is a queue, so it doesn't get in the way of other apps' shortcuts.

Snippets

Switch to the Snippets tab with ⇥ in the panel, or manage snippets from the menu bar menu ▸ Snippets (it opens the Snippets tab in Settings). You can also save one straight from clipboard history with ⌘S.

Give a snippet a Keyword (such as ;addr) and it rises to the top of search results: exact keyword match first, then keyword prefix match, then word match. Placeholders that are replaced with their value at the moment you paste:

Password vault

To get started, choose Password vault in the menu bar menu (or press ↩ on the panel's Password tab) and click Create vault. Once you set a master password (at least 10 characters), your recovery key is shown exactly once. The recovery key is the only way to open the vault if you forget the master password, move to a new Mac or reinstall macOS, so write it down somewhere safe.

Selected text straight into the vault (⌃⌘C)

Select an API key or password and press ⌃⌘C (or choose Add selected text to vault in the menu bar menu) to open it as a new vault entry. Check it, then save with ⌘S. The selected text is read without going through the clipboard. If nothing is selected, CopyBuffer uses the text you just copied and then removes it from the clipboard and from clipboard history (handy for a web console's "Copy" button → ⌃⌘C). A .env line such as OPENAI_API_KEY=sk-… comes in together with its environment variable name, an otpauth:// URL goes into Two-factor authentication (OTP), and multi-line text goes into Notes.

The site you're on comes first, with phishing warnings

When you open the panel in Safari, Chrome, Arc, Edge, Brave, Firefox, Whale, Vivaldi or Opera, entries matching the current address (subdomains included) come first. If you try to paste a password saved for a different site, you get a warning and have to press ↩ again within 8 seconds to paste it. This is also recorded in the Access log.

Two-factor authentication (OTP)

Edit an entry, and under Two-factor authentication (OTP) enter the Secret key (Base32) or an otpauth:// URL, or click QR image to read a QR code from an image on the clipboard or from a file. 6- to 8-digit codes with SHA1, SHA256 and SHA512 are supported. Press ⌥↩ in the panel to paste the current 2FA code.

Password audit and breach check

In the vault window's Security tab, Password audit lists weak passwords, reused passwords, passwords not changed for over a year, empty passwords, and any found in a breach. Next to Breach check (Have I Been Pwned), Check sends only the first 5 characters of each password's SHA-1 hash to Have I Been Pwned (k-anonymity, with response padding requested) to see whether the password appears in known breaches. Neither the password itself nor its full hash is ever sent.

Encrypted backup

In the vault window's Security tab, under Backup, click Export. CopyBuffer asks for your master password once more, then creates a file encrypted with a separate backup password you choose. The backup isn't tied to this Mac, so you can import it on another Mac. When the same entry exists on both sides, Import keeps whichever one was edited more recently.

Auto-lock

The vault locks after 5 minutes of inactivity, and on sleep, screen lock, user switching and when you quit the app.

Terminal environment variables (cbvault)

Instead of keeping API keys in plain text in a .env file while you develop, pull them from the vault with Touch ID when you need them.

1. Edit a vault entry and enter a name (e.g. OPENAI_API_KEY) under Terminal environment variable. Only ASCII letters, digits and underscores are allowed, and the name can't start with a digit. The value is the entry's password.
2. Settings ▸ Terminal ▸ Install. This makes ~/.local/bin/cbvault point to the command inside the app. If that folder isn't on your PATH, add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc.

# inject into one command only (safest)
$ cbvault run OPENAI_API_KEY STRIPE_KEY -- npm run dev

# export into the current shell / print just the value / list registered names
$ eval "$(cbvault export OPENAI_API_KEY)"
$ cbvault get OPENAI_API_KEY
$ cbvault list

# add this to ~/.zshrc to get the cbload / cbunload functions
$ eval "$(cbvault shell-init)"
$ cbload OPENAI_API_KEY
Loaded: OPENAI_API_KEY
$ cbunload OPENAI_API_KEY

• Every time a value is handed over, you approve it with Touch ID (or your Mac login password). Repeat requests for the same names from the same terminal aren't asked again for 5 minutes, and locking the vault revokes that immediately.
• If the vault is locked, CopyBuffer shows the unlock window and waits up to 2 minutes.
• While your screen is being recorded or shared, CopyBuffer won't unlock a locked vault, and it refuses requests where cbvault get or cbvault export runs without a pipe and would print the value straight to the screen. cbvault run and eval "$(cbvault export …)" keep working.
• The app accepts requests only over a socket that only you can access (agent.sock, 0600), and uses the kernel audit token to check that the connecting process runs as the same user and is a cbvault signed with the same certificate as the app. Copied or modified binaries are refused.
• The approval prompt and the Access log record the requesting process path and working directory.

Settings and recording exclusions

Menu bar icon ▸ Settings… (⌘,)

Also available straight from the menu bar menu: Pause recording (15 minutes / 1 hour / Until I resume; while paused, the menu shows Resume recording instead), Don’t record next copy, and Don’t record copies from ‘…’ for the app in front. Copies that a password manager marks as concealed are never stored, whatever your settings.

To open the panel from another shortcut tool (Karabiner, Hammerspoon and so on), post the distributed notification local.copybuffer.toggle (Clipboard), local.copybuffer.snippets (Snippets) or local.copybuffer.vault (Password).

Data location and deletion

All data lives in ~/Library/Application Support/CopyBuffer/. The folder is 0700 and the files are 0600 (readable by you only). Settings such as excluded apps and the history size are kept separately in ~/Library/Preferences/local.copybuffer.CopyBuffer.plist.

To clear history: menu bar menu ▸ Clear history (except pinned), or delete items one at a time with ⌘⌫ in the panel. To remove the app completely, move it to the Trash and delete the folder above.

Security design

Clipboard history, snippets and images

• Encrypted with AES-256-GCM. Each file's purpose is bound in as authenticated data (AAD), so a file swapped in for another won't open.
• The key is wrapped by this Mac's Secure Enclave key (which can't be exported) and kept in history-key.json. It doesn't ask for Touch ID, and it can't be opened on another Mac.
• When the key can't be used (for example, when the app starts while the screen is locked), nothing is written to disk: text you copy stays in memory only, and images aren't recorded. Once you unlock, CopyBuffer tries again, opens the existing history and merges in whatever you copied in the meantime.
• Images briefly decrypted for pasting or opening go into a temporary folder (0600) and are deleted after 30 minutes, and again whenever the app starts or quits.

Password vault

• Key structure: a random 256-bit data key encrypts all entries and the entire access log with AES-256-GCM. The data key is wrapped with HKDF(PBKDF2-SHA256(master password, 3,000,000 iterations) ‖ device secret).
• Device binding: the device secret can only be derived through ECDH with a P-256 key inside the Secure Enclave. Even if someone copies the vault file, brute-forcing the password on another device isn't possible at all.
• Touch ID: confirms it's you every time the Secure Enclave key is used.
• Sealed in memory: even while the vault is open, each entry's password, notes and OTP secret key stay encrypted under a separate key, and are decrypted only at the moment you view or paste them.
• Tamper protection: KDF settings, device information and entry IDs are bound in as authenticated data, so tampering such as lowering the iteration count or swapping entries makes the vault fail to open.
• Attempt limits: after 5 failures in a row you wait 30 seconds, doubling with each further failure (up to 1 hour). This survives an app restart.
• Access log: unlocks, locks, failed attempts, recovery key use, viewing, copying and pasting (and into which app), 2FA codes, pastes on a mismatched site, added, edited and deleted entries, master password changes, backups, breach checks, and environment variables provided or refused. It's encrypted along with the vault, so it can't be edited or deleted without the master password.
• Clipboard: passwords carry the concealed marker (ConcealedType) so clipboard apps that respect it don't keep them, and your previous clipboard is restored 1 second after pasting. If you only copied, it's cleared after 20 seconds. Passwords are placed on the clipboard for this Mac only, so they don't travel to your iPhone or iPad through Universal Clipboard.
• Screen: the panel's Password tab and the vault window don't show up in screenshots, screen recordings or screen sharing. USB monitors such as DisplayLink and virtual displays work by capturing the screen and sending it on, so on those displays the protection is turned off to keep the window visible, and the panel shows Capture blocking off. While screen recording or sharing is in progress, the Password tab and the vault window are hidden and won't open until it ends. The master password field uses secure input mode.

App process

• Signed with the hardened runtime to block code injection.
• No core dumps (which would contain memory) are written on a crash, and debugger attachment is denied.
• The app goes online only when you ask: pressing Check for the breach check, and registering a license key (only that key is sent, once, to the license server). There is no cloud, account or analytics.

Troubleshooting

Picking an item copies it but doesn't paste it

Accessibility permission is turned off. Turn on CopyBuffer in System Settings ▸ Privacy & Security ▸ Accessibility (the menu bar menu's Turn on auto-paste (Accessibility permission) takes you there). Until then, items are copied to the clipboard, so you can paste them with ⌘V.

Copies from a certain app aren't recorded

Check whether the app is in Settings ▸ Excluded apps, and whether recording is paused (the menu bar icon shows a pause symbol). Copies that a password manager marks as concealed aren't stored either.

cbvault: The CopyBuffer app isn’t running

Open the app first. Environment variables are handed out only by the running app, and only after Touch ID approval.

cbvault: Only a cbvault signed the same way as CopyBuffer can connect

You're using a cbvault that was copied out of the app. Delete the copy, then recreate the link to the command inside the app with Settings ▸ Terminal ▸ Install (it won't overwrite a regular file at ~/.local/bin/cbvault).

The panel opens near the mouse pointer instead of under the text caret

The app doesn't report its text caret position (some terminals, Electron apps and so on). Pasting still works as usual.