droboticflow/docs/drosync/cli-reference.md

9.1 KiB
Raw Blame History

CLI reference — 1.0.4

This reference describes the current source contract. It does not establish the version installed on a device or the availability of a signed release. CLI owns local operations; web is the sole daily-report viewer and report is the sole report exporter. No command aliases or old IPC routes are retained.

Function Canonical command
Authenticate/register the device and save server configuration drosync auth --server URL --access-key-id ID (--secret-file PATH or --secret-stdin)
List mappings drosync mapping list
Add a mapping drosync mapping add ROOT (--bucket NAME or --space ID) [--remote-prefix P] [--include-hidden] [--require-done]
Confirm cancellation of active sessions and remove their mapping drosync mapping remove ID
Upload/resume a mapping drosync sync [ID]
Preview the cloud plan without uploading file content drosync sync [ID] --dry-run
Read a page of local daemon/session state drosync status [--cursor SESSION_ID] [--limit N]
View locally recorded conflicts drosync status --conflicts
Pause new upload scheduling drosync pause
Resume upload scheduling drosync resume
Abort one session or all locally known active sessions drosync abort [SESSION_ID]
Diagnose the state database, IPC and scoped control-plane access drosync doctor
Query available update metadata without downloading drosync update check
Prepare a verified native package and request OS-authorized installation drosync update install
Pin the allowed update version without installing drosync update pin VERSION
Clear the update pin drosync update unpin
Pause client update preparation drosync update pause
Resume client update preparation drosync update resume
Request OS-authorized installation of the recorded previous package drosync update rollback
Export daily-report files drosync report [--date D] [--mapping ID or --path ROOT] [--output DIR] [--format xlsx or csv]
Start the read-only daily-report viewer drosync web [--mapping ID or --path ROOT] [--host H] [--port P] [--open]
Read CLI/protocol/platform and reachable daemon versions drosync version
Read command help drosync [COMMAND] --help

Selection and results

Global --json selects machine-readable output. --help is the sole help spelling: there is no help subcommand, -h, or --version alias. auth also accepts --profile, --device-name, --require-https, DROSYNC_ACCESS_KEY_ID and DROSYNC_SECRET. File and stdin secret inputs are mutually exclusive. Bucket and space are two mutually exclusive target representations within one mapping operation.

Omitting a sync mapping ID is allowed only with one mapping. Report/Web accept one explicit mapping or path; multiple mappings require selection. If the same path belongs to multiple cloud mappings, choose --mapping rather than letting the report guess a destination. Equivalent duplicate mappings are rejected. Removing a mapping cancels local work and requires confirmation of cloud cancellation; on an uncertain remote result the mapping/journal is preserved for retry. An accepted Session creation whose response was lost is recovered using its original request and idempotency key before cancellation.

sync --dry-run sends a manifest and creates a control-plane plan. It is not an offline scan and does not disable the daemon's independent automatic scheduling. Data-file flow remains local-to-BOS only. pause prevents new object dispatch; already in-flight objects may finish. Use abort for cancellation.

status defaults to 100 sessions, accepts limits 1–1000 and returns sessions, nextCursor and truncated. Feed the returned cursor into the next request; do not manufacture offsets. --conflicts cannot be combined with cursor/limit and returns at most 1000 locally cached conflict results with truncated. These are local diagnostics. The platform Session/conflict pages provide paginated cloud management views; they do not operate the local daemon.

Daily reports

Web serves only / and read-only GET /api/report; it has no control or export endpoints. Default binding is 127.0.0.1:8080. The old platform /sync-report page, object-storage report modal/API and their export controls are removed. Platform admin-abort is also removed; drosync abort is the sole public session-cancellation operation.

Report queries use the selected mapping's upload filters and explicit remote prefix, and look up each file in the latest local receipt projection. A completed receipt must match the current source identity. Historical receipts without identity are 待校验, not proof of completeness. On Unix this identity includes filesystem identity/change evidence; on Windows the weaker metadata additionally requires streaming SHA256 verification of completed candidates. A report never performs a real-time scan of the bucket. Read/permission failures are errors rather than invented empty or complete data.

Export returns date, localRoot and exportedFiles; it does not return an alternative terminal dashboard. Names are data_sync_report_<DATE>_<SCOPE>.xlsx, or matching _summary.csv/_missing.csv, where SCOPE is a stable digest of root plus mapping. Distinct mappings/roots cannot overwrite each other's default same-day report by sharing a date-only name. Re-exporting the same scope/date replaces that scope's prior report. Default output is reports/ under the selected state directory; --output explicitly overrides it. Synchronization does not export reports automatically or write them back into the capture directory.

State, credentials and server contract

Use one state namespace for CLI and daemon. UNIX defaults to OS project directories; Windows system mode uses ProgramData/drosync. An absolute DROSYNC_DATA_DIR selects state.db, the UNIX socket and config/ underneath it. The Windows pipe is \\.\pipe\drosync; choose MSI system service or user-startup mode, never both. There is no endpoint or account-path fallback.

Linux packages use the service account's explicit device-token file. On Unix, DROSYNC_SECRET_FILE can explicitly select token storage; Windows runtime tokens use its OS credential store. The Access Key Secret passed to auth --secret-file is an authentication input, not that persisted device token. No old JSON/env defaults, guessed token paths or default mappings are imported.

Upgrade API/coordinator first. Before scanning/creating a Session the client requires /capabilities to advertise features.sessionHeartbeat=true; the status endpoint must provide progress.totalItems and progress.terminalItems, and the server must implement Session heartbeat. There is no per-item-heartbeat or old polling fallback. A v1 protocol string alone does not satisfy these requirements.

The daemon migrates SQLite to schema 5; read-only reports do not migrate it. Current recovery journals are version 3 with source snapshots and the original Session creation request. An incompatible in-flight journal requires confirmed remote abort and a fresh scan; source files and committed cloud data are not deleted. See installation.

Updates and exit codes

The daemon periodically checks/prepares signed updates. It downloads and verifies packages but never elevates privileges or installs them from its service account. update install/rollback requests OS authorization in the CLI; the authorized installer verifies a private copy's fixed SHA256 and native signature before installation. An active transfer returns a deferred result. Only the installer-owned native format marker permits native package install/rollback; missing, unknown, portable and user-startup markers are rejected. Portable and Windows user-startup installations update through their corresponding installer, not by crossing into DEB/MSI self-update. Signed updates must contain the complete four-platform artifact/digest matrix; historical partial manifests are no longer accepted. See update rollout.

Code Meaning
0 Operation succeeded; for sync, completed/unchanged or a successful preview.
2 CLI usage/argument error.
10 Credential/authorization error classification.
20 Scope/capability error classification.
30 Lease/conflict error, or sync ended conflicted.
40 Local filesystem/state error classification.
50 Network/server/unclassified error; also sync failed, expired, aborted, partial, or paused before completing.

Sync failure/partial/conflict results preserve their JSON body even when the exit code is nonzero. Automation must inspect both. A success code or a local report alone is not a policy for deleting source data.

Retired entries: configure/plan/retry/conflicts, --non-interactive, old update flags, GUI, Web controls/exports, platform daily-report routes and admin-abort, terminal dashboard output, automatic Excel export, multi-path state/socket discovery, configuration initialization, and clean-install.sh. Switch callers to the canonical entry; no aliases remain. Start/stop the daemon through the selected OS service manager, not an additional CLI alias.