Zynk CLI

JSON output and errors

How to read --json-output records, which fields each result carries, and what the CLI reports when something fails.

Reading a command result

Zynk writes one JSON object per line. This format is called NDJSON. Read all the lines and check whether the command succeeded.

JSON records go to standard output. Keep standard error separate for diagnostics. Ignore extra fields and unrelated record types so additions do not break your script.

Save the output and check success — Bash

if zynk --json-output devices > devices.jsonl; then  jq 'select(.type == "devices") | .data' devices.jsonlelse  cat devices.jsonl >&2  exit 1fi

This checks Zynk’s exit status before reading the result. A successful JSON parser alone does not prove that Zynk succeeded.

Exit status
0
Meaning
The command completed successfully. For send, this confirms submission, not delivery.
Exit status
Nonzero
Meaning
Failure, partial success, or an unknown outcome. Read the saved records to tell which.

Send results

A send can print several JSON records. Match them using data.transfer_id, then check the command’s final exit status.

Acknowledged submission — illustrative ID

{"type":"send_result","data":{"transfer_id":"example-id","outcome":"submitted"}}

Check current uploads

$ zynk --json-output list-uploads --ids
Record
send_queued
Meaning
The request was sent; the final answer has not arrived.
Next step
Keep the transfer ID.
Record
send_result with submitted
Meaning
Zynk acknowledged submission.
Next step
Keep the ID; recipient delivery may happen later.
Record
send_result with rejected
Meaning
Zynk rejected submission.
Next step
Read the error before trying again.
Record
Command fails after queueing, with no final result
Meaning
The outcome is unknown.
Next step
Check uploads before retrying to avoid a duplicate.

JSON fields

Read type first. Normal results put command-specific values inside data.

No devices is a successful empty result

$ zynk --json-output devices{"type":"devices","data":[]}
Command
pending
Type
pending
Useful fields
data.count and data.transfers. Transfer rows include an ID when available, a name, state, and index. Use stable IDs in scripts because indexes can change.
Command
pending --include-messages
Type
pending
Useful fields
Also includes data.messages. Use --all or --since to choose the time window.
Command
daemon status
Type
daemon_status
Useful fields
data.running tells you whether the daemon is running. Other fields describe its process and socket.
Command
config path
Type
config_paths
Useful fields
data.config_dir, data.user_config, and data.system_config.
Command
show-state-dir
Type
state_dir
Useful fields
data.path is the state directory selected for this run.

Errors

Error records have top-level code and message fields. They do not use the normal data field.

Invalid files, unusable destinations, signed-out state, and missing or malformed configuration return structured errors and failure exit codes. A nonzero exit can also mean partial success or an unknown outcome, so read all the records before deciding what to retry.

Error shape — illustrative message

{"type":"error","code":"invalid_path","message":"The selected file could not be used."}

Recipient records

The send_queued record keeps the destination you typed and the user or device identity used for the request. Use these fields when saving a send log.

Only the applicable identity field is present. target_user_id is a string containing a serialized handle, such as {"Email":"[email protected]"}. It is not an account UUID.

Field in data
requested_destination
Meaning
The destination supplied on the command line.
Field in data
target_user_id
Meaning
The serialized user handle sent to core for a user/account-wide send.
Field in data
target_peer_id
Meaning
The peer ID sent to core for a specific-device send.
Field in data
target
Meaning
The display name. It can be Unknown, so do not use it alone as an identity.