Zynk CLI

CLI configuration

Find the Zynk CLI config, make small durable changes, choose where state lives, and understand receive, notification, logging, color, and update settings.

Config and state paths

Start by finding the files Zynk will use on this machine. Config stores account and preference settings. State stores local identity, transfer history, and runtime data.

Use the config path command before editing a file by hand. The labels are stable; the exact paths depend on your operating system and user account.

Find the config files

$ zynk show-default-config-pathConfig directory: <config-dir>User config file: <user-config-file>System config file: <system-config-file>

zynk config path prints the same locations through the newer nested command form.

Find the default state directory

$ zynk show-state-dir<state-dir>

This shows the default state directory, or the directory passed with --persistence for this command. It does not prove which persistence value is written inside a selected config file.

Which path to edit

  • Most personal installs should edit the user config file after confirming a system config is not taking precedence.
  • A system config is for managed machines where one administrator owns the default settings.
  • Do not edit state files directly. Use commands such as pending, accept, daemon status, and uninstall instead.

When the paths matter

  • Check config paths when about shows the wrong account or device name.
  • Check state paths before moving a server install, backing up identity, or using uninstall --all.
  • Treat state deletion as destructive, and verify config paths before changing identity settings.

Which settings win

Zynk reads one config file for a run. If you do not pass --config, it uses the system config when that file exists; otherwise it uses the user config.

Use command-line flags for temporary changes. Put values in the config file only when you want the same behavior every time.

Run one command with another config

$ zynk --config ./server.zynk.conf pending

The override applies to this command only.

Precedence

  • --config selects a specific config file for one run.
  • Without --config, the system config wins when it exists. If it does not exist, Zynk uses the user config.
  • Global flags such as --user, --persistence, --no-color, --log-level, --log-filter, and --json-output are current-run overrides.

Safer habits

  • Prefer the user config unless you are managing a shared machine.
  • Use --config for scripts that should not depend on a developer laptop's normal account.
  • Use --example-config as reference output, then copy only the keys you understand into your active config.

Safe edit and validate workflow

Change config in small steps. Find the active files, copy only the keys you need, validate parsing with a harmless command, then restart the daemon only if one was running.

Inspect, edit, validate

$ zynk show-default-config-path$ zynk --example-config > zynk.example.txt$ zynk --config ./zynk.conf --dry-run about{"type":"about_preview","data":{"command":"about"}}$ zynk --config ./zynk.conf about

--example-config is reference output, not a clean active config template. --dry-run about proves the selected config parses and the command plan can be built; the real about confirms account and device output.

Restart daemon mode after config changes

$ zynk daemon kill$ zynk --config ./zynk.conf --run-mode server

Skip this when you were not using daemon mode.

Recover from a bad active config

$ zynk pendingFailed to parse Zynk config file: <parse error>$ zynk show-default-config-path$ mv <user-config-file> <user-config-file>.broken$ zynk --config ./minimal.conf --dry-run about{"type":"about_preview","data":{"command":"about"}}

Rename the broken active file instead of deleting it immediately, then restore known-good settings into a minimal file and validate parsing before replacing the active config.

Edit only what you need

  • Use --example-config as a reference, not as a file to copy wholesale.
  • Keep comments and unused keys out of your active config unless they help your team maintain it.
  • Use --config in scripts so they do not silently depend on your normal laptop config.

Validate before relying on it

  • A parse error means the TOML needs fixing before Zynk can use that file.
  • --dry-run about confirms parsing, while the real about confirms the account and device that the selected config produces.
  • If a daemon was already running, restart it so new one-shot commands do not keep using old background state.

Recover from a bad config

  • Run zynk show-default-config-path to find the user and system config locations; this command works before normal config loading.
  • A broken active file can make normal commands fail with a parse error such as Failed to parse Zynk config file.
  • Use the parse error line to fix the smallest TOML mistake, or rename the broken file and restore the last known-good copy.
  • Validate a temporary minimal file with zynk --config ./minimal.conf --dry-run about before replacing the active config.

Minimal config

The smallest useful config identifies the account and gives this device a human name. Add other keys only when they solve a real problem.

Account and device

user = "+1234567890"description = "Work Laptop"

Core keys

  • user is the phone number for the Zynk account.
  • description is the device name shown in device lists and identity checks.
  • zynk install writes these values for you during guided setup.

Small preferences

  • tips = true keeps first-run and login tips visible.
  • command-history = true keeps interactive shell history between sessions.
  • suggestions = "on" keeps unknown-command suggestions enabled.
  • copy-links = true copies share and drop links to the clipboard when the platform allows it.

State and persistence

Leave state in the default directory on laptops and desktops. Set persistence only when the machine needs an explicit durable state path, such as a server, container, or portable install.

The state directory is more sensitive than the config file because it contains local identity and transfer data. Back it up deliberately and do not delete it as a troubleshooting shortcut.

To audit a configured install, inspect the selected config file's persistence key. show-state-dir is a default or one-run flag check, so pair it with zynk --persistence <path> show-state-dir when testing a candidate path.

