Zynk CLI

Troubleshooting

Fix common Zynk CLI issues with install paths, config, identity, contacts, sending, receiving, daemon mode, JSON output, notifications, completions, shares, and state.

Start with what you see

Match the visible symptom first, then run the smallest check that separates install, config, target, transfer, daemon, and automation problems.

Symptom: zynk: command not found
Run first: ./zynk --version
What the result means: If the local binary works, the problem is PATH or shell refresh.
Then go to: PATH and install

Symptom: macOS blocks a manual download
Run first: xattr -p com.apple.quarantine ./zynk
What the result means: If the attribute exists, remove it before running the binary.
Then go to: PATH and install

Symptom: Wrong account or device
Run first: zynk about
What the result means: If the phone number or device name is wrong, inspect config before networking.
Then go to: Config and identity

Symptom: Contact or own device is not accepted
Run first: zynk contacts or zynk devices
What the result means: Contacts and own-device IDs use different selectors.
Then go to: Contacts and devices

Symptom: Send target is ambiguous
Run first: zynk send +15551234567 report.pdf
What the result means: A phone number removes contact-name ambiguity.
Then go to: Sending

Symptom: Expected receive is missing
Run first: zynk pending --all
What the result means: If the row appears only with --all, the default 24-hour window hid it.
Then go to: Receiving

Symptom: One-shot commands feel stale
Run first: zynk daemon status
What the result means: A running daemon may still be using old config or state.
Then go to: Daemon

Symptom: A wrapper cannot parse output
Run first: zynk pending --json-output
What the result means: Only specific commands promise machine-readable JSON.
Then go to: Automation and extras

Symptom	Run first	What the result means	Then go to
`zynk: command not found`	`./zynk --version`	If the local binary works, the problem is PATH or shell refresh.	PATH and install
macOS blocks a manual download	`xattr -p com.apple.quarantine ./zynk`	If the attribute exists, remove it before running the binary.	PATH and install
Wrong account or device	`zynk about`	If the phone number or device name is wrong, inspect config before networking.	Config and identity
Contact or own device is not accepted	`zynk contacts` or `zynk devices`	Contacts and own-device IDs use different selectors.	Contacts and devices
Send target is ambiguous	`zynk send +15551234567 report.pdf`	A phone number removes contact-name ambiguity.	Sending
Expected receive is missing	`zynk pending --all`	If the row appears only with `--all`, the default 24-hour window hid it.	Receiving
One-shot commands feel stale	`zynk daemon status`	A running daemon may still be using old config or state.	Daemon
A wrapper cannot parse output	`zynk pending --json-output`	Only specific commands promise machine-readable JSON.	Automation and extras

Diagnostics and state

Before changing files, record the config, state, daemon, and log paths involved in the failing run.

Collect diagnostics

$ zynk config pathConfig directory: <config-dir>User config file: <user-config-file>System config file: <system-config-file>$ zynk show-state-dir<state-dir>$ zynk daemon statusZynk daemon is running  PID:       <pid>$ zynk daemon statusZynk daemon is not running.  Socket:    /tmp/zynk.sock$ tail -f <daemon-log-path>

Use the daemon log path printed when daemon mode starts. If status says the daemon is not running and you did not start it, there may be no daemon log to follow.

State checks

config path shows the config files Zynk can read.
show-state-dir shows the default or flag-selected state directory for this run.
daemon status shows whether routed commands may be talking to a background process.
The daemon prints its log path at startup; use that path when following daemon lifecycle output.

Bug reports

Include the command you ran, OS, shell, Zynk version, config path, state path, daemon status, and the smallest failing example.
Redact phone numbers, peer IDs, contact names, local file paths, share/drop links, and any auth codes before sharing logs.
Keep stdout and stderr separate when reporting automation failures.

PATH and install

If zynk is not found after installation, first prove the downloaded binary works, then refresh the shell path.

Confirm PATH setup

$ ./zynk --versionzynk <version>$ ./zynk install$ zynk --versionzynk <version>

A version line from ./zynk means the binary works. A version line from zynk means PATH also works.

Checks

Run the binary directly as ./zynk to confirm it works before debugging PATH.
After zynk install, restart the terminal or run the printed source ... command.
Unix installs to ~/.local/bin/zynk.
Windows installs to %USERPROFILE%\.zynk\bin\zynk.exe.

Shell-specific notes

Unknown shells may need a manual PATH update.
Fish uses ~/.config/fish/conf.d/zynk.fish, not config.fish.
On macOS, browsers attach com.apple.quarantine to manual downloads. If Gatekeeper blocks ./zynk, run xattr -d com.apple.quarantine ./zynk and try again.
On Windows, Unblock-File .\zynk.exe clears the browser download marker for a manually downloaded binary.
Windows PATH is updated in the current user's environment registry key.

