11 KiB
CLI reference — 1.0.5
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 [--session ID] [--cursor CURSOR] [--limit N] |
| Pause new upload scheduling | drosync pause |
| Resume upload scheduling | drosync resume |
| Abort one owned session or discover and abort all owned 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 --device-id for recovery into a new/empty namespace, --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 into a separate preview-only Session, reads its plan, and confirms remote abort before reporting success. The server rejects reserve/upload/commit for preview Sessions. For a plan with no independent automatic upload, execute pause before adding the mapping and running the preview; paused preview is supported. Preview receipts do not replace real upload receipts. 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 supports the same limit/cursor pagination plus optional --session. Cursors are bound to the selected filter. runs exposes persisted mapping run state, phase labels, error details and retryability, including background failures. Phase-deadline errors are currently misclassified and the failing phase can be overwritten; see the recurrence audit. 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; MSI system service is the supported Windows installation. Windows user-startup and Linux user-service packaging are retired. 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. Authentication goes through the daemon only: prepare pending token, save to the explicit protected credential location, activate it, and clear the recovery checkpoint. Retry auth with the same server/key/profile after uncertainty. DROSYNC_TOKEN overrides are rejected. Server/key/profile changes are refused while mappings, active work or recovery still bind the current identity. The canonical prior device-ID file is consumed once into SQLite to preserve identity; there is no path probing or ongoing dual source. 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, features.previewSessions=true, and features.credentialActivation=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 authoritative discovery scoped to the original mapping/space/device/credential, 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 v2 updates. update check returns policy, verified candidate metadata and the durable update ledger; on daemon IPC failure it can read local recovery state. Automatic offers are strictly newer SemVer versions and obey pin/pause policy. Install/rollback share one installer lock and preserve a verified baseline before any replacement. Only a native installation can self-update; preview and portable packages cannot cross formats. Windows user-startup and Linux user-service modes are retired.
update install requests OS authorization, verifies a private copy, and waits up to 90 seconds for the target daemon, installed-binary identity and matching attempt receipt. If readiness is not confirmed it attempts one verified baseline recovery; update rollback also supports recovery when daemon IPC is unavailable. Ledger changes are transactional. Native bootstrap, schema migration and real OS trust still require the documented release process. See update rollout.
doctor validates local integrity, identity, token/activation state, required server features/schema, upload grant and each mapping. ready=true means configuration/daemon checks passed; syncReady additionally requires an unpaused mapping. Neither is a BOS throughput or end-to-end acceptance result.
| 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.
Complete user workflows, failure recovery and current verification evidence: 1.0.5 closure manual.