# CLI reference — 1.0.7 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; `episodes` owns CLI batch queries; `web` is the read-only daily-report/file-progress 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` | | Query batch details and mutually exclusive statuses | `drosync episodes [--mapping ID or --path ROOT] [--date D] [--status missing or completed or running or cleaned or all] [--cursor C] [--limit N]` | | Preview/delete cloud-verified completed local files | `drosync clean MAPPING --session SESSION [--execute]` | | 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 and per-file progress 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. Global `-c FILE` / `--config FILE` selects the shared literal runtime configuration file; Linux defaults to `/etc/drosync/environment`. Missing explicit files, obsolete/duplicate/unknown keys and old runtime environment variables are errors. See [all configuration keys and migration](runtime-configuration.md). `--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`, and `--require-https`. `DROSYNC_ACCESS_KEY_ID` / `DROSYNC_SECRET` environment inputs are retired; supply the explicit key flag and a protected file/stdin secret input. 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. Episodes/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 deadlines are typed retryable timeouts. `phase`/`failedPhase`, Session/operation/request IDs, retry timing and the last failure survive retry. Metadata progress names the requested endpoint, page/item, in-flight request, elapsed time and successful response-body bytes. See the [repair record](../../doc/drosync群反馈修复与验证-2026-10-08.md). These are local diagnostics. The platform Session/conflict pages provide paginated cloud management views; they do not operate the local daemon. ## Batches, per-file progress and daily reports `episodes` queries the requested day against current local files and confirmed local receipts. Date accepts `YYYY_MM_DD`, `YYYY-MM-DD`, `today` and `yesterday` (default today). `completed` requires a nonempty batch with every file confirmed and source identity unchanged; `running` means at least one in-progress item; explicitly cleaned batches are `cleaned` only when their exact latest receipt matches the durable cleanup ledger and the source remains absent; remaining batches, including unproven empty/failed/unverified batches, are `missing`. These four categories are mutually exclusive. A newly created same-name local source is analyzed normally and overrides cleanup history. JSON returns `counts` for all batches, filtered `matching`, bounded `items`, and `nextCursor`; human output is a table. Limits default to 100, range 1–1000. A fresh command rescans that day rather than pretending old statistics are current. Fully cleaned batch directories remain queryable even after their empty directories are removed. `cleanedFiles`/`cleanedSize` identify partially cleaned batches; this means the cloud was verified at cleanup time, not verified again by a report. The Web report date is selected from the browser calendar, initialized to the local day. Empty or incomplete dates do not send a request; choosing a day refreshes the report. Web serves only `/`, read-only `GET /api/report` and `GET /api/progress`; it has no control or export endpoints. Default binding is `127.0.0.1:8080`. The file-progress panel polls the selected mapping's latest-session SQLite samples about once per second (five seconds in hidden tabs), defaulting to active files. Each page contains at most 50 displayed files, with navigation and a latest-session-all view. It shows filename, bytes/total, percentage, sampled rate and phase. Sending 100% of the bytes is not a cloud commit: `waiting_commit` remains distinct from `completed`. Empty/idle states invent no progress; stale samples suppress the rate. Paused/interrupted/failed/missing states remain visible in latest-session history. No chunk is written to SQLite individually and progress refresh does not rescan the source tree. 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. `totalLocalEpisodes`/summary `localEpisodes` count locally identified batches including durable cleaned history; UI/export labels make this explicit. `totalCleanedEpisodes`, `totalCleanedFiles` and `totalCleanedSize` are separate from still-present confirmed batches. Cleaned history is joined by mapping/date prefix in bounded SQLite pages, never inferred from an empty directory. 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. ## Safe local cleanup `clean MAPPING --session SESSION` previews candidates; only `--execute` deletes them. Both local and current cloud Session must be `completed` and non-preview. The mapping must have no active/pending work or overlapping source roots. Only committed/unchanged files with matching source identity, full SHA256 and fresh cloud object proof are candidates; rejected/failed/skipped/keep-both or unverifiable receipts are retained. Cloud proof is authenticated and rate-limited, never served from the idempotency cache. Deletion uses an exclusive mapping gate, confined paths without following symlinks, a recoverable quarantine journal, verification and exact-file deletion. If the process stops, restart/retry recovers pending quarantined data; a newly created source at the same path is never overwritten. `status.cleanupRecovery` exposes manual recovery paths if automatic restore is unsafe. No buckets, cloud objects, entire source directories or unfinished files are cleanup targets. Keep the state database and quarantine directory until recovery completes. JSON reports `candidateFiles/Bytes`, `deletedFiles/Bytes`, `blockedFiles`, `recoveryNeeded` and up to 1000 detailed `files` with `filesTruncated`. Any blocked/recovery-needed result exits 50. A preview with zero candidates is not permission to use a recursive shell delete. Cleanup is a CLI-only control; Web remains read-only. ## 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` **configuration-file key** 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, the `DROSYNC_SECRET_FILE` **configuration-file key** 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`, `features.metadataRecovery=true`, `features.missingFileSkip=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](installation.md). ## 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](update-rollout.md). `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.6 closure manual](../../doc/drosync功能闭环使用与验收-2026-10-08.md). 1.0.6 metadata, timeout and BOS recovery changes: [repair and verification](../../doc/drosync群反馈修复与验证-2026-10-08.md). 1.0.7 V1.1 requirements, configuration, safe clean and file progress: [review and implementation](../../doc/drosync每日数据上传V1.1需求审查与实现-2026-10-08.md). 1.0.8 V1.1 requirement re-audit and corrections (missing-source batch inventory, Uploaded status, runtime log fallback, and failed-commit progress): [re-audit evidence](../../doc/drosync每日数据上传V1.1复审与修复-2026-10-08.md). 1.0.9 uses the union of current local files and all latest receipts for episode statistics, and atomically persists metadata pages with file progress. See [third requirement audit](../../doc/drosync每日上传需求第三次复核-2026-10-09.md) for absent-source classifications and failure recovery.