# 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__.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](installation.md). ## 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](update-rollout.md). | 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.