Zynk CLI

Command reference

Find the Zynk CLI command you need by task: transfers, inboxes, identity, messages, usage, progress, sharing, config, daemon control, and flags.

Command forms

Start from the task, then check where the command runs. Most daily actions work as one-shot commands; repeated file selection, shares, drops, shared folders, and several account helpers live in the interactive shell.

Read command help

$ zynk --help$ zynk send --help$ zynk help accept~/Zynk> help --search pending

Prompt markers

  • Lines that start with $ are one-shot commands. They run one action and return to your shell.
  • Lines that start with ~/Zynk> run inside the interactive Zynk shell.
  • Some interactive aliases do not exist as one-shot subcommands. pd is an alias for pending only inside the shell.
  • If you have not installed or signed in yet, start with Setup before using this reference.

Help entry points

  • zynk --help shows top-level one-shot commands and global flags.
  • zynk <command> --help shows one-shot command syntax.
  • zynk help <command> opens the interactive help entry when that command is in the shell registry.
  • help --search <term> searches command names, notes, examples, and tips inside the shell.

Command index

Use this index when you know the command name and need the right section, alias, or execution surface.

Command
send
Aliases
Runs as
one-shot, shell
Use it for
Send files, folders, or stdin path lists.
Command
pending
Aliases
pd in shell
Runs as
one-shot, shell
Use it for
List incoming transfers waiting for approval.
Command
accept
Aliases
a
Runs as
one-shot, shell
Use it for
Accept the latest, indexed, explicit, or bulk pending transfer.
Command
list-uploads
Aliases
lu
Runs as
one-shot, shell
Use it for
Inspect active uploads.
Command
list-downloads
Aliases
ld
Runs as
one-shot, shell
Use it for
Inspect active downloads.
Command
cancel
Aliases
Runs as
one-shot, shell
Use it for
Cancel selected or all active transfers.
Command
pause
Aliases
Runs as
shell
Use it for
Pause one transfer or all transfers.
Command
resume
Aliases
Runs as
shell
Use it for
Resume one transfer or all transfers.
Command
showprogress
Aliases
sp
Runs as
shell
Use it for
Toggle or show transfer progress.
Command
about
Aliases
Runs as
one-shot, shell
Use it for
Confirm active account, device name, peer ID, and version info.
Command
devices
Aliases
Runs as
one-shot, shell
Use it for
List your devices and copy the short own-device ID.
Command
contacts
Aliases
Runs as
one-shot, shell
Use it for
List or search contacts.
Command
set-contact
Aliases
Runs as
one-shot
Use it for
Add or update one contact label.
Command
renamedevice
Aliases
Runs as
shell
Use it for
Rename the current device.
Command
connect
Aliases
Runs as
shell
Use it for
Refresh or connect a contact.
Command
setcontacts
Aliases
Runs as
shell
Use it for
Add or update contact labels in bulk.
Command
message
Aliases
msg
Runs as
one-shot, shell
Use it for
Send a text message or read recent message history.
Command
usage
Aliases
quota
Runs as
one-shot, shell
Use it for
Show usage in the rolling window.
Command
plan
Aliases
Runs as
shell
Use it for
Show the current plan.
Command
getplans
Aliases
Runs as
shell
Use it for
List available plans and limits.
Command
forward
Aliases
Runs as
shell
Use it for
Forward a selected transfer to another target.
Command
cd
Aliases
Runs as
shell
Use it for
Change the interactive working directory.
Command
zs
Aliases
ls
Runs as
shell
Use it for
List local files with selectable indexes.
Command
setdownloadpath
Aliases
Runs as
shell
Use it for
Set the default receive directory.
Command
autoaccept
Aliases
aa
Runs as
shell
Use it for
Toggle automatic acceptance for the running shell session.
Command
sendtodevices
Aliases
Runs as
shell
Use it for
Send selected items to your devices from the shell.
Command
share
Aliases
Runs as
shell
Use it for
Create, list, or remove download links.
Command
drop
Aliases
Runs as
shell
Use it for
Create, list, or remove upload drops.
Command
addshare
Aliases
Runs as
shell
Use it for
Create a shared folder for contacts.
Command
getshares
Aliases
Runs as
shell
Use it for
Refresh shared-folder state.
Command
acceptshare
Aliases
Runs as
shell
Use it for
Accept an incoming shared folder.
Command
removeshare
Aliases
Runs as
shell
Use it for
Remove a locally tracked shared folder.
Command
sendauth
Aliases
Runs as
shell
Use it for
Send an authentication request to your devices.
Command
verifyauth
Aliases
Runs as
shell
Use it for
Verify an authentication code.
Command
verifynewdevice
Aliases
Runs as
shell
Use it for
Verify a newly linked device.
Command
blockauthpeer
Aliases
Runs as
shell
Use it for
Block an authentication peer.
Command
theme
Aliases
Runs as
shell
Use it for
Preview or apply terminal themes.
Command
help
Aliases
h, ?
Runs as
shell
Use it for
Open help for a command or search help.
Command
search
Aliases
Runs as
shell
Use it for
Search help entries from the shell.
Command
shortcuts
Aliases
keys, keybindings
Runs as
shell
Use it for
Show keyboard shortcuts.
Command
configpath / configdir
Aliases
Runs as
shell
Use it for
Print config locations from the shell.
Command
!<command>
Aliases
Runs as
shell
Use it for
Run a local shell command from inside the Zynk shell.
Command
clear
Aliases
Runs as
shell
Use it for
Clear the interactive terminal screen.
Command
feedback / bugreport
Aliases
Runs as
shell
Use it for
Open support-oriented reporting flows.
Command
kill
Aliases
Runs as
shell
Use it for
Ask the running Zynk core to shut down.
Command
quit
Aliases
q
Runs as
shell
Use it for
Exit the interactive shell.
Command
config path
Aliases
show-default-config-path
Runs as
one-shot
Use it for
Print config locations.
Command
show-state-dir
Aliases
Runs as
one-shot
Use it for
Print the state directory for the current run.
Command
install
Aliases
Runs as
one-shot
Use it for
Run guided setup or reinstall.
Command
uninstall
Aliases
Runs as
one-shot
Use it for
Remove local install pieces, optionally including state.
Command
update
Aliases
Runs as
one-shot
Use it for
Update the CLI.
Command
completions
Aliases
Runs as
one-shot
Use it for
Print shell completion scripts.
Command
daemon status
Aliases
Runs as
one-shot
Use it for
Check background daemon health.
Command
daemon kill
Aliases
Runs as
one-shot
Use it for
Stop the daemon or clean stale daemon files.

