Documentation

Installation

ClipinVault is distributed as a native installer for Windows and a .deb package for Ubuntu/Debian. No runtime or admin rights are required on Windows.

Windows

1. Download ClipinVaultSetup.exe from the Downloads section.
2. Run the installer- Windows may show a SmartScreen prompt - click More info → Run anyway.
3. Choose whether to create a desktop shortcut and whether to start with Windows.
4. Click Install. ClipinVault launches automatically when finished.

Ubuntu / Linux

1. Download the .deb package from the Downloads section.
2. Install with: sudo dpkg -i clipinvault_*.deb
3. If dependency errors appear, run: sudo apt-get install -f
4. Launch from your application menu or run clipinvault in a terminal.

Upgrading

Run the new installer over the existing installation — it will close the running app, replace the binary, and relaunch. Your database, settings, and all clips are never touched during an upgrade.

First Launch

On first launch ClipinVault creates its data directory and starts monitoring the clipboard immediately. No sign-in, no account, no configuration required.

1. The app window opens. Copy anything — a URL, a code snippet, a password — and it appears in the list within a second.
2. Click any entry to see its full content in the detail pane on the right.
3. Click Use for Paste (or press Enter) to put the clip back on your system clipboard so you can paste it anywhere.
4. Close the window. ClipinVault keeps running in the system tray — clips keep being captured.

Clipboard Capture

ClipinVault listens to the OS clipboard event in the background. Every time you copy something — with Ctrl+C, right-click → Copy, or any application's copy action — the content is captured and stored locally.

How capture works

• Debounce: rapid successive copies within 300 ms are merged to prevent duplicate entries from drag-resize or auto-copy applications.
• Deduplication: the SHA-256 hash of each entry is computed before saving. If an identical item already exists, the copy count on the existing entry is incremented — no duplicate is added.
• Size limit: entries up to 5 MB are accepted. Anything larger is silently skipped to prevent performance issues with huge clipboard payloads.
• Minimum length: single-character or empty copies are ignored to reduce noise.

What gets captured

• Plain text, rich text, code, JSON, SQL, URLs, terminal commands
• Screenshots and copied images (stored encrypted, displayed as previews)
• Any text content your applications place on the clipboard
ℹ️
ClipinVault does not capture clipboard content from other ClipinVault paste operations — re-pasting a clip does not create a duplicate entry.

Content Types

Every entry is automatically tagged with a content type the moment it is captured. The type controls how the entry is displayed, coloured, and filtered.

Changing the type manually

Click on the type badge of any entry in the detail pane. A dropdown lets you switch between text, code, sql, json, url, cmd, and secret. Changing to secret will immediately encrypt the content.

Search

ClipinVault uses SQLite FTS5 (Full-Text Search version 5) — the same engine that powers many professional search applications. Results appear as you type with no perceptible delay even across thousands of entries.

How to search

1. Click the search bar at the top of the window (or press Ctrl+Shift+V to focus it).
2. Type any word, phrase, or fragment. Results update in real time.
3. Use the type filter dropdown to narrow results to a specific content type (e.g. only code or only url entries).

Search tips

• Search matches against both the entry content and the custom title you may have set.
• Search is case-insensitive.
• Secret entries are excluded from search results — their content is encrypted and not indexed. You can still find them by switching the type filter to secret.
• Clearing the search bar returns to the full list sorted by most-recent first.

Pinning & Titles

Pinning entries

Click the pin icon on any entry to mark it as pinned. Pinned entries:

• Always appear at the top of the list regardless of age.
• Are never deleted by the Auto-Clean janitor, regardless of retention settings.
• Survive application updates unchanged.

Click the pin icon again to unpin. Unpinned entries return to the normal chronological list.

Custom titles

Every entry can have a user-defined title (max 80 characters). Click the title area of an entry in the detail pane and type a name — for example, "Production DB password" or "Deploy script for staging". The title is searchable and appears as the primary label in the list view.

Pasting Clips

Finding a clip is only half the job — getting it back into your workflow is the other half. ClipinVault offers several ways to paste.

Click to paste

1. Select an entry in the list.
2. Click Use for Paste in the detail pane.
3. Switch to your target application and press Ctrl+V as normal.

Keyboard shortcuts

System tray quick-paste

The system tray icon shows the 5 most-recent clips in its context menu. Click any of them to copy the clip directly to your clipboard without opening the main window.

Secrets Mode

Secrets Mode lets you store sensitive data — passwords, API keys, tokens — inside your clipboard history without exposing them in plain text.

Marking an entry as secret

1. Find the entry in your list (it may have been auto-captured as text).
2. Open it in the detail pane.
3. Click the type badge and choose secret.
4. The preview immediately changes to •••••••• and the content is encrypted on disk.

Using a secret

Click Use for Paste on a secret entry. ClipinVault decrypts it in memory, copies the plain text to your clipboard, and you can paste normally. The decrypted content is never logged.

Encryption

ClipinVault uses AES-256-GCM envelope encryption for all secret entries and all image files. This is the same algorithm used in TLS, Signal, and modern storage encryption.

How it works

• Master key: a 32-byte random key is generated on first launch and stored in your OS credential store (Windows Credential Manager on Windows, Secret Service API on Linux, Keychain on macOS). It never touches disk in plain form.
• Per-entry key: each secret entry gets its own unique random data key. The data key is encrypted by the master key (envelope encryption) and stored alongside the ciphertext in the database.
• Nonce: a unique 12-byte nonce is generated for every encryption operation, ensuring that the same plaintext encrypts to different ciphertext each time.

What this means for you

