droboticflow/docs/drosync/cli-reference.md

76 lines
9.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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](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.