Config and identity

Most confusing first-run failures are config or account identity failures. Verify the active config before debugging networking.

Find the active config

$ zynk aboutUser ID:        +15551234567Device Name:    Work LaptopPlatform:       macOSPeer ID:        12D3KooWabc...CLI Version:    1.3.2Daemon:         Disconnected$ zynk show-default-config-pathConfig directory: <config-dir>User config file: <user-config-file>System config file: <system-config-file>$ zynk --config /path/to/zynk.conf about~/Zynk> sendauth sms~/Zynk> verifyauth <code>~/Zynk> verifynewdevice <code>

If about shows the wrong account, edit the config file that wins for this run or pass --config explicitly. If the account is right but this device is not verified, repeat the auth-code flow.

Config checks

about shows the current account and device.
show-default-config-path shows which config files Zynk will read.
config path shows config locations through the newer nested command.
--config points one command at a specific config file.

Identity checks

Phone numbers must start with + and contain digits only.
A missing config can be created by zynk install or by passing --user +1234567890.
Wrong account symptoms usually show up first in about, devices, and contacts.
If about has no account or shows the wrong account, fix config before retrying sends.

Auth recovery

Use sendauth <type> again when an auth code expired or was mistyped.
Use verifyauth <code> for account verification in the interactive shell.
Use verifynewdevice <code> when the account exists but this device still needs approval.

Contacts and devices

If a send cannot resolve the target, separate the problem into people and devices before trying to send again.

Resolve a target

$ zynk aboutUser ID: +15551234567$ zynk contacts ALLNo contacts found.$ zynk contacts ZYNK janeNo contacts found with the searched name.$ zynk set-contact +15557654321 Jane$ zynk devicesID    NAME          PEER ID          LAST SEEN    OS5o4   Work Laptop   12D3KooWabc...  just now     macOS$ zynk devicesNo devices found.$ zynk send my:"Work Laptop" report.pdf

Use my:devicename (or --my <id> with the short ID from zynk devices) to target a device under your own account. Use a contact name or phone number for another person.

Contact search

contacts with no arguments lists Zynk contacts.
contacts ALL lists all contacts.
contacts ZYNK is explicit Zynk-only mode.
contacts ZYNK jane searches inside Zynk contacts.
If contacts ZYNK is empty but contacts ALL has the person, use set-contact or send to the phone number directly.

Device search

devices lists your linked devices.
Send with my:devicename (or pass the short ID via --my <id>) to target a device under your own account.
Do not use my: or --my for contacts or phone numbers.
If devices is empty or only shows this machine, confirm the other device is installed, signed in, and linked to the same account.

Sending

Send failures are easiest to inspect when destination resolution and file selection are handled separately.

Check sends

$ zynk send +1234567890 report.pdfSuccessfully requested File send to +1234567890$ zynk list-uploadsID    NAME         SIZE      STATUS        RECIPIENT17    report.pdf   842 KB    transferring  +1234567890$ zynk cancelID    NAME         STATUS        DIRECTION17    report.pdf   transferring  upload$ zynk cancel all

The success line means the send request was accepted locally. It does not prove the recipient has received or saved the file yet.

Send checks

Start with one path and one explicit destination.
Use a phone number when a contact name is ambiguous.
Use my:devicename (or --my <id>) only for a device under your own account.
When piping paths, confirm the upstream command prints the paths you expect.
If the target cannot be resolved, stop here and fix contacts/devices before retrying transfer recovery.

Active transfers

list-uploads / lu shows upload progress.
If the upload row shows progress or a queued/transferring state, leave the sender running and inspect receiver state.
If the upload row shows a failed, refused, cancelled, or terminal state, cancel stale rows and send again from an explicit path.
If the file path is missing or unreadable, fix disk permissions or path spelling before retrying.
cancel lists cancellable transfers when no target is provided.
cancel all cancels every active transfer.

Receiving

If an expected receive is not visible, the default time window is the first thing to check.

Check receives

$ zynk pending --since 3dID    NAME           SIZE      STATE      SENDER0     report.pdf     842 KB    pending    Alice$ zynk pending --contact NobodyNo pending transfers.$ zynk accept 0 ~/DownloadsAccepting file transfer from Alice: report.pdf to ~/DownloadsPlease use showprogress|sp to see the file's progress$ zynk list-downloadsID    NAME         SIZE      STATUS        SENDER42    report.pdf   842 KB    transferring  Alice

pending --all is the broadest inbox check. If the transfer appears there, accept by visible row ID or by an explicit transfer ID shown in JSON/status output. If the accepted download fails, check the save directory and daemon logs before retrying.

Find the transfer

