Official ClipGate CLI docs

Install fast. Learn the flow. Keep moving.

This is the public docs hub for ClipGate CLI: install channels, first-run workflows, a comprehensive quick reference, configuration guidance, content typing, and the local-first model behind the tool.

Install Free Download Support

Quick install

curl -fsSL https://clipgate.github.io/install.sh | sh

Primary install channels

curl installer for macOS and Linux, pip install clipgate for any platform with Python, manual downloads from Release Notes, and an official Homebrew tap for terminal-native installs.

What ClipGate does

Classifies clipboard items into 13 developer-relevant types, protects secrets, and lets you retrieve by type instead of by recency.

How these docs are organized

Start with Quick Start, skim Core Workflows, then use Quick Reference for copy-paste command variations. Config Guidance explains what to tune without pinning public docs to version-specific defaults.

Install

The public site is the canonical place for ClipGate installs, downloads, release notes, and support. ClipGate is free to use through the official install channels below, and you do not need source access to get the CLI on your machine.

ChannelCommand or pathNotes
Quick installcurl -fsSL https://clipgate.github.io/install.sh | shFastest path for macOS and Linux.
PyPIpip install clipgateWorks anywhere Python is available, including Windows. View on PyPI
Homebrewbrew install clipgate/tap/cgOfficial tap recipe; binaries still download from the public site.
Manual download/releases/vX.Y.Z/...Use the Release Notes page for versioned binaries and checksums.
macOS Intel + Apple Silicon Linux x86_64 + ARM64 Windows via PyPI or manual download No cloud account required

Quick Start

The core loop is simple: capture something, inspect the typed history, retrieve by type, then pack context when you need to hand several related clips to an AI tool.

1

echo "TypeError: x is undefined" | cg copy
ClipGate stores the value and auto-classifies it as an error.

2

cg list
Inspect typed history instead of a flat chronological clipboard list.

3

cg paste -t error
Retrieve the latest clip of the exact type you want.

cg pack -t error -n 5 | claude "fix these issues"

Core Workflows

ClipGate is most useful when the docs teach repeatable terminal habits instead of just listing flags. These are the workflows worth emphasizing first.

Capture and retrieve by type

Use ClipGate as a typed working buffer when you bounce between errors, commands, and file paths.

echo "TypeError: x is undefined" | cg copy cg list cg paste -t error

Find older context fast

Search and inspect when you remember the meaning of a clip, but not when you copied it.

cg search "connection refused" cg inspect -t error cg get -t command

Bundle context for AI tools

Pack several recent clips into a cleaner handoff for Claude, Codex, or any shell-based assistant flow.

cg pack -t error -t command -n 5 cg pack -t error -n 5 | claude "fix these"

Save and restore working context

Use stacks when a task switch would otherwise destroy a useful clipboard state.

cg push -s bugfix cg stack list cg pop -s bugfix

Quick Reference

This is the part users should be able to scan without thinking: real commands, likely variations, the flags that matter, and short operational notes where behavior could surprise you.

Core Clipboard Search & Inspection AI & Packaging Stacks & Cleanup Shell & System
cg copy cg paste cg list cg search cg inspect cg get cg pack cg mcp cg push cg pop cg stack cg clear cg shell-init cg completions cg doctor cg watch cg config cg version

Global flags

--config overrides the config file path, --db overrides the SQLite path, -q/--quiet suppresses output, -v/--verbose adds detail, and --no-color disables colorized output.

Piping and stdout

copy, paste, pack, and machine-readable outputs are designed for shell pipelines. Pipe them into tools that actually read stdin such as cat, grep, jq, pbcopy, wc, or xargs.

Common recipes

cg paste -t error cg search "deploy" -t command cg pack -t error -n 5 | claude "fix these" cg push -s context-switch cg pop -s context-switch

Reference style

The examples below favor commands people can copy as-is. Where help text and older README prose drift from current behavior, these examples stay conservative and implementation-aligned.

Tier 1 — Daily

Core Clipboard

The daily flow starts here: capture text, view typed history, and retrieve the exact item you need without relying on chronology alone.

cg copy

Store text and auto-classify it. Reads from an argument, stdin, or the system clipboard.