zynk --persistence /var/lib/zynk show-state-dir echoes the path selected for that invocation. It does not create the directory, check permissions, or prove a later daemon can use it.

Durable state path

persistence = "/var/lib/zynk"

For a one-run check, use zynk --persistence /var/lib/zynk show-state-dir.

Good reasons to set it

  • A service account needs state under /var/lib/zynk or another managed data directory.
  • A container needs state mounted on a persistent volume.
  • A portable install needs config and state kept in predictable locations.

What to avoid

  • Do not point two daemons at the same state directory.
  • Do not put state in a source repo or synced folder you do not control.
  • Stop the daemon before changing state paths, and do not delete state until you know what identity and history it contains.

Privacy and shared machines

Config, state, history, logs, and copied links can expose different parts of local Zynk usage. Treat them as user data on shared machines and servers.

Shared-machine snippet

  • command-history = false avoids saving interactive command history.
  • copy-links = false keeps share and drop URLs out of the system clipboard when possible.
  • Use a private log-file path only when durable logs are needed, and review that file before sharing support bundles.

What can leak

  • Config can include your phone number and device name.
  • State can include local identity material, transfer state, and transfer history.
  • Command history and logs can include paths, contact names, phone numbers, peer IDs, share links, and drop links.

Safer handling

  • Keep config and state out of source repos and broad synced folders.
  • Review logs and command history before sharing them for support.
  • Disable or avoid copy-links on shared desktops when share or drop URLs should not land in the system clipboard.

Notifications

Keep notifications enabled while setting up and troubleshooting receives. They make incoming transfers and completion events visible without watching the terminal constantly.

Desktop notification settings

[notifications]enabled = truemessage-received = truefile-request = truetransfer-complete = trueonly-when-unfocused = true

What each key controls

  • enabled is the master switch.
  • message-received covers incoming messages.
  • file-request covers incoming file requests.
  • transfer-complete covers uploads and downloads finishing.
  • only-when-unfocused avoids duplicate noise while you are already focused on the terminal.

When to turn them off

  • Server installs may prefer notifications off and logging on.
  • Long-running interactive sessions can keep notifications on with only-when-unfocused = true.
  • If notifications do not appear, inspect notification config before changing unrelated transfer settings.

Auto-accept

Auto-accept saves incoming files without a manual accept step. Use it only with a destination directory you chose for unattended receives.

The durable config key is the destination path. Removing the key disables auto-accept at startup.

Dedicated receive directory

auto-accept-path = "/absolute/path/to/ZynkDownloads"

Use an absolute path on the machine running Zynk.

Safer defaults

  • Use a directory you can inspect before moving files into project folders.
  • Do not auto-accept into executable paths, source repos, or shared folders with broad access.
  • In config, the important trust choice is the destination directory.

Interactive testing

  • setdownloadpath sets the interactive shell download directory.
  • autoaccept toggles auto-accept during an interactive session.
  • Use the interactive commands first when you are not sure the destination path is right.

Logging and terminal output

Most users should leave logging and color alone. Change these settings for diagnostics, script output, terminals without color, or places where progress rendering gets in the way.

One-run diagnostic output

$ zynk --no-color --log-level Info --log-filter Base pending

--no-color removes terminal color. --log-level and --log-filter apply only to this run when passed as flags.

Durable logging and output settings

json-output = falseforce-show-progress = truelog-level = "Info"log-filter = "Base"log-file = "zynk.log"log-show = falseno-color = false

Keep json-output = false for normal terminal use; turn it on per command when a wrapper needs machine output.

Durable keys

  • json-output = true requests JSON by default where a command supports it.
  • force-show-progress = true keeps transfer progress visible.
  • log-level, log-filter, log-file, and log-show control diagnostic logging.
  • no-color = true disables colored terminal output.

Color themes

  • zynk --theme displays the current terminal theme sample.
  • In the interactive shell, theme preview <name> tests a preset and theme apply <name> saves it.
  • Hand-edit colors.* only when you need exact RGB values.

Updates

Leave update checks on unless the machine is managed by a separate packaging system or cannot make background version checks.

Update check settings

[updates]enabled = truecheck-interval-hours = 24

When to change it

  • Turn checks off when an administrator controls upgrades.
  • Increase the interval on machines where periodic network checks are undesirable.
  • Use zynk update for a deliberate update run.

What not to mix in

  • Update settings do not change transfer routing.
  • Update settings do not start or stop daemon mode.
  • Update settings do not repair PATH; fix installer or shell configuration separately.

Settings to leave alone

A working CLI usually does not need network or sync tuning. Changing those settings can make a simple account or contact issue harder to diagnose.

When config does not solve the problem, use Automation for wrapper behavior or Daemon for background-process state.

Usually keep defaults

  • Leave enable-contacts-sync and enable-transfer-sync enabled for normal use.
  • Keep netmode at its default unless you are working through a specific network issue.
  • Leave unfamiliar settings out until the command reference or current --example-config output explains the effect you need.