pending defaults to the last 24 hours.
pending --since 3d expands the window.
pending --all removes the time filter.
pending --contact Alice filters to one sender.
If pending --all is empty, the sender has not reached this account/device or the transfer already moved out of pending.

Accept the right transfer

accept accepts the newest pending transfer.
accept 0 ~/Downloads accepts the transfer at index 0.
accept --transfer-id <ID> ~/Downloads avoids index ambiguity.
accept --from Alice ~/Downloads accepts every pending transfer from one sender.
list-downloads shows active downloads after acceptance; failed rows usually point to disk/path or network recovery.

Stuck transfers

A stuck transfer can be target resolution, pending approval, moving upload/download progress, disk/path failure, or stale state. Use the table row and progress/status wording before retrying.

What you see: send cannot resolve the name
Likely state: Unresolved target
Next action: Run contacts, contacts ALL, devices, or send to the phone number directly.

What you see: Sender says requested/queued, receiver sees a pending row
Likely state: Pending receive
Next action: Accept with accept <row> <directory> or an explicit --transfer-id from machine output.

What you see: list-uploads shows progress, queued, transferring, or paused wording
Likely state: Upload has not finished
Next action: Keep the sender online and check receiver pending or list-downloads.

What you see: list-downloads shows progress, queued, transferring, or paused wording
Likely state: Download has not finished
Next action: Keep the receiver online and confirm the destination directory is writable.

What you see: A row shows failed, refused, cancelled, or other terminal failure wording
Likely state: Terminal transfer state
Next action: Fix the cause, cancel stale rows if needed, then retry from an explicit path.

What you see: Accept fails with a path error
Likely state: Disk or permission issue
Next action: Choose a writable directory and retry the accept command.

What you see: Status is unclear after a daemon restart
Likely state: Stale daemon or state view
Next action: Run daemon status, inspect logs, then daemon kill and restart only if you want daemon mode.

What you see	Likely state	Next action
`send` cannot resolve the name	Unresolved target	Run `contacts`, `contacts ALL`, `devices`, or send to the phone number directly.
Sender says requested/queued, receiver sees a pending row	Pending receive	Accept with `accept <row> <directory>` or an explicit `--transfer-id` from machine output.
`list-uploads` shows progress, queued, transferring, or paused wording	Upload has not finished	Keep the sender online and check receiver `pending` or `list-downloads`.
`list-downloads` shows progress, queued, transferring, or paused wording	Download has not finished	Keep the receiver online and confirm the destination directory is writable.
A row shows failed, refused, cancelled, or other terminal failure wording	Terminal transfer state	Fix the cause, cancel stale rows if needed, then retry from an explicit path.
Accept fails with a path error	Disk or permission issue	Choose a writable directory and retry the accept command.
Status is unclear after a daemon restart	Stale daemon or state view	Run `daemon status`, inspect logs, then `daemon kill` and restart only if you want daemon mode.

Daemon

Daemon problems are usually lifecycle or routing expectations. Start with status, then logs, then a clean restart.

Reset daemon mode

$ zynk daemon statusZynk daemon is running  PID:       <pid>  Socket:    /tmp/zynk.sock$ zynk daemon kill$ zynk --run-mode server

If status says the daemon is not running, one-shot commands should still run directly. Kill and restart only when you actually want daemon mode.

Daemon checks

daemon status confirms whether the daemon is running.
daemon status --json-output gives scriptable status.
daemon kill stops a stale daemon before a fresh start.
--dry-run bypasses daemon routing by design.

Routing checks

A command that cannot connect to the daemon should still run directly.
Commands such as install, update, completions, and config-path inspection do not route through the daemon.
Check the daemon log path printed at startup for lifecycle details.

Automation and extras

Some problems are not transfer problems at all: machine output, shell setup, desktop notifications, or clipboard integration.

Check automation and extras

$ zynk pending --json-output{"type":"pending","data":{"count":0,"transfers":[]}}$ zynk daemon status --json-output{"type":"daemon_status","data":{"running":false,"pid":null,"user":null,"uptime_secs":null,"socket":"/tmp/zynk.sock","socket_exists":false,"lock_file":"<lock-file>"}}$ zynk pending --json-output{"type":"error","code":"<error-code>","message":"<message>"}$ zynk completions zsh > ~/.zsh/completions/_zynk$ zynk share ls --full --verbose

JSON output

--json-output is global but command support is per-command.
Do not assume every command emits stable JSON.
pending --json-output and daemon status --json-output are the first automation-safe surfaces to verify.
On errors, check the top-level type, the process exit code, and stderr separately.

Notifications, completions, and links

If notifications do not appear, inspect [notifications] config keys.
If completions do not load, regenerate for the correct shell.
If share/drop links do not copy, check copy-links and clipboard utility availability.