CLI Reference

This is the full uniclip subcommand reference. New to the CLI? Start with the CLI overview.

Members

uniclip devices is an alias for uniclip members. Both honour --json for scripting.

Join requests

Without --no-wait, uniclip join waits for a final result. Ctrl-C stops only that local wait; use join cancel when the request itself should be cancelled.

Device trust changes

Scripts and JSON callers must pass --change <CHANGE-ID> to bind the choice to the change they inspected. Applying a change that removes the local device also requires --confirm-local-removal.

Per-member sync

<DEVICE> can be a device ID, or an unambiguous device name in an interactive terminal. set accepts --send on|off, --receive on|off, and comma-separated --send-types / --receive-types values; use all or none for every type or no types.

Sending and watching

# Send text to every online paired device
uniclip send "hello from the CLI"

# Or pipe stdin
echo "from a heredoc" | uniclip send

# Restrict fan-out to specific devices (repeatable)
uniclip send "scoped message" --peer DEVICE_ID_A --peer DEVICE_ID_B

# Re-fan-out a previously captured local entry. No stdin / positional
# text is read. Without `--peer`, targets default to the diff of
# trusted peers minus those that already received this entry.
uniclip send --resend <ENTRY_ID>

# Watch inbound clipboard payloads as they arrive (Ctrl-C to stop)
uniclip watch

--resend only re-fans-out entries that were captured locally and whose payload is still cached. Entries originating on a remote peer cannot be re-sent from this device; combine --resend with --peer ... to force a specific fan-out target.

uniclip watch is a diagnostic observer: it prints the first text representation (or a per-rep summary for image-only payloads) but does not write the system clipboard — that's the daemon's job.

Sending and receiving files

# Sender: dispatch a file to paired peers via the daemon's blob
# pipeline. The daemon handles blob storage and transfer — the CLI
# exits once the dispatch is acknowledged.
uniclip send -f ./big-file.bin

# Receiver: wait for the first inbound file, export it from the
# daemon's cache, and write it to disk (defaults to cwd; pass --out
# for a different directory). Ctrl-C to stop waiting.
uniclip recv --out ./inbox

send -f is mutually exclusive with positional text and --resend. The daemon handles blob storage and peer-to-peer transfer, so the CLI can exit as soon as the dispatch is confirmed.

Reading already-synced entries

recv waits for the next inbound file. To read what is already in the daemon's history — the common case on a headless / SSH box with no system clipboard to paste from — use get, which returns immediately.

# Newest usable entry (text/link prints to stdout)
uniclip get

# Newest entry of a kind: image | file | text | link
uniclip get --type image

# A specific entry by id (from `uniclip search`), into a directory
uniclip get --id <ENTRY_ID> --out ./inbox

# Browse recent entries instead of materializing one
uniclip get --list -n 20

Output contract: text / link content is printed to stdout (pipe-friendly). A trailing newline is appended only when stdout is an interactive terminal, so piped or redirected output stays byte-exact; image / file bytes are written to --out (a directory, defaulting to a per-user cache dir) and the absolute path is printed to stdout, or streamed to stdout with --out -. Status lines go to stderr, so stdout stays clean. Unlike recv, get never blocks.

Search

uniclip search exposes the encrypted full-text index that backs the GUI dashboard search.

uniclip search status                    # is the index ready / building?
uniclip search rebuild                   # rebuild from history (synchronous)
uniclip search "report"                  # default query
uniclip search "report" \
    --type text --ext md \
    --limit 20 --detailed
uniclip search "report" \
    --from-ms 1710000000000 --to-ms 1710100000000
uniclip search "report" \
    --source-device "Laptop"             # only clips from that device

--source-device filters by the device a clip arrived from. It accepts a device name (case-insensitive) or a device id and is repeatable; run uniclip members to see the available names. --detailed (and --json) output includes each result's source device id.

rebuild blocks until the rebuild finishes; useful when scripting a diagnostic snapshot.

Blob (large-payload) diagnostics

Note: blob, probe, and dev subcommands are only available in development builds (dev-tools feature). Release binaries do not include them.

uniclip blob is the headless interface to the chunked-blob pipeline described in Sync content.

# Publish a local file as an encrypted blob and print its ticket
uniclip blob publish ./sample.bin

# Fetch a blob by ticket + entry ID into a local file
uniclip blob fetch <TICKET> --entry-id <ENTRY_ID> --out ./restored.bin

Useful when debugging file-sync failures or verifying a peer can reach blob storage.

Mobile sync

uniclip mobile ... is the CLI surface for the mobile companion feature. It mirrors the Devices → Mobile sync panel in the GUI and the protocol is documented in the Mobile LAN API.

# One-shot wizard: turn the feature on, configure the LAN listener,
# register one iPhone, print the install QR + a one-time password.
uniclip mobile setup

# Read-only view (allowed while the daemon is running)
uniclip mobile status            # combined: feature + LAN + paired devices

# Paired device management
uniclip mobile add --label "My iPhone" \
    [--username my_user] [--password-stdin]