JSON support

JSON support is command-family specific. Use the stable contracts documented in Automation for wrappers, and treat the rest of this page as terminal reference unless a row says otherwise.

Command family
pending
JSON status
Stable contract documented in Automation.
Use it for
Incoming-transfer inbox and empty-work checks.
Command family
daemon status
JSON status
Stable contract documented in Automation.
Use it for
Daemon health checks before unattended work.
Command family
config path and show-state-dir
JSON status
Stable contract documented in Automation.
Use it for
Finding selected config and state paths.
Command family
send, accept, cancel, about, message, and usage
JSON status
Terminal-first here; dry-run preview JSON may exist, but the success schema is not documented as a stable public contract on this page.
Use it for
Human operation and previews, not broad wrapper parsing.
Command family
devices, contacts, and transfer lists
JSON status
Implementation may emit JSON, but these schemas should not be treated as stable until Automation publishes them.
Use it for
Human lookup in this reference; wrapper use only after schema review.
Command family
Interactive shell commands such as share, drop, zs, theme, and support commands
JSON status
No stable one-shot JSON contract in this reference.
Use it for
Human interactive use.

Sending and receiving files

send, pending, and accept are the core file commands. Setup covers the first successful send; this page keeps the selector and input forms close at hand.

Core transfer flow

$ zynk send Bob ~/Projects/site-backupSuccessfully requested Folder send to Bob$ zynk send my:laptop ~/Pictures$ find ~/Documents -name '*.pdf' | zynk send Alice$ zynk pendingID    NAME           SIZE      STATE      SENDER0     report.pdf     842 KB    pending    Alice$ zynk accept 0 ~/DownloadsAccepting file transfer from Alice: report.pdf to ~/DownloadsPlease use showprogress|sp to see the file's progress$ zynk accept 9 ~/DownloadsTransfer index 9 was not found. Run `pending` to refresh the inbox.