echo "some text" | cg copy # pipe from stdin cg copy "literal text here" # pass as argument cg copy --from-clipboard # read from system clipboard cg copy -t command -l "deploy" # override type and add label cg copy --ttl 60 # auto-expire after 60 seconds cg copy --no-persist # keep in memory only cg copy --policy memory_only # explicit storage policy cg copy -q # suppress confirmation and pass-through
FlagDescription
-t, --typeOverride auto-classification.
-l, --labelAttach a human-readable label for later retrieval.
--from-clipboardRead from the system clipboard instead of stdin or an argument.
--ttlSet an explicit time-to-live in seconds.
--no-persistKeep the item in memory only.
--policySet the storage policy directly, such as persist or memory_only.

cg copy prints a short confirmation to stderr and currently passes the captured content through to stdout unless you use --quiet. Use --verbose if you want the confidence score in the confirmation output.

cg paste

Retrieve a stored item by type, label, or ID. Use it when you know what you copied, not just when.

cg paste # most recent item cg paste -t error # most recent error cg paste -t sha -n 3 # third most recent SHA cg paste -i 01KN3K4Q # by item ID prefix cg paste -l "deploy" # by label cg paste --secret # allow secret-type retrieval cg paste --to-clipboard # write result back to clipboard cg paste --with-metadata # prepend type and timestamps cg paste -t path | xargs cat # pipe into a stdin reader
FlagDescription
-t, --typeFilter by content type.
-l, --labelRetrieve by label.
-i, --idRetrieve by ID prefix.
-n, --nthSelect the Nth most recent match.
--secretExplicitly allow retrieval of secret-type items.
--to-clipboardWrite the result to the system clipboard instead of stdout.
--with-metadataPrepend type, ID, and timestamp metadata.

cg paste writes to stdout by default. Pipe it into cat, grep, pbcopy, wc, or xargs. echo does not read stdin, so cg paste | echo will not behave the way people expect.

cg list

Show recent clipboard history as a typed listing. Useful when you want a quick inventory of recent context.

cg list # recent items cg list -t error # only errors cg list -l 50 # show more items cg list -f json # machine-readable output cg list -f csv # export-friendly output
FlagDescription
-t, --typeFilter the listing by content type.
-l, --limitSet the maximum number of items returned.
-f, --formatSwitch output between table, JSON, and CSV.

Use cg list -f json when another tool will consume the output. The table view is optimized for terminal scanning.

Tier 2 — Power Tools

AI & Packaging

These commands are where ClipGate becomes more than clipboard history: structured context packing and tool exposure for AI-assisted workflows.

cg pack

Bundle recent clips into AI-ready context in text, JSON, or Markdown. This is the command you reach for when handing several related clips to an assistant.

cg pack -t error -n 3 cg pack -t error -n 5 | claude "fix these" cg pack -t error -t command -n 10 cg pack -f json | jq . cg pack -f markdown >> issue.md cg pack --no-header cg pack --reverse
FlagDescription
-t, --typeFilter by content type. Repeat it to include multiple types.
-n, --countControl how many items are packed together.
-f, --formatChoose text, JSON, or Markdown output.
--header / --no-headerCustomize or remove the metadata header.
--reverseEmit oldest-first instead of newest-first.

cg pack prints the packed content to stdout and a lightweight item/token summary to stderr unless you use --quiet.

cg mcp

Start the MCP server on stdio so MCP-aware clients can query clipboard state and packed context through ClipGate.

cg mcp

This is a stdio-based MCP server. It is meant for AI tools and editors that speak MCP over JSON-RPC, not for day-to-day terminal retrieval.

Tier 3 — Advanced

Stacks & Cleanup

Use stacks to preserve useful context during task switches and cleanup commands to prune history precisely instead of wiping everything.

cg push

Push a clipboard item onto a named stack so you can come back to it later.

cg push cg push -s deploy cg push -t error cg push -i 01KN3K4Q
FlagDescription
-s, --stackChoose which named stack to push onto.
-t, --typePush the latest item of a given type.
-i, --idPush a specific item by ID prefix.
cg pop

Pop an item back from a stack, optionally previewing it first or writing the result directly to the clipboard.

cg pop cg pop -s deploy cg pop --peek cg pop --all cg pop --to-clipboard
FlagDescription
-s, --stackChoose the named stack to pop from.
--peekView the next item without removing it.
--allEmit every item in the stack.
--to-clipboardWrite the popped content to the system clipboard.
cg stack

