Clipman CLI

Development preview: this build is available for practical testing and feedback. Command names, configuration details, and behavior may change before the first stable CLI release.

Clipman CLI is an additional command-line client for Clipman text history. It does not replace the Windows, macOS, Linux, Android, or iOS apps. It is intended for terminals, SSH sessions, scripts, headless systems, and users who prefer ordinary text commands.

Clipman CLI connects to Clipman Server and reads and writes the same encrypted text-history database as the other clients. Clipman Server requires a nonblank, preferably unique history password. File history, Secrets, local clipboard monitoring, and server administration remain in the relevant apps or server tools.

Project page: Clipman on GitHub

Contents

• Quick Start
• Global Options
• Commands
• Selecting Entries
• Interactive Use
• Templates
• Streams and Scripts
• Agent Access
• Configuration
• Security
• Exit Codes
• Included Files
• Changelog
• License

Quick Start

Choose the binary matching the current operating system and processor. It is standalone and does not require Go to be installed. You may rename that binary to clipman-cli or clipman-cli.exe and place it on the command search path. The Windows binary requires Windows 10 or later; the graphical Clipman client remains available for Windows 7.

Run initialization once for each configuration. The easiest method is to use the private importable connection file created by Clipman Server:

clipman-cli init --connection-file clipman-server-connection.clpconf

For a direct private-CA HTTPS server, a current connection file also contains the public authority. The CLI validates it, binds it to the file's HTTPS host, and uses it as the exclusive trust anchor for that profile. No operating-system certificate installation or first-connection trust prompt is required. Treat the connection file as a credential because it also contains the server token.

Running clipman-cli init without --connection-file, --token, --token-file, or --server on a controlling terminal first asks Do you have a Clipman Server connection file (.clpconf)? [y/N]. Answering y prompts for the path to that file and continues exactly as --connection-file would. Answering n, pressing Enter, or running with --non-interactive skips the question and prompts for the server address and token individually instead.

If the server uses HTTPS with a private authority that init does not already trust, and neither --ca-cert nor --insecure was used, it shows the server certificate details and the Authority SHA-256 fingerprint, then asks Trust this certificate for this server? [y/N]. Compare that authority fingerprint with the one shown by the Clipman Server administrator before answering y. Trusting it stores the public authority in the configuration file so later commands do not ask again. Hostname mismatches, expired certificates, and other invalid certificates are rejected rather than offered as trust exceptions. Running with --non-interactive skips the prompt and reports the original error.

After the history password is entered and --save-password was not given on the command line, init asks Save the history password in the configuration file so it is not requested again? [y/N]. Answering y behaves like --save-password config, so later commands no longer prompt for the password; answering n, pressing Enter, or running with --non-interactive behaves like the default --save-password none. See Security for what "saved" means on each operating system before answering y.

Initialization checks the server and, when the selected database already exists, verifies that the history password can decrypt it. If the selected database does not exist, Clipman cannot distinguish a new password from a mistyped password. It warns before any history is created.

Add and retrieve text through standard input and standard output:

printf '%s' 'Text from a terminal' | clipman-cli put
clipman-cli get
clipman-cli get --name deploy-command > command.txt

Global Options

Global options must appear before the command. --ca-cert and --insecure are mutually exclusive. Prefer --ca-cert because it keeps certificate and hostname verification enabled.

Commands

Run clipman-cli --help or clipman-cli COMMAND --help for the current syntax. Global options must precede the command. Command options follow it.

agent permissions, agent search and agent get provide a separate, optional read-only integration interface. They always return JSON and require explicit permission; see Agent Access.

Selecting Entries

get and rm accept a visible zero-based index, exact ID, exact name, or text search. Indices belong to the selected view and can change after another client updates history. Scripts should prefer exact IDs or names.

clipman-cli get 3
clipman-cli get --id 0123456789abcdef0123456789abcdef
clipman-cli get --search kubectl --first
clipman-cli rm --name old-command --yes
clipman-cli get 3 --json
clipman-cli rm 3 --yes

Command options may be written before or after the index, so get 3 --json and get --json 3 are equivalent. To select an entry whose name or search text begins with a hyphen, put -- before it.