The examples use convenient paths, not size limits. Paths can be files, folders, or path lists from another command.

Send files

  • send <destination> <path...> sends files or folders to a contact name or phone number.
  • send my:devicename <path...> sends to one of your own devices by name; send --my <id> <path...> and send --device <id> <path...> are the short-ID forms.
  • When no path arguments are given, send reads newline-separated paths from stdin.
  • Use Basics for the contact-name, phone-number, and own-device mental model.

Receive files

  • pending lists incoming transfers waiting for approval.
  • accept accepts the latest pending transfer when no selector is given.
  • accept <index> <save-dir> accepts a row from pending into a directory.
  • accept --transfer-id <id>, accept --all, and accept --from <contact> handle explicit or bulk receive work.
  • If you omit the save directory, accept writes to the current directory. Use - only for the configured default download path.

Output and JSON

  • pending prints No pending transfers. when the inbox is empty.
  • accept prints the selected transfer and destination before saving or reporting why it cannot accept.
  • pending --json-output is the structured inbox surface; Automation documents the stable fields.
  • If accept cannot find the selector, rerun pending and choose a current index or --transfer-id.

Inbox and progress

Use pending when the question is what needs approval. Use upload and download lists when the question is what is moving now.

Inspect and control transfers

$ zynk pending --since 3d$ zynk list-uploads --contact AliceID    NAME          STATE         PROGRESS   RATE       ETA2     report.pdf    transferring  48%        8.2 MB/s   12s$ zynk list-downloadsThere are no active downloads to list.$ zynk cancel all~/Zynk> showprogress~/Zynk> pause 2~/Zynk> resume 2

Inbox filters

  • pending shows the last 24 hours by default.
  • pending --all removes the time window.
  • pending --since <duration> uses a window such as 12h, 3d, or 1w.
  • pending --include-messages includes recent incoming messages in the same inbox view.

Progress and control

  • list-uploads / lu lists active uploads with progress, rate, and ETA.
  • list-downloads / ld lists active downloads.
  • cancel [index|all] is available as a one-shot command and inside the shell.
  • pause, resume, and showprogress / sp are interactive-shell controls.

Output and JSON

  • Transfer lists print an empty-state line such as There are no active uploads to list. or a table with ID, name, state, progress, rate, and ETA.
  • cancel with no argument lists cancellable transfers before you choose one.
  • list-uploads --json-output and list-downloads --json-output emit transfer arrays for wrappers.

Identity, contacts, and devices

Run identity commands before sending when you are not sure which account, device, or contact list this terminal is using.

Verification output shape

$ zynk aboutUser ID:         +15551234567Device Name:     Work LaptopPlatform:        macOSColor Mode:      True Color (24-bit)Config Dir:      ~/Library/Application Support/ZynkTotal Contacts:  196Zynk Contacts:   135Session Time:    4m 12sBoot Time:       238msSession ID:      1777364593409Peer ID:         12D3KooWabc...CLI Version:     1.3.2Core Version:    zone_core(1.0.4-469bc8f)Daemon:          DisconnectedBoot Node:       Production$ zynk devicesID    NAME          PEER ID          LAST SEEN    OS5o4   Work Laptop   12D3KooWabc...  just now     macOS$ zynk contactsNAME     NUMBERAlice    +15557654321$ zynk set-contact +15557654321 AliceContact set successfully.

The exact rows depend on your account. The useful device-send value is the short ID, not the full peer ID.

Account and devices

  • about prints the current account, local device name, peer ID, and version info.
  • devices prints linked devices; send with my:devicename (or use the short ID column with send --my <id>).
  • renamedevice <name> is an interactive command for changing this device's display name.
  • Use Configuration when the wrong account or device is coming from config.

Contacts

  • contacts lists Zynk contacts by default.
  • contacts ALL lists all contacts alphabetically.
  • contacts <term> searches all contacts; contacts ZYNK <term> searches only contacts who use Zynk.
  • set-contact <phone> <name> adds or updates one contact from a one-shot command.
  • contacts --json-output emits contact rows for wrappers; use terminal output for human lookup.

