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 $ run from your operating-system shell. Most run one action and return; zynk activity and zynk repl start interactive sessions.
  • Lines that start with ~/Zynk> run inside the interactive Zynk shell.
  • Aliases vary by command. pd works as an alias for pending both from your operating-system shell and inside the REPL.
  • 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> shows help for commands supported by the Zynk prompt.
  • help --search <term> searches command names, notes, examples, and tips inside the shell.

Account session

Use login to sign in or switch this device to another account. Use logout to sign out this device without deleting the account or its other linked devices.

Switching accounts or signing out stops active transfers. Both commands ask for confirmation when needed; --yes skips it and is required for those confirmations when input is not a terminal.

Sign in with your account address

$ zynk login [email protected]

An existing account phone number also works. Follow any authentication-method and verification-code prompts.

Sign out this device

$ zynk logout

Command index

Find a command by name, check its aliases, and see where to run it.

Command
activity
Aliases
tui
Runs as
interactive launch, shell
Use it for
Open the full-screen workspace.
Command
repl
Aliases
Runs as
interactive launch
Use it for
Open the classic command prompt.
Command
login / logout
Aliases
Runs as
direct command, shell
Use it for
Sign this device in or out.
Command
send
Aliases
Runs as
one-shot, shell
Use it for
Send files, folders, or stdin path lists.
Command
pending
Aliases
pd
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
handles
Aliases
Runs as
shell
Use it for
List the addresses your account can be reached by.
Command
addhandle / removehandle
Aliases
Runs as
shell
Use it for
Add or remove an email address on your account.
Command
setprimary
Aliases
Runs as
shell
Use it for
Choose which address names your account.
Command
setusername / releaseusername
Aliases
Runs as
shell
Use it for
Claim or give up the username people can find you by.
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
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
Choose a folder and enable persistent auto-accept.
Command
autoaccept
Aliases
aa
Runs as
shell
Use it for
Disable persistent automatic acceptance of incoming files.
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 output differs between commands. Before parsing it in a script, check the supported fields in Automation.

Command family
pending
JSON status
Fields documented in Automation.
Use it for
Incoming-transfer inbox and empty-work checks.
Command family
daemon status
JSON status
Fields documented in Automation.
Use it for
Daemon health checks before unattended work.
Command family
config path and show-state-dir
JSON status
Fields documented in Automation.
Use it for
Finding selected config and state paths.
Command family
send and accept
JSON status
Read every JSON record and check the exit status. See Automation.
Use it for
Track acknowledged sends, completed receives, and unknown or partial outcomes.
Command family
cancel, about, message, and usage
JSON status
JSON fields depend on the command.
Use it for
Check the command’s output before using its fields in a script.
Command family
devices
JSON status
Returns a devices record; an empty list is a successful result. See Automation.
Use it for
Check linked devices, including accounts with none.
Command family
contacts and transfer lists
JSON status
JSON fields depend on the command.
Use it for
Check the output format before parsing it in a script.
Command family
Interactive shell commands such as share, drop, zs, theme, and support commands
JSON status
No stable one-shot JSON format is documented here.
Use it for
Human interactive use.

Sending and receiving files

Use send to send files, pending to list incoming requests, and accept to save an incoming transfer.

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, email address, 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.
  • See Basics for sending to a contact, an address, or one of your devices.

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 lists incoming requests as JSON. See Automation for the 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, devices, and handles

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

Verification output

$ 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...Core 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.~/Zynk> setusername danaYou are now @dana.

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 <address-or-username> <name> adds or updates one contact from a one-shot command. The first argument is a phone number, an email address, or a username with or without the leading @.
  • contacts --json-output emits contact rows for wrappers; use terminal output for human lookup.

Account handles and username

  • handles lists the phone numbers and email addresses your account can be reached by, marking the primary one. It answers from local state, so it works offline.
  • addhandle <email> adds an email address to your account. Zynk sends a verification code to that address; enter it with verifyauth.
  • removehandle <email> detaches an address. The primary address cannot be removed until another one is made primary.
  • setprimary <handle> chooses which verified address names your account. Any verified address qualifies, including the phone number on an older account.
  • setusername <name> claims a username such as dana so people can add you without your email or phone number. Names are 3 to 30 characters of a-z, 0-9, and _, start with a letter, and are folded to lower case. Claiming a new name replaces the old one.
  • releaseusername gives up your username. The name is retired rather than freed, so nobody else can claim it and you can take it back later.
  • These commands run from the ~/Zynk> prompt after zynk starts. A username is not a way to sign in, so --user and the user config key still take an email address or phone number.

Messages and usage

Messages are useful when a transfer needs context. Usage 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>

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

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

Choosing files at the prompt

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

Choosing files at the prompt

~/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.
  • Example syntax: 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> saves the receive directory and enables persistent auto-accept.
  • accept <index> - uses that default download path.
  • setdownloadpath <PATH> saves an existing, writable folder and enables auto-accept. autoaccept / aa disables it and clears the saved folder.
  • setcontacts <contact_list> [force] and connect <contact> [false] are interactive contact-maintenance commands.

Shares, drops, and shared folders

Create shares, drops, and shared folders from the Zynk prompt. Set passwords and expiry dates for links, and remove them when they are no longer needed.

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

Use these commands at the Zynk prompt for account verification, help, and support.

Interactive support commands

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

Auth and support

  • Use help to list commands, help <command> for details, or help --search <term> to search. search <term> also searches help.
  • 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.

Config and state paths

$ 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 installs the latest available CLI after confirmation. update --yes skips that confirmation; update --dry-run previews the update operation.
  • completions <shell> prints shell completion scripts; use Automation for shell-specific examples.

Daemon commands

Start the daemon to keep Zynk running in the background. Use daemon status to check it and daemon kill to stop it.

Daemon status output

$ 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.
  • Use daemon status --json-output to check the daemon from a script.
  • daemon kill gracefully stops the daemon.

Commands that use the daemon

  • 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 email address or 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. --interface activity|repl selects the interactive startup interface for one launch.
  • --json-output, --dry-run, and --no-color are global output controls.
  • --wait-timeout 10s bounds asynchronous startup and command-response waits. It is not a recipient-delivery deadline. See Automation.
  • --log-level and --log-filter control logging.
  • --example-config prints a human-readable config reference.
  • --theme prints the terminal theme preview.