uniclip mobile revoke <device-id>

# Advanced listener configuration (write commands — daemon must be stopped).
# `setup` already covers the common case; reach for these to re-point the
# address or front the listener with a reverse proxy.
uniclip mobile network interfaces
# LAN form: advertise an internal IPv4 → install URL is http://<IP>:<port>
uniclip mobile network set --ip <LAN_IPV4> [--port 42720] --accept-network-risk
# Reverse-proxy form: advertise a full base URL → install URL/QR points at
# the HTTPS front-end (e.g. Caddy), while the listener stays plain HTTP.
uniclip mobile network set --url https://clip.example.com --accept-network-risk
uniclip mobile network off       # stop just the LAN listener

# Disable the feature entirely (master switch + listener off; paired
# device records stay until you `revoke` them).
uniclip mobile disable

Behavioural notes:

• Write commands refuse to run while a same-profile daemon is up. Stop the daemon (uniclip stop / quit the GUI) before running setup, add, network set, etc. The read command (status) is tolerant of a running daemon.
• --json implies non-interactive. No prompts will be shown. setup in non-interactive / JSON mode requires --label and --accept-network-risk. --ip / --port are optional advanced pins (omit them and the QR carries every detected interface). --username / --password-stdin remain optional and default to auto-mint.
• --password-stdin reads exactly one line from stdin. Use it to pipe a password from a manager / CI without leaving it in shell history.
• Default port is 42720 (SPEC §3.2). The daemon socket always binds to 0.0.0.0:<port>; --ip only chooses the IPv4 that is printed to the install URL.
• network set requires exactly one of --ip <IP> or --url <URL>. --ip produces the LAN form http://<IP>:<port>. --url embeds a full base URL (scheme + host + optional port) such as https://clip.example.com, so the install URL / QR points at a TLS reverse proxy (Caddy, nginx, …) while the listener itself stays plain HTTP on the internal network. The two are mutually exclusive and setting one clears the other; mobile status reflects whichever is active.
• A debug subcommand group exists (uniclip mobile debug) but is hidden from --help — it is reserved for development and E2E scripts (it bypasses HTTP and pokes the facade directly), and may change without notice.

For a step-by-step setup walkthrough — listener risks, iOS Shortcut install, password rotation — see the Mobile sync guide.

Debug & log export

uniclip debug status                       # is persistent debug logging on?
uniclip debug on                           # enable verbose local logging
uniclip debug off                          # back to the normal profile
uniclip debug export-logs                  # zip the last 24h to Downloads
uniclip debug export-logs --since-hours 6  # narrow the window

debug on / off persists a more verbose logging profile across restarts; status reports the effective profile and whether a restart is still required for the change to fully take effect. Clipboard content is still not logged.

export-logs collects the GUI, daemon, and CLI logs from the recent window (default 24h) into a single zip in your Downloads folder — the fastest way to gather everything an issue report needs. The same action is available in the GUI under Settings → General.

Upgrade-detection cursor

uniclip upgrade            # bare command prints status
uniclip upgrade status     # same as the bare command
uniclip upgrade ack        # advance the cursor to the current build

Inspects or advances the upgrade-detection cursor — exposed for manual verification of the upgrade module. Most users never need this.

Hidden commands

The following commands exist but are deliberately hidden from uniclip --help:

• uniclip probe ... — clipboard-diagnostic group (replaces the old clipboard-probe binary). The only CLI path that writes the system clipboard, and only via probe restore. Development and E2E only.
• uniclip dev seed-clipboard --text <TEXT> — debug seeding for switch-space data-integrity tests.
• uniclip dev dump-clipboard --limit <N> — debug printing of decrypted history.
• uniclip dev capture-files --path <PATH> — captures one or more files or directories through the real local-capture pipeline and prints the persisted file-set manifest. Repeat --path for mixed selections. --max-members and --max-bytes temporarily override the file-set caps for this capture only; the override is not written back to the profile's settings.
• uniclip dev pairing ... — pairing-invitation diagnostics: addrs lists candidate addresses after the product filter has run, and issue --addr <IP> issues an invitation constrained to one local IP. Refuses to run while the daemon is up. Intended for triaging pairing failures on virtual-NIC setups.
• uniclipd — the background daemon, shipped as a separate binary (no longer a uniclip daemon subcommand). uniclip start and the desktop app spawn it for you; you'll see it in ps, but don't launch it directly.

These won't show up in shell completion or --help, and may change without notice. They're documented here so you don't think you're seeing things in ps or in commit history.

Exit codes

uniclip uses stable exit codes (defined in the source under src/exit_codes.rs). 0 is success; non-zero values map to distinct failure classes (configuration, network, pairing, etc.) and are stable across releases. Scripts should branch on exit code rather than parse human-readable output.

uniclip get additionally uses 6 when no entry matched the selector, and 7 when an entry matched but its payload is unavailable (Lost or not yet downloaded — re-send it from the source device).

For the most up-to-date list of subcommands, run uniclip --help — the binary's help is the source of truth.