Messages and usage

Messages are useful when a transfer needs context. Usage and plan commands answer whether shares, drops, buffered files, or relay usage are near a limit.

Messages and account usage

$ zynk message Alice "Sending the files now"$ zynk message --last 10 --contact AliceTIME      FROM     MESSAGE10:42     Alice    Sending the files now$ zynk message --last 10 --contact NobodyNo messages found for Nobody.$ zynk msg . "note to self"$ zynk usage --verboseUsage and quotas<usage bars and totals>~/Zynk> plan

Messages

  • message <recipient> <text> sends a text message.
  • msg is the short alias.
  • message --last shows recent messages and defaults to 30.
  • message --last <n> --contact <contact> filters recent messages to one contact.
  • Recent message output can be empty; No messages found. means no matching local recent messages, not a send failure.

Usage and plans

  • usage / quota shows recent usage in the rolling window.
  • usage --verbose adds totals and counts.
  • plan and getplans are interactive commands for plan details.
  • forward <target> <index> is an interactive, Pro-gated Fast Forward command.
  • usage --json-output is useful for scripts that only need machine-readable usage state.

Interactive file workflow

Use the interactive shell when you are selecting files repeatedly or receiving many transfers into the same directory.

Interactive file workflow

~/Zynk> cd ~/Projects~/Zynk> zs --recursive --type pdf --size '>1mb'~/Zynk> send Alice 1,3~/Zynk> setdownloadpath ~/Downloads/Zynk~/Zynk> accept 0 -

Local file selection

  • cd [directory] changes the interactive shell working directory.
  • zs / ls lists files and assigns index numbers.
  • zs supports recursive search, depth limits, sorting, entry type, extension, size, and name filters.
  • Common shape: zs [path] --recursive --type <kind> --size '<rule>' --search <term>.
  • send <target> 1,3 sends entries selected from the last zs table.

Receive preferences

  • setdownloadpath <path> sets the default receive directory.
  • accept <index> - uses that default download path.
  • autoaccept / aa toggles automatic acceptance after a default download path exists.
  • setcontacts <contact_list> [force] and connect <contact> [false] are interactive contact-maintenance commands.

Shares, drops, and shared folders

Shares, drops, and shared folders are interactive-shell workflows. Use passwords, expiry, and cleanup for links; use Security for the safety model.

Interactive sharing commands

~/Zynk> share ./release.zip --expiry 3dShare ready at <share-url> Share this link to send your files~/Zynk> share ls --full --verbose~/Zynk> drop 2g --title "Client upload"Drop ready at <drop-url>. Share this link with anyone to collect files.~/Zynk> drop rm 2a1b7f3c~/Zynk> share lsNo active shares found.~/Zynk> drop lsNo active drops found.~/Zynk> addshare Alice ~/Shared --readonly~/Zynk> getshares~/Zynk> acceptshare . ~/Shared/Alice

Links and drops

  • share <path[,path...]> creates a download link from the interactive shell.
  • share ls [--full] [--verbose] lists shares.
  • share rm <id|all> removes shares.
  • drop <size> creates an upload drop; drop ls and drop rm manage existing drops.
  • Share/drop options include titles, passwords, and expiry when the command supports them.
  • Anyone with an active link can use it within its password, expiry, and size limits.