Inspect or clear named stack inventory.

cg stack list cg stack clear deploy

Use cg stack list when you need a fast view of active stacks and item counts. Use cg stack clear <name> when a saved context is no longer useful.

cg clear

Delete by recency, type, age, or ID. This is the safest way to keep history tidy without destroying everything unintentionally.

cg clear -n 2 cg clear -n 1 -t error cg clear -t error cg clear --older-than 7d cg clear -i 01KN3K4Q cg clear --confirm
FlagDescription
-n, --nthDelete the Nth most recent matching item.
-t, --typeDelete items of one content type.
--older-thanDelete items older than a duration such as 7d or 24h.
-i, --idDelete a specific item by ID prefix.
--confirmRequired when clearing everything.
Tier 3 — Advanced

Shell & System

Once the basic clipboard loop is comfortable, use these commands to integrate ClipGate into your shell, inspect your environment, and tune behavior.

cg shell-init

Print shell helpers, aliases, and helper functions so ClipGate feels native in your shell session.

eval "$(cg shell-init)" eval "$(cg shell-init zsh)" cg shell-init fish | source

Persist the output in your shell rc file when you want aliases like cgc, cgp, and helper functions like cgr and cgpack available every session.

cg completions

Generate shell completion scripts for tab completion of commands and flags.

cg completions bash > ~/.bash_completion.d/cg cg completions zsh > ~/.zfunc/_cg cg completions fish > ~/.config/fish/completions/cg.fish

After generating completion scripts, reload your shell or source the generated file so the new completions take effect.

cg doctor

Run environment health checks covering clipboard access, database connectivity, config loading, fzf availability, shell detection, secret patterns, and watcher state.

cg doctor
cg watch

Run the clipboard watcher in the foreground or inspect watcher state from the terminal.

cg watch # foreground watcher cg watch --status # check if watcher is running cg watch --stop # stop a running watcher cg watch --daemon # currently reports not yet implemented
FlagDescription
--daemonCommand interface exists, but current public builds report daemon mode as not yet implemented.
--statusCheck the watcher PID state.
--stopStop a watcher using the PID file.
cg config

Inspect and change configuration from the CLI. Use this when you want to understand or override current behavior without hand-editing YAML first.

cg config show cg config get display.verbose cg config get history.max_items cg config set display.quiet true cg config set display.color false cg config set mcp.enabled true

Keep the docs conceptual here. Use cg config show and cg config get <key> for exact current values, because public docs should not drift every time defaults change.

cg version

Print the current version and branding banner.

cg version

Configuration Guidance

ClipGate is zero-config by default. Optional config lives under ~/.config/clip-gate/config.yml. The docs should explain what each config area controls and when to tune it, without freezing exact values into public docs that can drift between releases.

history

Controls retention size, age, database location, and duplicate handling. Tune this when you want ClipGate to remember more context or keep storage leaner.

watch

Controls watcher behavior, clipboard polling, and responsiveness. Tune this when capture feels too eager or too delayed for your workflow.

secrets

Controls detection, storage policy, expiry behavior, warnings, and custom secret patterns. This section should focus on tradeoffs and safety, not just switches.

display and fzf

Controls output verbosity, previews, color, picker behavior, and terminal ergonomics. Tune this when you want quieter automation or richer interactive output.

mcp

Controls how ClipGate exposes itself to AI tooling. Document intent, security posture, and when enabling MCP makes sense.

Exact values

For exact current values, users should rely on runtime inspection:

cg config show cg config get history.max_items cg config get display.verbose
version: 1 history: # retention and storage behavior secrets: # detection, persistence, and expiry policy display: # output and preview behavior

Content Types

ClipGate detects 13 content types and assigns the highest-priority match. This turns clipboard history into a searchable typed buffer instead of a blind time-ordered list.

secret

API keys, tokens, passwords, and high-entropy values. Stored memory-only by default.

error

Stack traces, exception output, and terminal failures.

sha

Git SHAs and hash-like identifiers.

diff

Unified diffs, hunk headers, and patch snippets.

path

Absolute, relative, and home-relative filesystem paths.

json

Structured JSON objects and arrays.

url