An ambiguous search is not treated as bulk deletion. Use a unique ID or a reviewed visible index.

Clipman CLI preserves optional HTML and RTF fields created by Windows or Mac Rich Text history when it reads, merges, and writes shared entries. CLI output remains the authoritative plain-text fallback and does not emit rich clipboard formats.

Interactive Use

Run clipman-cli menu, or run clipman-cli without arguments in an interactive terminal. Each row is a complete sentence naming the entry, its group, the device it came from, and how long ago it was used, so a row read on its own makes sense without column headings.

Choosing a renderer

Two renderers are available and both describe entries with the same words.

• Line is the default. It prints numbered rows and reads typed commands, and avoids full-screen cursor movement entirely.
• Full screen draws a scrolling list with arrow-key navigation, a live filter, and a preview of the selected clip.

Select one with --renderer line or --renderer tui, or the shorthands --line and --tui. Setting renderer in the configuration file changes the default; an option on the command line always wins.

Clipman does not try to detect a screen reader. No portable way to do that exists, and guessing wrong would silently change how the program behaves, so the choice is yours to make and the line renderer remains the default. If a terminal cannot run the full-screen interface, Clipman says so and names --renderer line rather than quietly switching, because the two renderers do not put the same things in the same places.

Because the choice is yours, each interface says which one it is. The line interface opens with Clipman line interface. Type ? for commands., and the full-screen interface names itself on its status line. In both, ? describes the other interface. clipman-cli status reports the configured one as Interface:, which answers the question without opening either.

Switching interface while you work

Press u in either interface to move to the other one. You are asked to confirm first: the full-screen interface takes over the whole window, and in it u is a single key with no Enter behind it, so a stray press should not be able to rearrange your screen. In the line interface answer yes; in the full-screen interface press y.

The switch carries your place across. The entry you were resting on, the search you had typed, and the history-or-templates view you had selected all travel with you, so the interface you arrive in is showing the same thing you left. In the full-screen interface the cursor lands directly on the row you were on; the line interface has no cursor to land, so it says You were on entry 12. after the list instead.

The history already downloaded is handed to the interface being started, so switching does not wait on the network. The choice is also written to your configuration file, so the next run opens where this one ended. If that file cannot be written, Clipman says so and switches anyway; a preference that could not be saved is not worth losing your session over. If the terminal cannot run the full-screen interface, Clipman says so and leaves you where you are, without changing anything.

pick refuses to switch. It offers one choice and exits, so switching out of it would strand you in a picker you could not switch back from.

Menu commands

• Type an entry number to read the entry, a page at a time. Inside it, n and p page, w saves, x runs a program, and q closes. v NUMBER does the same thing.
• Type w, a space, and an entry number to save it to a file.
• Type x, a space, and an entry number to run a program on it. The same rules apply as in the full-screen interface; see Running a program on a clip.
• Type o, a space, and an entry number to write that entry to standard output and exit.
• Type d, a space, and an entry number to delete it after confirmation.
• Type / followed by text to show only matching entries. The text may contain spaces.
• Type / on its own to clear the search.
• Type n for the next page or p for the previous page.
• Type a to add a new clip.
• Type r to reload from the server.
• Type u to switch to the full-screen interface. You are asked to confirm first, because it takes over the whole window. ui and renderer do the same thing.
• Type ? for the command list, or q to quit.

The history is downloaded once when the menu opens and reused for every command afterward, so moving through the list never waits on the network. Deleting or adding an entry updates the list in place. Type r when you want to pick up changes made on another device.

Entry numbers are positions in the current filtered list rather than in the current page, so a number you heard stays valid after paging. While a search is active the numbers refer to the matches, and clearing the search restores the full numbering.

Adding a clip from the menu

a reads a clip over as many lines as you need. Finish with a single period on a line by itself. To store a line that holds only one period, type two periods instead. To abandon the clip without storing it, type !cancel on a line by itself. Clipman then offers an optional name; press Enter to skip it. The new clip joins whichever kind you are browsing, so adding one under --kind templates creates a template.

How much is announced at once

-n COUNT sets how many entries are announced at a time; the default is 20. Every entry remains reachable by paging with n and p. Use --all to announce the whole list at once without paging. This applies to the line renderer; the full-screen renderer scrolls to fit the window.

pick presents a numbered list, takes one choice, and exits. It accepts n and p to page and q to cancel. Prompts use the controlling terminal, so piped clip text remains separate.

The full-screen renderer

Run clipman-cli menu --tui. The list scrolls, a preview of the selected clip sits below it, and a status line reports what just happened.

Running a program on a clip

Press x and type a command. No shell is involved. Clipman splits what you typed into a program and its arguments and runs that program directly, so |, >, ; and && are not operators. Typing one is refused with an explanation rather than passed on as an ordinary argument, because running it would do something you did not ask for. If you meant one literally, put it in quotes.

This is deliberate. A clip is text you copied from somewhere else, and building a command line out of it and handing that to a shell would mean a clip containing ; rm -rf ~ ran when you asked to echo it. Instead the clip becomes exactly one argument that is never split again, whatever it contains.

Write @clip where the clip text should go; it must be an argument on its own. With no @clip anywhere, the clip is piped to the program's standard input instead, which is usually what you want:

x wc -w            count the words in the clip
x xdg-open @clip   open a clip that is a URL
x clip.exe         put the clip back on the Windows clipboard

Output is captured and shown in the viewer rather than printed to the terminal, so you can move through it and read it again. The exit status is always reported, including when a program prints nothing at all. Output longer than 1 MB is cut off and says so. A command that does not finish can be stopped with Escape; while one is running Clipman says so every ten seconds.

On Windows a .cmd or .bat file cannot be started directly because there is no shell to interpret it. Name the interpreter instead, as in x cmd /c mytask.cmd. A program in the current directory needs an explicit path, such as x ./script.sh, since the current directory is not searched.

Correcting what you typed

Whenever Clipman asks something — the filter, an entry number, a file name — the line you are typing can be edited rather than only backspaced. Left and Right move through it, Home and End jump to its ends, Delete removes the character under the cursor, and Ctrl+U clears the line so you can start again. Ctrl+A and Ctrl+E also work as Home and End.

The cursor stays on the character you are editing rather than at the end of the line, so moving back through what you typed reads it to you as you go.

Where the cursor goes

One rule decides it: the cursor sits in whatever you are moving through or typing into, because a screen reader reads the line the cursor is on.

• While you move through the list, the cursor rests on the selected row, in the space just after the entry number, so each arrow key reads out the entry that is now selected. It never rests on the status line while you are browsing.
• When Clipman asks a question, the cursor moves to the end of your answer on the same line as the question. Typing an entry number reads as Go to entry number: 12, so you hear both what was asked and what you have typed so far.

The selected row is also marked with -> in the text itself, and unselected rows are indented to match. A highlight that only changed colours would tell a screen reader nothing, and would be lost in review-mode navigation.

The heading, status line, and preview of the selected clip sit above the list, and the list runs to the bottom of the window. That ordering is deliberate: a terminal receives a redrawn screen from top to bottom, so keeping everything else above the list means the entry rows are the last text written, and a screen reader that reads newly written text finishes on the row you moved to rather than on the status line.

Clipman also redraws as little as it can, because everything redrawn is sent to the terminal again and therefore read again. Moving through the list changes only the two -> markers and the preview line; the entry text, heading, and status line are left alone. The selected row is not highlighted in reverse video for the same reason — a colour change across a whole row would resend every character of it on each arrow key, so only the marker is highlighted. Paging and scrolling have to repaint the list, and after they do the cursor returns to the selected row.

As in the line renderer, only Enter writes to standard output, so clipman-cli pick --tui | ssh web-02 'cat > /tmp/snippet' still transfers the clip and nothing else. The terminal is restored on exit, including if the interface stops unexpectedly.

Templates

Use put --template to create a template entry. get, pick, and menu output resolve the established Clipman date, time, time-zone, operating-system, and username variables. get --raw returns the stored text unchanged. Unknown variables remain unchanged.

clipman-cli put --text '{{year_full}}/{{month_num_padded}}/{{day_of_month_padded}}' --template --name today
clipman-cli get --kind templates --name today

Streams and Scripts

Successful get and pick commands write only clip text to standard output. Prompts and status messages do not enter the data stream. Text must be valid UTF-8 and may contain NUL bytes, whitespace, CRLF, LF, or no final newline.

--newline adds one LF only when the selected text does not already end in LF. --json provides structured output where documented.

Agent Access

The optional agent commands provide bounded, read-only searches for integrations on Windows, macOS and Linux. They use an existing CLI server profile and require no server update or database migration. They do not read the graphical client's local-only or shared-folder history.

Disabled by default: enable history reading yourself for the selected profile only after deciding what you are comfortable sharing. Ordinary history can contain passwords and other private information even outside Secrets. Search previews and full entries returned to an agent may be sent to its AI provider. Secrets, file history, Rich Text and templates are excluded from these commands.

clipman-cli --config agent-profile.toml agent permissions
clipman-cli --config agent-profile.toml agent permissions --read allow --yes
clipman-cli --config agent-profile.toml agent search --query hister
clipman-cli --config agent-profile.toml agent search --query hister --from 2026-10-01 --through 2026-10-05 --group Work --device Laptop --limit 10
clipman-cli --config agent-profile.toml agent get --id ENTRY_ID
clipman-cli --config agent-profile.toml agent permissions --read deny

Configure the profile first using init. Agent reads never prompt for a password: use your existing protected saved credential or supply CLIPMAN_PASSWORD in the process environment. Do not give credentials or connection files to the model. On Windows, saved credentials use Windows account protection; on macOS and Linux, saved CLI passwords are protected by file permissions, not encryption. Agent commands reject server, password, certificate and verbose command-line overrides, and reject profiles with TLS verification disabled. They otherwise retain the profile's existing transport, including HTTP; they do not add encryption to an HTTP connection.

search requires literal text, matches Name or text without executing regular expressions, and defaults to entries created today in the computer's timezone. --from and --through are inclusive calendar dates, with a maximum of 31 days. Giving only --from selects that day. Group and device filters are exact except for case and surrounding spaces. Results are newest-created first, independent of the graphical history sort order.

Search returns at most 20 entries by default, with a hard limit of 50, previews of at most 300 characters, and at most 64 KiB of JSON. matches reports the total matching entries; truncated reports omitted results, while per-entry flags identify shortened previews or metadata. Narrow a truncated search rather than asking for the entire history. get retrieves one exact ID and rejects an entry whose complete JSON response exceeds 64 KiB; it never silently truncates full text.

Responses identify content as untrusted_data. Treat clips as source material, not instructions to run commands, visit links, change permissions or reveal other data. Searching and getting do not change timestamps, pinning, ownership, the system clipboard, pending writes, cached rules or server data. Each request reads current server history and the device's subscribed channels; there is no cached-history fallback, background watcher, local web listener or MCP endpoint. Existing encrypted history blobs are downloaded and decrypted on the client before filtering; only matching previews or the requested entry are returned.

The permission is an opt-in for these commands, not a sandbox for an agent running under your own account. Such an agent may be able to run the ordinary CLI, read your files or change the configuration. Enforce tool restrictions in the agent host as well. The agent interface deliberately has no write, delete, execution or clipboard-replacement command. A user can separately approve the ordinary put workflow when adding an agent's output.

Disable agent reading before returning to an older CLI binary: enabling it adds the agent_read configuration key, which older binaries do not recognize. Disabling removes that key without changing the other profile settings. The package includes an optional skills/clipman-history skill for scoped agent searches. It does not grant access or enforce a sandbox. For installation and the request-and-result workflow, see Agent integration guidance.

Configuration

Where the configuration lives

Clipman CLI looks for config.toml in this order and uses the first it finds:

1. the path given to --config;
2. the path in the CLIPMAN_CONFIG environment variable;
3. config.toml inside the directory named by CLIPMAN_HOME;
4. config.toml sitting beside the clipman-cli program, if one is there;
5. the per-user location: %LOCALAPPDATA%\Clipman CLI\config.toml on Windows, ~/.clipman/config.toml elsewhere.

Keeping settings beside the program

Step 4 lets one copy of Clipman CLI keep its own settings. On an interactive run, init asks:

Settings are normally saved for your user account, where every copy of Clipman CLI shares them.
Save them beside this program instead, so only this copy uses them? [y/N]

Answering y writes the configuration next to the program; that copy then uses it automatically. Two builds in two directories can point at two different servers without interfering, which is useful when testing a new version against a spare server while the installed one keeps working.

init --portable does the same without being asked, for scripts and --non-interactive runs. The question is skipped when --config, CLIPMAN_CONFIG, or CLIPMAN_HOME has already named a location.

The file is adopted only if it already exists, so an ordinary installation is unaffected and the per-user location remains the default. Answering the question or passing --portable is the only way to create one, because creating it should be deliberate.

Clipman looks beside the program, not in the directory you happen to be working in. A configuration file names a server and carries a token, so an unrelated config.toml in some other folder must never quietly take over a session.

Run clipman-cli status to see which configuration is in use; it is the first line of the report and appears as config_path under --json. --verbose also reports it.

The default configuration file is ~/.clipman/config.toml on Linux and macOS, and %LOCALAPPDATA%\Clipman CLI\config.toml on Windows. CLIPMAN_HOME changes the data directory. CLIPMAN_CONFIG or --config selects a particular config file.

The nonblank history password is resolved from --password, CLIPMAN_PASSWORD, saved configuration when explicitly enabled, or a no-echo controlling-terminal prompt. This allows clip text to be read from standard input without consuming the password prompt.

Security

• Encrypted CLIPDB2 data is authenticated before decryption or decompression.
• Database, JSON, nesting, entry-count, and text-size limits are enforced.
• Server tokens, passwords, full database IDs, and clip text are not written to diagnostic output.
• On Windows, saved token and password values are encrypted with DPAPI for the current Windows user. On Linux and macOS there is no equivalent encryption yet: saving the password (via --save-password config or answering y to init's save-password prompt) writes it in plain text into the owner-only configuration file (directory mode 0700, file mode 0600) — it is protected only by file permissions, readable by that user account or root.
• --password, --token, and --text can be visible to other software inspecting the process list. Prefer prompts, environment variables used carefully, token files, connection files, standard input, or --file.
• clipman:// is a convenient name for plain HTTP. Use it only on loopback, a trusted private network, or a VPN. Use HTTPS across an untrusted network.
• Keep the Clipman Server token private. Delete or secure its connection-details file after configuring clients.
• init's certificate-trust prompt is trust-on-first-use, the same model as an SSH host-key prompt: it protects against a passive eavesdropper but not against an attacker intercepting that first connection. Always compare the displayed authority fingerprint against the authority fingerprint shown by the Clipman Server administrator.
• A private authority imported from a current .clpconf file is host-bound and exclusive to that server profile. --ca-cert remains an additive manual option for older setups. --insecure disables certificate and hostname verification and should be used only as a temporary last resort.

Exit Codes

Included Files

The manual directory also includes AgentIntegration.md for agent setup and consent. The optional skills/clipman-history directory contains the complete Clipman History skill and its host metadata.

Each platform has its own directory, and the program inside every one of them is called clipman-cli. Installing it is therefore a move, with no renaming step: pick the directory matching your operating system and architecture and copy the program out of it.

Changelog

0.10.0 development preview

• Added optional, read-only agent searches for server-backed text and links. Search by a literal term and creation-date range, with optional group and device filters, then retrieve relevant entries by ID.
• Reading is disabled by default and must be explicitly enabled for the selected CLI profile. Returned clips may reach the agent's AI provider; Secrets, file history, Rich Text and templates are excluded.
• Included a Clipman History agent skill and setup guidance for turning relevant clips into summaries or drafts. Results are treated as untrusted source material, not instructions to execute.
• Searches return bounded JSON, and failures are distinguished from an empty result. Reads do not change the clipboard, timestamps or server history, retry pending uploads, or repair missing server rules.
• This CLI-only update needs no server or graphical-client update. It addresses Samuel's scoped-search suggestion in issue #65; the broader MCP and mobile requests remain open.

0.3.0 development preview

• A config.toml sitting beside the clipman-cli program is now used in preference to the per-user one, so one copy of Clipman CLI can keep its own settings. An interactive init asks whether to save settings beside the program or for your user account; init --portable chooses the former without asking. The per-user location remains the default when no such file exists.
• status now reports which configuration file is in use, as its first line and as config_path under --json.
• Exit code 4 now means only what it says. A local failure — a malformed database, a decode error, a merge problem — that happened to surface through a command which also talks to the server used to exit 4, reporting a network fault that had not occurred and telling a script to retry something retrying could not fix. Those now exit 1. Code 4 is reserved for timeouts, unreachable servers, TLS failures, and HTTP 413 or 5xx.
• Press u in either interface to switch to the other one, after confirming. Your place, your search, and your history-or-templates view travel with you, the already-downloaded history is handed over so the switch does not wait on the network, and the choice is saved as your default. A terminal that cannot run the full-screen interface leaves you where you are with a spoken reason and no change to your settings, and a configuration file that cannot be written costs a saved preference rather than the session. pick refuses to switch, because it offers one choice and exits.
• Each interface now says which one it is. Two interchangeable interfaces ship, but nothing named the one you were in, so there was no reason to suspect the other existed. The line interface now opens with Clipman line interface, the full-screen interface names itself on its status line, and ? in either one describes the other and how to reach it. status reports the configured interface as Interface: and as interface under --json. clipman-cli --help no longer describes menu as the line-based manager, which was wrong whenever the full-screen interface was configured, and now says that menu is what runs when no command is given.
• Added an optional full-screen renderer: menu --tui and pick --tui, or renderer = "tui" in the configuration file. The line renderer remains the default. Both describe entries with the same words, and Clipman does not attempt to detect a screen reader. The cursor sits in whatever you are moving through or typing into: on the selected row while you arrow through the list, and at the end of your answer on the same line as the question when Clipman asks something. The selected row is marked with -> in the text, not by colour alone. Press g to go to an entry by number.
• The menu now downloads the history once when it opens and reuses it for every command. Previously every command downloaded the whole database again, so each keystroke waited on the network.
• Added searching in the menu with /TEXT, and / alone to clear the search.
• Added paging in the menu and in pick with n and p. Every entry is now reachable; previously -n hid the entries past its limit entirely. -n now sets the page size, and --all announces the whole list at once.
• Added a to write a new clip from inside the menu, over as many lines as needed.
• Added ? for the menu command list, so the prompt no longer has to spell every command out on each line.
• Menu and pick rows now name each field and give a relative time, so a row read on its own is understandable. Out-of-range and unrecognized commands now say what is valid instead of giving one generic message.
• Restructured the release package so each platform has its own directory holding a program simply called clipman-cli. Installing it is now a move instead of a rename.
• Added a Windows ARM64 build.
• Moved the manual and manual page into a manual directory.
• Fixed get and rm rejecting an option written after the index. get 3 --json and rm 3 --yes reported "only one index may be supplied" and now work as documented.
• Fixed sync reporting "History is current: 0 entries" when no database existed for the token and history password, which could hide a mistyped password. It now says so explicitly.
• Fixed a negative index reporting "entry not found" instead of a usage error.
• Fixed --help and -h being ignored when another option preceded them, so get --json --help now prints the command syntax and exits successfully.
• Replaced the generated option dump printed on a usage error with the command's one-line syntax, which is shorter and clearer to read aloud.
• Implemented --verbose, which was previously accepted and ignored, and documented it.
• status --json now reports entries as null rather than -1 when --refresh was not used.

0.2.0 development preview

• Returned Clipman CLI to active development after practical server testing and community feedback.
• Added safe private-authority and self-signed HTTPS support through --ca-cert, plus an explicitly warned --insecure fallback.
• Added guided initialization for Clipman Server connection files, certificate-authority trust, and optional history-password persistence.
• Added authority-fingerprint verification aligned with Clipman Server, while continuing to reject hostname mismatches and expired certificates.
• Added automated certificate, configuration, and build checks and refreshed the Go dependencies used by the standalone binaries.

0.1.1 development preview

• Added portable server connection-file support, enforced nonblank server history passwords, and published binaries for Windows, macOS, and Linux.

License

Clipman CLI is supplied under the MIT License. See LICENSE.txt.