19 KiB
CLI reference — 1.1.2
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. --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.
Starting with 1.1.2, upload scans exclude the legacy generated daily_report/ directory directly under the mapping's local root, matching report scans. Nested business directories with the same name and ordinary spreadsheet files remain eligible. The mapping's remote prefix is applied after this local filter.
Incremental scans skip an unchanged confirmed file only when its receipt belongs to a completed, non-preview session of the same mapping. Successful files from a partial session are sent in a new manifest so the server can confirm them again; matching current MD5 receipts produce unchanged without another content upload. After resolving the denied/failed files, use the new completed session ID for clean preview. Historical partial sessions keep their original status. A legacy SHA256-only archive remains denied: independent content verification and an explicit receipt migration or separate destination are still required. This change does not invent MD5 receipts or bypass clean checks. See the 1.1.2 diagnosis and recovery notes.
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. 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 MD5 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_<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.
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 MD5 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.
The known Linux race involving a same-size write after content verification remains unresolved in 1.1.2. Do not execute cleanup on files that can still be written; external producers must be stopped and their write handles closed. drosync pause does not stop external writers. The partial-session recovery procedure uses preview only; see the recorded failure and limits.
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 7; 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.6 closure manual.
1.0.6 metadata, timeout and BOS recovery changes: repair and verification.
1.0.7 V1.1 requirements, configuration, safe clean and file progress: review and implementation.
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.
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 for absent-source classifications and failure recovery.
1.0.32 adds a file inventory to the existing read-only web dashboard: total/completed/running/failed/missing/cleaned counts, exact paths and reasons, status/path search, and bounded pagination. Episode totals remain separate; report JSON includes the same file totals, while CSV/XLSX remain batch exports. Receipt-backed cloud sizes describe previous confirmations, not a live BOS integrity audit. See file report acceptance.