droboticflow/docs/drosync/cli-reference.md

2.6 KiB

CLI reference

Global flags:

  • --json: one JSON value on stdout.
  • --non-interactive: reject any future command that would require interactive input.

Commands:

Command Purpose
configure --server URL Persist the control-plane URL through daemon IPC.
auth --server URL [--profile NAME] --access-key-id ID (--secret-file PATH | --secret-stdin) Validate a scoped drosync Key/Secret, automatically register the device, and store the resulting bearer token in the OS credential store. DROSYNC_ACCESS_KEY_ID and DROSYNC_SECRET are supported for non-interactive injection.
mapping list List local mappings.
mapping add ROOT (--bucket NAME | --space ID) [--remote-prefix P] [--include-hidden] [--require-done] Add a mapping. --bucket resolves only within spaces visible to the current scoped credential; --space selects an exact administrative ID.
mapping remove ID Remove a mapping without deleting local or remote objects.
plan [ID] Scan, calculate plan, and preview pending changes (dry-run) without uploading data.
sync [ID] Execute live data scan through final upload and commit.
status Show daemon, mappings, active sessions, and transfer status.
conflicts List locally known kept_both results.
retry [ID] Resume a mapping after a retryable failure.
abort [ID] Abort active sync session(s).
doctor Check SQLite, IPC, device credential, control plane, and scoped capabilities.
report [--date D] [--format xlsx|csv] Scan local data and generate Excel/CSV sync report.
web [--port P] [--host H] Launch local embedded web dashboard server (pure local access, no login required).
update Check/pin/pause/rollback signed client releases.
version Print client, protocol, platform, and architecture.

Daemon service management: The background daemon is managed exclusively through the system service: sudo systemctl {start|stop|restart|status} drosync. drosync daemon CLI command has been removed to maintain a single canonical entry point.

Exit codes:

Code Meaning
0 Success.
2 CLI usage or invalid local configuration.
10 Authentication or credential revoked.
20 Permission/scope/capability gate denied.
30 Conflict or active lease; retry according to the error.
40 Local filesystem/SQLite integrity failure.
50 Network, server, BOS, or otherwise unclassified operation failure.

The implementation emits structured server code/message/retryable/requestId/details errors. Automation should prefer --json and the stable error code over translated text.