Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

3.2 KB
Raw Blame

CLI queries and JSON output

PasteFerry 2.9 adds a version command and structured read-only queries to the existing desktop CLI. These queries use the same authenticated local RPC connection as the desktop app. The CLI controls an existing background service; it does not install or start one.

Commands

Global flags must precede the command. Both -json and --json are accepted.

pasteferry-cli version
pasteferry-cli -json version
pasteferry-cli -json status
pasteferry-cli -json devices
pasteferry-cli -json history
pasteferry-cli -json config
pasteferry-cli -json config get
pasteferry-cli -json -data-dir /path/to/running-instance status

version reports the CLI executable version without contacting a service. status reports the service version, which can differ from the CLI version. config get is an alias for config, including in text mode.

Response format

Each JSON invocation writes one JSON object followed by a newline to stdout. Success has exit code 0:

{"ok":true,"data":{"version":"2.9.0"}}

Failures have a nonzero exit code and an error description:

{"ok":false,"error":"daemon 未运行(找不到 /path/to/daemon.json)"}

Errors from supported queries, invalid arguments and unsupported JSON commands use this envelope. Global flag parsing stops at the command, as with Go's standard flag parser; put -json before other flags to request JSON errors for invalid flags as well. JSON mode does not write diagnostic text to stderr. Error descriptions are intended for people and should not be parsed as codes.

Query data contents
version version: the CLI version string
status pid, port, and daemon: the RPC Status message
devices The RPC ListDevicesResponse, including self and peers
history The RPC ListHistoryResponse, including records
config [get] The RPC Config message

RPC messages follow ProtoJSON: field names use snake_case, booleans remain booleans, enums use their full names (for example CONNECTION_KIND_DIRECT), and 64-bit integers use decimal strings to preserve precision in JavaScript. Default scalar fields are included. Empty repeated fields are [], and absent optional messages are null. Consumers should tolerate additional fields in future versions.

For example, no paired devices produces data.peers: []; no history produces data.records: []. History returns up to 20 recent record summaries, matching the existing text command, and does not fetch file content or alter the clipboard. The endpoint authentication token is never included in the output.

The data fields are defined in proto/pasteferry/v1/daemon.proto. Each RPC request has a five-second deadline, including configuration queries.

Compatibility and scope

Without -json, existing commands keep their human-readable output and behavior. JSON mode supports only the queries listed above. Commands that pair devices, change settings, write the clipboard or modify history are rejected before any RPC call. Existing text-mode operation commands remain available.

The new CLI can query an existing 2.8.3 service. There are no device protocol or server changes in this feature.