HTTP, HTTPS, localhost, and web targets.

sql

Queries and database snippets.

ip

IPv4 and IPv6 with optional ports or CIDR.

env

KEY=value style environment exports.

docker

Dockerfile instructions and Docker CLI text.

command

Shell commands with flags, pipes, and chaining syntax.

text

The safe fallback when nothing more specific matches.

Security Model

ClipGate is intentionally local-first. Clipboard storage, classification, and retrieval happen on the machine where you run the CLI. Secrets are detected early, masked in previews, and kept out of persistent storage unless you explicitly opt in.

Secret handling

Known key patterns plus entropy checks flag sensitive values, store them memory-only, and expire them after the configured TTL.

Local database

Regular history lives in a local SQLite store. No cloud sync or account setup is required for the core flow.

Architecture

The CLI is built around a straightforward capture pipeline: read clipboard or stdin input, classify it, run secret guards, store it locally, then expose the result through retrieval, search, packing, stacks, watcher flows, and MCP tooling.

clipboard or stdin → classifier → secret guard → SQLite or memory → paste, list, search, pack, MCP

Capture

cg copy, watcher flows, and shell pipelines collect raw clipboard context with minimal friction.

Classify

Each item is typed, scored, and preview-safe so later retrieval is semantic rather than chronological.

Store

Secrets stay in memory; regular items go to the local store with retention and display controls.

Retrieve

paste, search, pack, stacks, and MCP expose the stored context to terminal and AI workflows.

Distribution Model

ClipGate source stays private for now, while the public site acts as the official distribution surface for binaries, docs, release notes, license summary, and support. The release pipeline builds in the private repo, publishes artifacts into this public site, publishes the Python package to PyPI, and keeps the Homebrew tap formula in sync.

SurfaceRolePublic outcome
Private CLI repoSource, CI, packagingBuilds and prepares release artifacts.
Public site repoDocs, downloads, release pagesServes installers and binaries via GitHub Pages.
PyPI packagePython-based CLI distributionLets users install ClipGate with pip install clipgate.
Public Homebrew tapFormula distributionLets users install with brew install clipgate/tap/cg.
InstallerReads latest.txt and fetches matching artifactsGives users a stable install command.

Troubleshooting

Common questions and quick fixes for when things don't behave as expected.

My clipboard isn't being captured ⌄

First, verify that the clipboard watcher is running:

cg watch --status

If the watcher is stopped, start it with cg watch in a terminal session or background process. On macOS, ensure ClipGate has accessibility permissions in System Preferences. On Linux, check that your clipboard manager (X11, Wayland, or clipboard-related packages) is installed and functional. Run cg doctor for environment diagnostics.

Secret detection is too aggressive — how do I tune it? ⌄

ClipGate flags high-entropy values and known key patterns by default. To loosen detection or add custom patterns, edit your config at ~/.config/clip-gate/config.yml and adjust the secrets section:

secrets: enabled: true entropy_threshold: 3.5 # lower = more aggressive custom_patterns: - "MY_CUSTOM_KEY"

Then reload with cg config show to verify. For fine-grained control, use cg copy --policy persist to force-store a value as non-secret once.

Can I use ClipGate inside tmux/zellij? ⌄

Yes. ClipGate works inside terminal multiplexers, but clipboard access depends on your system and multiplexer config. On macOS, use tmux with reattach-to-user-namespace or modern clipboard passthrough. On Linux, ensure your multiplexer preserves X11 or Wayland socket forwarding. Run cg doctor to detect the current clipboard backend and verify access.

Where is my data stored? ⌄

Clipboard history lives in a local SQLite database at ~/.local/share/clip-gate/history.db (or the path you set in ~/.config/clip-gate/config.yml). Secrets are stored in memory only unless you explicitly override with --policy persist. Configuration lives at ~/.config/clip-gate/config.yml. No cloud syncing or remote servers are involved.

How do I uninstall and remove all data? ⌄

To remove the binary, use your install method:

# curl installer rm $(which cg) # Homebrew brew uninstall clipgate/tap/cg # pip pip uninstall clipgate

To remove all ClipGate data, watcher state, and config:

rm -rf ~/.config/clip-gate rm -rf ~/.local/share/clip-gate

To stop a running watcher before uninstalling, use cg watch --stop.