Zynk CLI

Daemon mode

Start and inspect the optional Zynk CLI daemon, understand one-shot routing, find logs, and recover from stale daemon state.

Starting the daemon

Start daemon mode only when you want a background Zynk process. Normal one-shot commands still work without it.

Start the background process

$ zynk --run-mode serverZynk daemon started successfully.Logs: <daemon log path>

The launcher exits after it starts the detached daemon. Use the printed log path when you need to inspect daemon output.

Start with explicit config and state

$ zynk --config ./server.zynk.conf --persistence /var/lib/zynk --run-mode server

These paths are loaded when the daemon starts. To change the daemon's account or state later, stop it and start a fresh daemon with the new paths.

Already running

$ zynk --run-mode serverZynk daemon is already running (PID <pid>).$ zynk daemon status$ zynk daemon kill

If this appears while switching account or state paths, inspect status, stop the existing daemon, then retry the start command with the intended config and state.

When it helps

  • Repeated one-shot commands can reuse a warm Zynk process.
  • Server sessions can keep Zynk ready without leaving an interactive shell open.
  • Automation can check daemon health before running jobs that expect a warm process.

What starts

  • The daemon owns the Unix socket at /tmp/zynk.sock while it is running.
  • The socket examples on this page apply to macOS, Linux, and FreeBSD builds.
  • Daemon mode is not currently available on Windows; use normal one-shot commands or the interactive CLI there.
  • It writes a lock file with its PID so zynk daemon status can find it later.
  • If another daemon is already running for this user, start exits instead of launching a second copy.
  • The detached process can survive closing the terminal that launched it, but it is not installed as a launchd or systemd service by this command.
  • It does not restart automatically after reboot or login unless you configure your own service manager.
  • Normal one-shot commands do not auto-start daemon mode; they use it when available or run directly.

Daemon status

Check status after starting the daemon, before automation, or any time a command seems to be using old background state.

Human-readable status

$ zynk daemon statusZynk daemon is running  User:      <user>  PID:       <pid>  Uptime:    2m 17s  Socket:    /tmp/zynk.sock  Lock file: <daemon lock file>

The user, PID, uptime, and lock-file path vary by machine.

JSON status for scripts

$ zynk daemon status --json-output{"type":"daemon_status","data":{"running":true,"pid":"<pid>","user":"<user>","uptime_secs":137,"socket":"/tmp/zynk.sock","socket_exists":true,"lock_file":"<daemon lock file>"}}

Use this shape for health checks before scripted jobs.

What status proves

  • A running result means the PID in the daemon lock file is a live Zynk process.
  • The socket line shows where one-shot clients try to connect.
  • A not-running result is still useful because it reports a stale socket when one exists.

Stopping the daemon

Stop the daemon before switching accounts, changing config or state paths, or clearing behavior that looks stale.

Stop the background process

$ zynk daemon killZynk daemon (PID <pid>) stopped.

A stopped daemon does not remove your config, contacts, pending transfers, or local state.

Shutdown behavior

  • Zynk first asks the daemon to shut down through the socket.
  • If the socket cannot complete the shutdown but the PID is live, Zynk sends the normal Unix termination signal.
  • If there is no live PID and only stale daemon files remain, daemon kill cleans them up.

One-shot routing

After the daemon is running, keep using normal one-shot commands. There is no daemon-specific form of send, pending, or accept, and config flags on a routed command do not select a different running daemon.

Run the same command

$ zynk pending

When daemon routing is available, the CLI tries the daemon socket first. If that fails, it falls back to direct execution.

What can route

  • Send and receive workflows can use the daemon when one request maps to one background action.
  • contacts, devices, about, messages, usage, and transfer lists can also use daemon routing.
  • For send, a routed one-shot returns after the request is accepted or queued; it does not wait for every byte to finish transferring.
  • A routed command talks to the daemon on the fixed socket, so the daemon's loaded config and state are the ones that matter.

What stays direct

  • --dry-run bypasses daemon routing so it can report the direct command plan.
  • Installer, updater, completions, config-path, state-path, and daemon-management commands run in the current process.
  • Multi-destination contact sends can run directly because one daemon completion cannot represent every fan-out target.

Daemon logs

Use status first, then choose the log that matches the problem. Startup output and runtime transfer diagnostics are separate concerns.

Follow detached process output

$ tail -f <daemon log path>

Replace <daemon log path> with the exact path from the Logs: line. This is stdout and stderr for the detached daemon process.

Enable runtime diagnostic output

$ zynk daemon kill$ zynk --log-level Info --log-filter Base --run-mode server

Logging settings apply when the daemon starts. Stop the existing daemon first, then restart it with the logging flags or equivalent config. If config sets log-file, inspect that file for runtime diagnostics.

Startup output

  • The detached daemon writes stdout and stderr to zynk-daemon.log instead of the terminal that started it.
  • Use the printed startup output for the exact log path on the current machine.
  • The path normally comes from the platform state directory, then cache, then the temp directory if state is unavailable.

Runtime diagnostics

  • Use the detached process log for startup failures and socket connection failures.
  • Use runtime logging for transfer lifecycle issues such as queued, active, failed, or cancelled transfers.
  • Check logs before deleting daemon files by hand.
  • Do not share logs before checking for account, contact, path, or transfer details.

State ownership

A daemon is one background process under one OS user. Keep the daemon, config, and state path aligned.

Switch daemon account or state

$ zynk daemon kill$ zynk --config ./server.zynk.conf --persistence /var/lib/zynk --run-mode server$ zynk daemon status$ zynk about

daemon status proves the restarted process is live. Run identity or inbox checks without config/state flags so you are testing the daemon on the fixed socket, not a direct fallback process with different flags.

Keep ownership simple

  • Start the daemon under the same OS user that will run one-shot commands.
  • Do not run multiple daemons against the same state directory.
  • Stop the daemon before changing --config, --persistence, phone number, or device name.

Stale process or socket recovery

Start with status. It tells you whether the lock file points to a live daemon and whether a stale socket is still on disk.

Check for a stale socket

$ zynk daemon statusZynk daemon is not running.  Stale socket at /tmp/zynk.sock

Daemon cleanup

$ zynk daemon killCleaned up stale daemon files.

Run zynk --run-mode server again after cleanup if you still want daemon mode.

Common fixes

  • If status says the daemon is not running, start it again when you need daemon mode.
  • If behavior looks stale after a config or account change, kill the daemon and start a fresh one under the intended state.
  • If a one-shot command cannot connect to the daemon, direct execution should still handle the command.

Manual cleanup

  • Prefer zynk daemon kill before deleting /tmp/zynk.sock or lock files yourself.
  • Manual deletion should be a last step after status, kill, and the logs agree there is no live daemon.
  • On servers, keep the state directory persistent so daemon restarts keep the same identity.