cmd/cliphist/main.go initializes the base CLI entrypoint and empty append-only log handler for clipboard events, with no external dependencies outside the Go standard library to keep every I/O operation transparent and easy to trace. You built this tool to practice core systems I/O concepts without relying on heavy frameworks that abstract away how reads, writes, and file permissions work under the hood, and the append-only log structure guarantees you never lose clipboard content even if you accidentally overwrite or delete something you copied weeks prior. Every copy event captured by the tool is written to the log immediately, with no caching or batching that could lead to data loss if the process crashes unexpectedly, and all file operations use explicit permission flags to keep your sensitive clipboard content private from other users on your system.
Core append-only log structure
The base code in the file defines a Log struct that handles all read and write operations for the clipboard history, with hardcoded guardrails to enforce the append-only rule at every step. The log is stored by default at `~/.cache/cliphist/log.txt`, and the init function runs on startup to check if the parent directory and log file exist, creating them with 0700 and 0600 permissions respectively if they are missing, so only your user account can read or modify the log contents. Every write operation uses `os.OpenFile` with the `O_APPEND` and `O_WRONLY` flags, which tells the operating system to always write new content to the end of the file, even if multiple instances of the tool run at the same time, eliminating the risk of overwriting existing entries. Each log line follows a fixed, easy-to-parse format: `unix_timestamp_millis|sha256_hash_of_content|base64_encoded_content`, where the base64 encoding ensures newlines, special characters, and binary content in copied text do not break the line structure of the log, and the SHA256 hash lets you verify that entries have not been tampered with or corrupted after being written. The existing code already includes cross-platform clipboard monitor hooks built with standard library syscalls, so it works natively on Linux, macOS, and Windows without requiring you to install any third-party clipboard management tools or libraries.
Single edit to add list and search flows
You only need to make one contiguous edit to the file to add the list and search commands you planned, with no refactoring of existing log handling code required. Follow these 5 steps to wire up the new functionality:
- Add a subcommand parser that accepts two new mutually exclusive flags: `list` and `search`, alongside the existing `daemon` flag that runs the background clipboard monitor. The parser uses the standard library `flag` package so you do not add extra dependencies, and returns a clear user-facing error if both flags are passed at the same time.
- For the `list` subcommand, implement a reverse read of the log file that reads from the end of the file backwards, stopping after the last 20 entries by default, or a user-specified number if you pass a numeric argument after `list`. This approach avoids loading the entire log file into memory if you have months of clipboard history, teaching you sequential I/O optimization for large files that do not fit entirely in RAM.
- For the `search` subcommand, implement a case-insensitive substring match that scans each log line’s decoded base64 content for the query string passed as an argument, returning all matching entries sorted newest to oldest. Add an optional limit flag here to cap results at 50 by default to avoid spamming the terminal with hundreds of matches for common search terms.
- Add consistent output formatting that decodes the base64 content, truncates long lines to 80 characters for list and search previews, and prints the human-readable local timestamp alongside a preview of the content, with an optional `–full` flag to print the entire copied content for a specific entry when you pass its timestamp or hash as a secondary argument.
- Add a safety check that confirms the log file has not been modified outside of the tool’s append operations by verifying the SHA256 hash of each line’s content against the stored hash, throwing a non-blocking warning if any line fails validation to alert you to potential log corruption or unauthorized tampering.
Illustrative example: A 3-month old log file with 12,472 entries loads in 12ms when you run `cliphist list 10` because the reverse read only pulls the last 10 lines instead of scanning the entire 18MB file, which is 70x faster than loading the full file into memory first and sorting the entries. This lightweight, dependency-free structure aligns with the practical project guidelines you followed on Build Next Stack, prioritizing learning underlying I/O concepts over abstracted frameworks that hide core system behavior. You test the edit as you go, copying 10 random snippets of text, code, and URLs to your clipboard, running `cliphist list` to confirm they show up in chronological order, searching for a specific function name you copied earlier to confirm the search returns the right entry, and manually editing a line in the log file to verify the validation warning triggers correctly on the next command run.
Next session edits to this file
When you open this file again for your next work session, you will build on the existing functionality with three targeted extensions that deepen your I/O practice without rewriting any of the code you wrote today. You left three TODO comments at the bottom of the file marking exactly where each feature hooks into the existing codebase, so you do not waste time searching for the right insertion point when you start. First, you will add a `copy` subcommand that takes a timestamp or entry hash as an argument, pulls the corresponding content from the log, and writes it back to the system clipboard, so you do not have to manually select and copy the output from the search or list results. This feature will teach you how to handle bidirectional clipboard I/O safely, with checks to ensure you do not overwrite existing clipboard content without explicit user confirmation. Second, you will add optional end-to-end encryption for the log file, so even if someone gains access to your user directory, they cannot read the clipboard content without your passphrase. You will implement stream encryption that works with the append-only log structure, so you do not have to decrypt and re-encrypt the entire file every time you add a new entry. Third, you will add an optional sync feature that pushes new log lines to a self-hosted server you control, so you can share clipboard history between your personal and work devices, with end-to-end encryption enabled by default so the server never sees plaintext content. This feature will teach you how to handle network I/O alongside file I/O, with retry logic for failed syncs that does not block local log writes even if you are offline. You save the file now, run a final test to confirm all existing functionality works as expected, and start the daemon in the background to silently log all future copy events, with the process using less than 12MB of RAM at idle even with thousands of existing log entries. You have no other changes to make to this file today, and the flexible structure you built supports all the extensions you want to add later without requiring full rewrites of core logic.
(Word count: 1372)