• If someone copies your database file (ClipinVault.db), they cannot read your secrets without also having your OS master key.
• Your secrets are safe even if the app is force-closed mid-write (WAL journal mode ensures atomicity).
• Uninstalling the app and re-installing on the same machine preserves the master key — your encrypted secrets remain readable.
ℹ️
If your OS keyring becomes unavailable (locked, corrupted, or moved to a new machine), secret entries will appear locked. Regular text, code, and image entries are unaffected.

Exporting Clips

The Export feature lets you package your clipboard history into a portable .clipbundle file that you can move to another machine or store as a backup.

How to export

1. In the ClipinVault window, click File → Export in the menu bar.
2. The Export dialog shows checkboxes for each content type. Select the types you want to include.
3. Optionally enable Export secrets (separate file) to include your secret entries.
4. Click Export and choose where to save the file.

What gets exported

Bundle file format

A .clipbundle file is plain JSON. It can be opened with any text editor. The format is stable across ClipinVault versions.

Importing Clips

Import a .clipbundle or .secrets.clipbundle file to merge clips from another machine into your current vault.

How to import

1. Click File → Import in the menu bar.
2. Click Select .clipbundle file and pick the bundle you exported.
3. A preview shows the number of entries found and their types.
4. Click Import to confirm. The merge begins immediately.

What happens during import

• Deduplication: entries whose content hash already exists in your vault are skipped. You will never end up with duplicates.
• Secrets re-encryption: secret entries from a .secrets.clipbundle are encrypted with this device's master key the moment they are imported. They are never stored as plain text.
• Metadata preserved: pin status, custom titles, and usage counts from the bundle are imported alongside the content.
• Images and MFA skipped: even if a bundle somehow contains image or mfa entries, they are silently ignored as a safety guard.
💡
Import is non-destructive. Your existing clips are never modified or removed during an import — only new, unique entries are added.

Create Clip

You don't need to copy something to an external app and then come back to ClipinVault — you can create a clip directly inside the app at any time.

How to create a clip manually

1. Click the New Clip button at the top of the left sidebar.
2. The clip list and detail panel are replaced by a full-panel editor. Only the sidebar remains visible.
3. Optionally enter a Title (up to 80 characters) at the top of the editor.
4. Type or paste your content in the editor area. Line numbers are shown live; Tab inserts 2 spaces and Enter auto-indents to match the current line.
5. Use the type selector at the bottom left to choose a content type (text, code, sql, json, url, cmd, mfa, or secret).
6. Click Save Clip. The new clip appears in the list and is selected automatically.

Edit Clip Content

Captured clips sometimes contain extra whitespace, truncated lines, or content you want to refine. The Edit Content feature lets you update the text of any clip in-place.

How to edit a clip

1. Select the clip in the list to open it in the detail pane.
2. Click Edit Content at the bottom of the detail pane. The button is only shown for editable types.
3. The detail area switches to an edit panel with the current content pre-loaded.
4. Make your changes in the text area. You can also change the content type using the type selector.
5. Click Save to commit. The list preview and the full-text search index are both updated immediately.
6. Click Cancel or press Esc to discard your changes.

Which clips can be edited

Auto-Clean

The Auto-Clean janitor runs in the background every hour and removes old clips according to your retention policy. It is disabled by default — nothing is ever auto-deleted until you enable it.

Configuring Auto-Clean

1. Open Settings (gear icon in the top bar).
2. Enable the Auto-Clean toggle.
3. Set Max age (days): clips older than this are deleted. Set to 0 to disable age-based cleanup.
4. Optionally set Min usage count: clips with fewer usages than this threshold are also deleted. Set to 0 to disable usage-based cleanup.

What is never auto-deleted

• Pinned entries — the pin flag is an explicit "never delete" signal. Pinned entries survive Auto-Clean regardless of age or usage count.
• Entries with a hard expires_at date in the future (reserved for future features).
ℹ️
The janitor only runs while the app is open. If you close ClipinVault for a week and reopen it, the janitor runs once when the app starts and catches up on all overdue deletions.

Keyboard Shortcuts

Troubleshooting

My copies aren't appearing in the list

• Check that ClipinVault is still running — look for the icon in your system tray.
• Content shorter than 2 characters is ignored automatically.
• Content larger than 5 MB is skipped silently.
• Try clicking Refresh in the toolbar to force a reload from the database.
• On Linux, ensure the required clipboard daemon (xclip or xsel) is installed.

Import / Export menu items are greyed out or don't work

⚠️
Import and Export require the native Wails app window. If you open http://localhost:5173 in a browser (dev mode), the file-picker API is not available. Always use the installed desktop app for these features.

The app says secrets are "locked"

This means the OS keyring is unavailable — your master key cannot be retrieved. Common causes:

• Windows: your Windows account is locked or using a temporary profile. Sign in normally and relaunch ClipinVault.
• Linux: the GNOME Keyring or KWallet service is not running. Start it with gnome-keyring-daemon --start and relaunch.

Text, code, URL, and image entries remain fully usable — only secret entries are affected.

My data disappeared after an update

This should never happen. The installer only replaces the application binary in the install directory — it never touches your data directory.

If you lost data, the most likely cause was a manual uninstall that deleted %LOCALAPPDATA%\ClipinVault before reinstalling. Use File → Import to restore from a .clipbundle export if you have one.

Large content is not being captured

ClipinVault captures up to 5 MB per entry. Content exceeding this is silently skipped. If you regularly copy very large payloads (e.g. multi-MB log files), consider splitting or compressing them before copying.

Data Location

All ClipinVault data is stored locally on your machine. There is no cloud sync or remote storage of any kind.

Windows

Linux

Files inside the data directory

Backing up your data

The safest backup method is File → Export inside the app — it produces a clean, portable bundle. For a full backup including images and settings, copy the entire data directory while ClipinVault is closed.