Shared folders

  • addshare <contacts> <folder> [--readonly] creates a shared folder.
  • getshares refreshes and prints owned and incoming shared folders.
  • acceptshare <id> <folder> accepts an incoming shared folder.
  • removeshare [#|.|id] removes a locally tracked shared folder.
  • List commands print an empty state when no shares, drops, or shared folders are present.

Interactive support commands

These commands are available inside the interactive shell for account support, feedback, and terminal housekeeping. They are included here so the reference covers the public help surface without making setup depend on them.

Interactive support commands

~/Zynk> sendauth sms~/Zynk> verifyauth <code>~/Zynk> verifynewdevice <code>~/Zynk> help --search transfer~/Zynk> shortcuts~/Zynk> !pwd~/Zynk> feedback~/Zynk> bugreport~/Zynk> q

Auth and support

  • help, help <command>, help --search <term>, and search <term> expose the shell help registry.
  • shortcuts, keys, and keybindings show interactive keyboard shortcuts.
  • sendauth, verifyauth, and verifynewdevice support account and device verification flows from the interactive shell.
  • blockauthpeer blocks an authentication peer when a verification flow should not continue.
  • feedback and bugreport open support-oriented reporting flows.

Shell utilities

  • theme preview <name> tests a preset and theme apply <name> saves it.
  • !<command> runs a local shell command from inside the interactive shell.
  • clear clears the interactive screen.
  • quit / q exits the shell; kill asks Zynk to shut down the running core.

System and configuration

System commands are direct local operations. They do not need the daemon and should not be mixed into the first send-and-receive path.

Path output shape

$ zynk config pathConfig directory: /Users/alex/Library/Application Support/ZynkUser config file: /Users/alex/Library/Application Support/Zynk/zynk.confSystem config file: /etc/zynk.conf$ zynk show-state-dir/Users/alex/Library/Application Support/Zynk

config path and show-default-config-path print the same config-path fields. Use Configuration for precedence and common config keys.

Maintenance commands

$ zynk install --force$ zynk uninstall --yes$ zynk uninstall --all$ zynk update

Paths and state

  • show-default-config-path and config path print the config directory plus user and system config files.
  • show-state-dir prints the state directory used for identity, database, and transfer state.
  • --config <file> points one run at a specific config file.
  • --persistence <dir> points one run at a specific state directory.

Install and maintenance

  • install runs guided local setup; install --force reinstalls.
  • uninstall removes the installed binary, PATH entries, and config directory after prompts.
  • uninstall --all additionally offers to remove the auxiliary state directory for daemon logs and lock files when it exists separately.
  • Custom persistence paths outside the default config directory are reported but not deleted automatically.
  • update updates the CLI. completions <shell> prints shell completion scripts; use Automation for shell-specific examples.

Daemon commands

Daemon commands are small on purpose: start the background process, check it, and stop it.

Daemon output shape

$ zynk --run-mode server$ zynk daemon statusZynk daemon is running  User:      alex  PID:       12345  Uptime:    2m  Socket:    /tmp/zynk.sock  Lock file: /Users/alex/Library/Application Support/Zynk/zynk.lock$ zynk daemon status --json-output{"type":"daemon_status","data":{"running":true,"pid":"12345","user":"alex","uptime_secs":120,"socket":"/tmp/zynk.sock","socket_exists":true,"lock_file":"/Users/alex/Library/Application Support/Zynk/zynk.lock"}}$ zynk daemon kill

Daemon commands

  • zynk --run-mode server starts daemon mode. There is no daemon start subcommand.
  • daemon status shows whether the daemon is running.
  • daemon status --json-output is the health-check shape for scripts.
  • daemon kill gracefully stops the daemon.

Routing boundaries

  • send, pending, accept, contacts, devices, message, usage, list-uploads, and list-downloads can use daemon routing when it is available.
  • install, uninstall, update, completions, config-path commands, and daemon control run directly.
  • --dry-run bypasses daemon routing.
  • Use Daemon for startup behavior, logs, fallback, and recovery.

Flags

Flags either change startup state for this run or change how command output is emitted. Keep persistent defaults in config when the same override is needed every time.

Flag placement examples

$ zynk --config ./zynk.conf about$ zynk --persistence /var/lib/zynk pending$ zynk send Bob report.pdf --dry-run$ zynk pending --json-output$ zynk --no-color list-downloads

Use Automation for JSON and dry-run scripting patterns.

Identity and state overrides

  • --user / -u sets the account phone number for one run.
  • --config / -c points one run at a config file.
  • --persistence / -p points one run at a state directory.
  • --auto-accept true|false overrides auto-accept behavior for one run.

Runtime and output flags

  • --run-mode accepts repl, client, and server.
  • --json-output, --dry-run, and --no-color are global output controls.
  • --log-level and --log-filter control logging.
  • --example-config prints a human-readable config reference.
  • --theme prints the terminal theme preview.