Skip to content

docs: add command summaries to --help and update README usage section#178

Open
pxlman wants to merge 2 commits into
sentriz:masterfrom
pxlman:master
Open

docs: add command summaries to --help and update README usage section#178
pxlman wants to merge 2 commits into
sentriz:masterfrom
pxlman:master

Conversation

@pxlman
Copy link
Copy Markdown

@pxlman pxlman commented May 8, 2026

What does this PR do?

  • Extends --help output with a one‑line description for every subcommand (store, list, decode, delete-query, delete, wipe, compact, version).
  • Updates the README.md Usage section to be consistent with the new help text and to document all commands clearly.

Why is this change useful?

Previously, --help only listed command names and just explained the flags not the subcommands, and the README’s “Usage” section was incomplete (e.g., missing version, compact, decode without dmenu). New users had to guess or search elsewhere. These changes make the tool self‑documenting and the README a complete quick reference.

Changes included

  1. In main.go – Modified flag.Usage to print a commands: block with short, action‑oriented descriptions.
  2. In README.md – Rewrote the “Usage” section to cover every command, explain global options, and show typical examples (including cliphist decode <id> and cliphist version).

Example of new --help output

$ cliphist --help                                                                                                                            
Usage:
  ./cliphist <command> [arguments]

Commands:
  store           read clipboard content from stdin and store it (deduplicates, respects size/length limits)
  list            list all stored clipboard items with previews
  decode [id]     decode and print the full content for the given ID (or read ID from stdin)
  delete-query    delete all entries containing a substring (query argument required)
  delete          delete entries by reading IDs from stdin (one per line)
  wipe            remove all entries and compact the database
  compact         compact the database to reclaim space without deleting entries
  version         print version and current flag values

Options:
  -config-path (default /home/pxlman/.config/cliphist/config)
    overwrite config path to use instead of cli flags
  -db-path (default /home/pxlman/.cache/cliphist/db)
    path to db
  -max-dedupe-search (default 100)
    maximum number of last items to look through when finding duplicates
  -max-items (default 750)
    maximum number of items to store
  -max-store-size (default 5MB)
    maximum size of clipboard to store (e.g., 5MB, 10MiB, 1GB)
  -min-store-length (default 0)
    minimum number of characters to store
  -preview-width (default 100)
    maximum number of characters to preview

text

Testing

  • Manually ran cliphist -help and verified all commands appear with descriptions.
  • Checked that readme.md formatting renders correctly on GitHub (code blocks, bullet lists).
  • No functional changes – only documentation improvements.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant