.TH CLIPMAN-CLI 1 "October 5, 2026" "Clipman CLI 0.10.0" "User Commands"
.SH NAME
clipman-cli \- access Clipman text history from a terminal
.SH SYNOPSIS
.B clipman-cli
.RI [ global-options ]
.I command
.RI [ command-options ]
.br
.B clipman-cli
.RI [ global-options ]
.SH DESCRIPTION
Clipman CLI is an additional command-line client for Clipman text history.
It does not replace the Windows, macOS, Android, or iOS applications.
This development preview is intended for practical testing and feedback;
commands and configuration may change before the first stable CLI release.
It 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.
.PP
Running without a command opens the accessible line menu when a controlling
terminal is available. Run
.B clipman-cli --help
or
.B clipman-cli COMMAND --help
for the complete current syntax.
.SH COMMANDS
.TP
.B agent
Optional bounded, read-only integration commands. Reading is disabled by
default for each CLI profile. Run
.B agent permissions --read allow --yes
to acknowledge disclosure of ordinary clipboard history to the requesting
agent, or
.B agent permissions --read deny
to revoke it. This is not a sandbox for other programs running as your user.
.IP
.B agent search --query TEXT
searches Name and plain text for clips created today in the computer's timezone.
Use inclusive
.B --from YYYY-MM-DD
and
.B --through YYYY-MM-DD
for another range of at most 31 calendar days.
Optional exact, case-insensitive filters are
.B --group NAME
and
.BR "--device NAME" .
.B --limit COUNT
selects 1 to 50 results (default 20). Results are newest-created first and
contain previews of at most 300 characters. All responses are JSON of at
most 64 KiB, with explicit truncation flags and untrusted-content markers.
.IP
.B agent get --id ID
returns one complete plain-text entry or fails if the output is too large.
Secrets, file history, Rich Text and templates are excluded. Reads honor device
channel subscriptions without changing timestamps, the clipboard, pending
uploads, rule caches or server data. There is no cached-history fallback.
These commands do not prompt for credentials, accept transport or password
overrides, or permit profiles with TLS verification disabled. They use the
existing profile transport, including HTTP, without adding transport encryption.
.IP
Returned material may reach an AI provider and ordinary history may contain
sensitive information. Enforce tool permissions in the agent host and treat
clipboard contents as data, never executable instructions. Disable reads before
using an older CLI, which does not recognize the enabled agent_read key.
The optional skills/clipman-history skill and manual/AgentIntegration.md
describe human-approved scoped searches. The skill does not grant access
or enforce a sandbox.
.TP
.B init
Configure and test a server profile. A Clipman Server connection-details file
can supply the server address and token without manually extracting JSON. For
direct private-CA HTTPS, a current connection file also supplies the public
authority. The CLI validates it, binds it to the HTTPS host, and uses it as the
exclusive trust anchor for that profile.
Run on a controlling terminal without
.BR --connection-file ,
.BR --token ,
.BR --token-file ,
or
.BR --server ,
it first asks
.RB \(dq "Do you have a Clipman Server connection file (.clpconf)?" \(dq
before prompting for that file's path or, on
.BR n ,
falling back to the address and token prompts.
.B --non-interactive
skips this question.
.IP
If the server presents an HTTPS authority that is not already trusted and
neither
.B --ca-cert
nor
.B --insecure
was given, it shows the server certificate details and authority SHA-256
fingerprint and asks
.RB \(dq "Trust this certificate for this server?" \(dq \.
This is trust-on-first-use, the same model as an SSH host-key prompt; compare
the authority fingerprint against the one Clipman Server provides before
answering
.BR y .
Trusting it saves the certificate to the configuration file.
Hostname mismatches, expired certificates, and other invalid certificates are
still rejected.
.B --non-interactive
skips this prompt and reports the original error.
.IP
After the history password is entered, if
.B --save-password
was not given it asks
.RB \(dq "Save the history password in the configuration file so it is not requested again?" \(dq \.
Answering
.B y
behaves like
.BR "--save-password config" .
See
.B SECURITY
below: on Linux and macOS this stores the password in plain text, protected
only by file permissions, not encryption.
.TP
.B status
Check the configured server and selected history. Use
.B --refresh
to download and decrypt the database.
.TP
.B list
List entries, optionally filtered by group, search text, or kind.
.TP
.B get
Write one selected entry to standard output. Template entries resolve unless
.B --raw
is used.
.TP
.B put
Add UTF-8 text from standard input,
.BR --file ,
or
.BR --text .
Standard input is preferred for sensitive text because command arguments can
be visible in the process list.
.TP
.B rm
Delete exactly one entry and add a synchronization tombstone.
.IP
.B get
and
.B rm
accept their index before or after the command options, so
.B "get 3 --json"
and
.B "get --json 3"
are equivalent.
.TP
.B pick
Display a numbered list on the controlling terminal and write the selected
entry only to standard output. Type
.BR n " or " p
to move between pages, or
.B q
to cancel. Accepts the renderer options described under
.BR menu .
.TP
.B menu
Browse history interactively. This is what runs when no command is given at
all, and it opens the line interface or the full-screen interface according to
your configuration. In the line interface, commands are a number to view an entry,
.BI "o " NUMBER
to write it to standard output and exit,
.BI "d " NUMBER
to delete it after confirmation,
.BI / TEXT
to show only matching entries,
.B /
alone to clear the search,
.B n
and
.B p
to page,
.B a
to add a new clip,
.B r
to reload from the server,
.BI "v " NUMBER
to read an entry a page at a time, which is also what a bare number does,
.BI "w " NUMBER
to save an entry to a file,
.BI "x " NUMBER
to run a program on an entry,
.B u
to switch to the full-screen interface,
.B ?
for the command list, and
.B q
to quit.
.IP
Reading an entry opens a paged reader with its own prompt, where
.B n
and
.B p
page,
.B w
saves,
.B x
runs a program, and
.B q
closes it. A clip is never announced in one block: a long one would otherwise
arrive as a single unstoppable announcement.
.B pick
allows
.B v
but refuses
.B w
and
.BR x .
.IP
The history is downloaded once when the menu opens and reused for every
command, so browsing does not wait on the network. Use
.B r
to pick up changes made on another device.
.IP
Entry numbers are positions in the current filtered list, not in the current
page, so a number stays valid after paging. When a search is active the numbers
refer to the matches.
.IP
.B a
reads a clip over several lines. Finish with a single period on a line by
itself, write two periods for a line holding one period, or type
.B !cancel
on a line by itself to abandon it. The new clip joins whichever kind is being
browsed, so adding one under
.B "--kind templates"
creates a template.
.IP
Two renderers are available. The line renderer above is the default.
.BI --renderer " tui"
or
.B --tui
selects a full-screen list with arrow-key navigation, a live filter, a preview
of the selected clip, and
.B Tab
to switch between history and templates.
.BI --renderer " line"
or
.B --line
selects the line renderer, and
.B renderer
in the configuration file sets the default. An option on the command line
always wins.
.IP
Both renderers describe an entry with the same words. In the full-screen
renderer,
.B g
goes to an entry by number and
.B Tab
switches kind.
.IP
Because the choice is yours to make, each interface says which one it is. The
line interface opens with
.BR "Clipman line interface" ,
the full-screen interface names itself on its status line, and
.B ?
in either one describes the other.
.B "clipman-cli status"
reports the configured one as
.BR Interface: ,
which answers the question without opening either.
.IP
.B u
switches to the other interface, after a confirmation: type
.B yes
in the line interface, or press
.B y
in the full-screen one. The entry you were resting on, the active search, and
the selected kind all travel with you, and the already-downloaded history is
handed over so the switch does not wait on the network. The choice is saved as
your default. A terminal that cannot run the full-screen interface leaves you
where you are and changes nothing; a configuration file that cannot be written
costs the saved preference rather than the session.
.B pick
refuses to switch, because it offers one choice and exits.
.IP
.B v
opens the whole clip in a viewer that wraps and scrolls;
.B q
closes it.
.B ?
shows the key list in the same viewer.
.IP
.B w
saves the selected clip to a file, asking where and confirming before it
overwrites. The file is written verbatim with owner-only permissions, and a
leading
.B ~/
is expanded because there is no shell to do it.
.IP
.B x
runs a program on the selected clip. No shell is involved: what is typed is
split into a program and its arguments and run directly, so
.BR | ,
.BR > ,
.B ;
and
.B &&
are not operators, and typing one is refused with an explanation rather than
passed on as an ordinary argument. A clip is text copied from elsewhere, and
building a command line out of it for a shell would mean a clip containing
.B "; rm -rf ~"
ran when the user asked to echo it. Write
.B @clip
as an argument of its own where the clip text should go; with no
.B @clip
the clip is piped to standard input. Output is captured and shown in the
viewer, the exit status is always reported even when nothing was printed, and
.B Escape
stops a command that does not finish. On Windows a
.B .cmd
or
.B .bat
file needs its interpreter named, as in
.BR "cmd /c mytask.cmd" ,
and a program in the current directory needs an explicit path.
.B pick
refuses both
.B w
and
.BR x .
.IP
Whenever Clipman asks something, the line being typed can be edited rather than
only backspaced.
.B Left
and
.B Right
move through it,
.B Home
and
.B End
jump to its ends,
.B Delete
removes the character under the cursor, and
.B Ctrl+U
clears the line.
.B Ctrl+A
and
.B Ctrl+E
also work as
.B Home
and
.BR End .
The cursor stays on the character being edited rather than at the end of the
line, so moving back through what was typed reads it out on the way.
.IP
The cursor sits in whatever is being moved through or typed into, because a
screen reader reads the line the cursor is on. Moving through the list keeps
the cursor on the selected row, in the space just after the entry number, so
each arrow key reads out the newly selected entry; it never rests on the status
line while browsing. A question puts the cursor at the end of the answer on
the same line as the question, so the line reads
.RB \(dq "Go to entry number: 12" \(dq .
The selected row is marked with
.B ->
in the text itself rather than by colour alone.
.IP
The heading, status line, and preview sit above the list, which runs to the
bottom of the window. A terminal receives a redrawn screen from top to bottom,
so this ordering makes the entry rows the last text written on each frame.
.IP
Redrawing is kept to a minimum, because everything redrawn is sent to the
terminal again and read again. Moving through the list changes only the two
markers and the preview line, leaving the entry text, heading, and status line
untouched; the selected row carries no reverse-video highlight, which would
resend every character of two rows on each arrow key. Paging and scrolling
repaint the list, after which the cursor returns to the selected row.
.IP
Clipman does not attempt to detect a screen reader, and a terminal that cannot
run the full-screen interface is told so by name rather than silently falling
back.
.TP
.B sync
Download and validate the current server history. This stateless edition has
no offline write queue.
.SH GLOBAL OPTIONS
.TP
.BI --config " PATH"
Use a particular configuration file.
.TP
.BI --server " URL"
Override the configured server for this command.
.TP
.BI --password " VALUE"
Supply the history password. Prefer the no-echo prompt where practical because
command arguments may be visible to other software.
.TP
.BI --ca-cert " FILE"
Trust an additional PEM-encoded public authority or self-signed certificate
while retaining the operating system's normal certificate authorities. During
.B init
the public certificate is copied into the profile.
.TP
.B --insecure
Disable HTTPS certificate and hostname verification for the selected server.
This is an explicitly warned last resort for a trusted private network. It is
mutually exclusive with
.BR --ca-cert .
.TP
.B --json
Produce structured JSON where supported.
.TP
.BR --quiet , " -q"
Suppress nonessential status messages. Security warnings remain visible.
.TP
.B --verbose
Write diagnostic messages to standard error: the configuration file in use, the
server address, the short history-bucket fingerprint, and the revision and
entry count of each download. It never writes the token, the history password,
or the full database identifier.
.B --quiet
takes precedence.
.TP
.B --version
Show the CLI version.
.SH CONFIGURATION
The configuration file is found in this order, first match winning:
.IP 1. 4
the path given to
.BR --config ;
.IP 2. 4
.BR CLIPMAN_CONFIG ;
.IP 3. 4
.I config.toml
inside the directory named by
.BR CLIPMAN_HOME ;
.IP 4. 4
.I config.toml
beside the
.B clipman-cli
program, when one is present;
.IP 5. 4
the per-user default:
.I ~/.clipman/config.toml
on Linux and macOS,
.I %LOCALAPPDATA%\eClipman CLI\econfig.toml
on Windows.
.PP
On an interactive run,
.B init
asks
.RB \(dq "Save them beside this program instead, so only this copy uses them?" \(dq
after explaining that settings are normally saved for the user account and
shared by every copy. Answering yes, or passing
.BR --portable ,
writes the configuration beside the program, so that copy keeps its own
settings and two builds can use two servers without interfering. The question
is skipped when
.BR --config ,
.BR CLIPMAN_CONFIG ,
or
.B CLIPMAN_HOME
has already named a location, and on
.B --non-interactive
runs. The file is adopted only once it exists, leaving an ordinary
installation on the per-user location. The search covers the directory holding the
program, never the current working directory: a configuration file names a
server and carries a token, so an unrelated
.I config.toml
must not take over a session.
.PP
.B clipman-cli status
reports which configuration is in use on its first line, and as
.B config_path
under
.BR --json .
.PP
The history password is resolved from
.BR --password ,
.BR CLIPMAN_PASSWORD ,
saved configuration when explicitly enabled, or a no-echo prompt on the
controlling terminal.
.SH SECURITY
Encrypted CLIPDB2 data is authenticated before decryption or decompression.
The client enforces database, JSON, nesting, entry-count, tombstone-count, and
text-size limits. It does not print server tokens, passwords, full database
identifiers, or clip text in diagnostics.
.PP
On Windows, saved tokens and passwords are encrypted with DPAPI for the
current user. On Linux and macOS there is no equivalent encryption yet: an
explicitly saved history password (or token) on those systems is written in
plain text into the owner-only configuration file (directory mode 0700, file
mode 0600), protected only by file permissions.
.PP
The clipman scheme 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.
.PP
A private authority imported from a current connection file is host-bound and
exclusive to that server profile. The manual
.B --ca-cert
option remains additive for older setups. Treat every connection file as a
credential because it contains the server token.
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
Local input, output, or data-format failure, and anything not covered below.
.TP
.B 2
Usage, selection, or confirmation error.
.TP
.B 3
Configuration, permission, or server-authentication error.
.TP
.B 4
Network, TLS, or server failure, including timeouts, unreachable servers, and
HTTP 413 or 5xx.
.TP
.B 5
History password required or incorrect, or database authentication failed.
.TP
.B 6
Requested entry or database not found.
.SH FILES
The release package gives every platform its own directory and names the
program
.B clipman-cli
inside each one, so installing it is a move rather than a rename. The
directories are
.IR windows-amd64 ,
.IR windows-arm64 ,
.IR macos-amd64 ,
.IR macos-arm64 ,
.IR linux-amd64 ,
.IR linux-arm64 ,
and
.IR linux-armv7 .
.TP
.I manual/Manual.html
Accessible full manual supplied with the binaries.
.TP
.I manual/clipman-cli.1
This manual page.
.TP
.I SHA256SUMS
SHA-256 checksums for all supplied platform binaries. Run
.B sha256sum -c SHA256SUMS
from the package root to verify them.
.TP
.I LICENSE.txt
MIT License terms.
.SH PROJECT
https://github.com/OnjLouis/Clipman
.SH LICENSE
MIT License.