Getting Started

uniclip is the terminal client for UniClipboard. It connects to the same background service as the desktop app, so the CLI and GUI can use the same profile and space. If a command needs the service and it is not running, uniclip starts the matching uniclipd automatically.

If uniclip --version does not work yet, start with Install the CLI.

Global options

These options work with every public command:

Option	Effect
`--json`	Return machine-readable JSON for scripts.
`-v`, `--verbose`	Show more diagnostic output in the terminal.
`--profile <NAME>`	Use an isolated data set, secure-storage entry, and network identity.

You do not need a separate profile just because the desktop app is open. Use --profile only when you intentionally want an independent instance, such as two test devices on one computer.

Create or join a space

Create a space, then issue an invitation for another device:

uniclip space init
uniclip space invite

Both commands guide you through the required input. Treat the invitation as a short-lived secret and use it only once.

Run the join command on the new device. You can paste the invitation when prompted:

uniclip space join

For a non-interactive command, pass it explicitly:

uniclip space join --code <INVITATION_CODE>

The command also asks for the space passphrase and waits for the final result. After it succeeds, check the member list:

uniclip member list

Use --no-wait when a script should return after the join request is accepted. You can then inspect or cancel that request:

uniclip space join status
uniclip space join cancel

Pressing Ctrl-C stops only the local wait; it does not cancel the request.

Send and read content

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

# Send an existing regular file (auto-detected)
uniclip send ./report.pdf

# Force an existing filename to be sent as text
uniclip send --text report.pdf

# Read text from standard input
printf 'hello from a pipe' | uniclip send

# Print the newest already-synced text or link
uniclip get

# Wait for the next synced entry, then print it and exit
uniclip get --wait

# Wait for the next entry and copy it through the active terminal
uniclip get --copy --wait

# List recent entries without downloading one
uniclip get --list -n 20

# Search history
uniclip search "report"

By default, get returns content that is already in local history without waiting. get --wait handles the next matching delivery that arrives after the command subscribes and exits. It can be combined with --type or --id. Interactive terminals show real receive progress for a matched file; progress stays on stderr, so stdout remains safe for pipes and JSON. watch prints all future deliveries until you press Ctrl-C:

uniclip watch

The watcher is an observer; it does not write content into the system clipboard.

Send or receive a file

# Explicitly force file mode
uniclip send --file ./report.pdf

# Read complete file paths from stdin, one per line
printf '%s\n' ./report.pdf './images/cover art.png' | uniclip send --file

# Wait for the next incoming entry; files are saved under ./inbox
uniclip get --wait --out ./inbox

Existing regular files are detected automatically. File sending is owned by the daemon, and the command exits after all relevant targets reach a terminal state. When -f / --file has no positional path, stdin is a list of file paths, not file contents. Blank lines are ignored, paths are validated before sending, and duplicate paths are sent once. Use repeatable --peer flags to restrict the targets; Ctrl-C cancels the wait.

Manage the daemon

Most commands connect to the current profile's daemon or start one when needed. For explicit lifecycle control:

Command	Effect
`uniclip run`	Run in the foreground, preserving signals, logs and the daemon exit code.
`uniclip run --server`	Run a foreground headless node without the system clipboard.
`uniclip service start`	Install if needed and start a user service, enabled at login.
`uniclip service status`	Report registration, running state and HTTP health separately.
`uniclip service restart`	Restart with saved options and restore login startup.
`uniclip service stop`	Stop and disable login startup, retaining the service definition.
`uniclip stop`	Stop a standalone daemon for the active profile.
`uniclip space status`	Show space, network and trust status.

User services support Linux systemd and macOS launchd; Windows service commands report unsupported. service start --server selects headless operation. Install matching uniclip and uniclipd in a stable directory before creating a production service. Temporary builds, Git worktrees and portable installs cannot be used for production services.

run refuses an existing daemon, including one owned by the desktop app; stop its owner explicitly or use another --profile. Use service stop for a service-managed daemon. Services start when the user's login manager starts; this does not promise startup before login. See CLI reference for health failures and service requirements.

uniclip start is deprecated. During compatibility it still defaults to background operation and prints a migration warning; --foreground and --server retain their previous behavior. New scripts should use run or service start.

Use the CLI in scripts

Add --json when another program consumes the result:

uniclip --json space status
uniclip --json member list
uniclip --json search "report" --limit 10

Human-readable status messages go to standard error where commands need to keep standard output clean. Scripts should use JSON and the command's exit status instead of matching terminal wording.

Switch or rebuild a space

Switching to a different space migrates readable local history to the new space:

uniclip space join --switch --code <NEW_INVITATION_CODE>

The command asks for confirmation. Add --yes only in a controlled, non-interactive workflow. If some local records cannot be read, the command stops by default; --preserve-unreadable-history keeps those records instead of dropping them during the switch.

To rebuild the current device as a new one-device space:

uniclip space reset --yes

This permanently discards the old pairing, trust, and sync relationships but keeps local history, completed files, settings, device identity, and unlock access. Every device must pair again. This is not a factory reset.

Reset keeps the current passphrase. To change it, use uniclip space change-passphrase (only for an unlocked space where this device is the only member). uniclip space init is for a device that has no space yet and fails with "setup has already been completed" after a reset.

See the CLI reference for all public commands and options.