@moredrive/cli 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/build-info.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.4.0",
3
- "buildSha": "98b1cc9e125a0305fdeac6d25045435f37600743",
4
- "buildId": "release-20261105-v1.4.0-rc3"
2
+ "version": "1.5.0",
3
+ "buildSha": "1eba40e4d93abf33d341e4bf1d0aa6c19b44fe7d",
4
+ "buildId": "release-v1.5-20261117"
5
5
  }
package/commands.md CHANGED
@@ -1,11 +1,25 @@
1
1
  # CLI Commands
2
2
 
3
+ Use `moredrive --help` and `moredrive <command> --help` for the complete argument contract. Examples below use placeholders for account names, paths and IDs.
4
+
3
5
  Global options:
4
6
 
5
7
  ```bash
6
8
  moredrive [command] --base-url <url> --profile default --config ./config.json --json
7
9
  ```
8
10
 
11
+ | Option | Behavior |
12
+ | --- | --- |
13
+ | `--base-url <url>` | API endpoint override; disables profile session refresh for this invocation. |
14
+ | `--token <token>` | App-token override; prefer the environment to avoid exposing credentials in argv. |
15
+ | `--profile <name>`, `--config <path>` | Select a local profile or config file. |
16
+ | `--json`, `--jsonl` | Final JSON object or JSONL events; mutually exclusive. `stream` requires JSONL for machine output. |
17
+ | `--quiet`, `--verbose` | Suppress human diagnostics or enable redacted diagnostics on stderr. |
18
+ | `--upload-limit <rate>`, `--download-limit <rate>` | Override the process-wide upload/download budget without saving config. See transfer limits below. |
19
+ | `--timeout <ms>` | Positive API request timeout; distinct from operation wait timeouts and stream lifetime. |
20
+ | `--no-color` | Disable ANSI colors. |
21
+ | `--version`, `--help` | Print the executable version or help. |
22
+
9
23
  Environment variables:
10
24
 
11
25
  - `MOREDRIVE_BASE_URL`
@@ -21,6 +35,7 @@ Environment variables:
21
35
  moredrive login --username alice --password-stdin --save --json
22
36
  moredrive logout --json
23
37
  moredrive whoami --json
38
+ moredrive quota --json
24
39
  ```
25
40
 
26
41
  Worker APIs: `POST /api/auth/login`, `GET /api/auth/me`.
@@ -28,6 +43,10 @@ Worker APIs: `POST /api/auth/login`, `GET /api/auth/me`.
28
43
  `login` never prints the token. With `--save`, the token is stored in the selected profile.
29
44
  `--username` is required. Select exactly one password source: `--password` or `--password-stdin`.
30
45
 
46
+ App-token resolution uses the first non-empty value: `--token`, `MOREDRIVE_TOKEN`, selected profile `accessToken`, then legacy profile `token`. Multiple app-token sources are accepted with that precedence; they are not mutually exclusive. Password flags, share-token sources and `config set token` value sources are mutually exclusive within each group.
47
+
48
+ `login --save` stores access/refresh tokens and their expirations when the server provides a session. Saved profiles refresh access tokens automatically. Explicit `--token`/`MOREDRIVE_TOKEN` or `--base-url`/`MOREDRIVE_BASE_URL` overrides disable use of the profile refresh token for that invocation, even when the supplied base URL matches the saved URL. `logout` attempts refresh-session revocation and clears local credentials even if the server is unavailable. Inspect `data.serverRevocation`: only `revoked` or `already-revoked` confirms revocation; local removal alone does not. Legacy token-only profiles have no refresh session to revoke.
49
+
31
50
  ## Config
32
51
 
33
52
  ```bash
@@ -51,6 +70,8 @@ Config output redacts tokens and includes the resolved `download` profile defaul
51
70
  `partSizeBytes`, `multiRangeMinBytes`, `maxRequestsPerDownload`, and `downloadInflightBytes` must be positive
52
71
  integers; `dlinkSoftTtlSeconds`, `maxDlinkRefreshPerDownload`, and `progressIntervalMs` may be zero.
53
72
 
73
+ `config set token` accepts exactly one of a literal value, `--stdin`, or `--from-file <path>`. Stdin/file input is supported only for `token`. Prefer these over a literal token in argv. Config files support `moredrive.config.v2` (including shared CLI/Sync sessions) and legacy `moredrive.config.v1`; config updates preserve the Sync namespace. Transfer default keys are documented below.
74
+
54
75
  ## Drive
55
76
 
56
77
  ```bash
@@ -69,6 +90,18 @@ Worker APIs: `drive/list`, `drive/search`, `drive/file/:fs_id`, `drive/mkdir`, `
69
90
 
70
91
  `rm` requires `--yes`. Directory deletion also requires `--recursive`.
71
92
 
93
+ `MOREDRIVE_ASSUME_YES=1` also permits deletion. `rm --dry-run` inspects the target without submitting a deletion or requiring `--yes`; directory preflight still requires `--recursive`. `/` is always refused.
94
+
95
+ `ls` returns one page by default. Use `--start` for pagination or `--all` for all pages; JSON collection is bounded to 10,000 items, while JSONL emits `item` events as pages arrive. `--dirs-only` and `--files-only` filter entries.
96
+
97
+ `rename`, `mv`, `cp` and `rm` support `--idempotency-key`, `--wait`/`--no-wait`, `--operation-timeout` (default `10m`) and `--poll-interval` (default `750` ms, zero allowed). Retain the operation ID and idempotency key after uncertain submission; query the same operation rather than creating a new intent:
98
+
99
+ ```bash
100
+ moredrive operation status <operation-id> --json
101
+ ```
102
+
103
+ By default only `completed` exits 0; `--no-wait` also permits `accepted`. Other unfinished/failed statuses exit 1 (`cancelled` exits 130). A success envelope means the request succeeded, so inspect `data.status` and the exit code. A dry run is a local inspection result, not an operation completion.
104
+
72
105
  Recursive download:
73
106
 
74
107
  ```bash
@@ -77,7 +110,14 @@ moredrive download /docs --to ./downloads --recursive --jsonl
77
110
 
78
111
  This scans the complete Personal Drive tree and preserves `/docs/...` below the local root. It uses three file workers by default (`--file-concurrency 1-16`); `--concurrency` remains per-file Range concurrency. The scan is bounded at 5,000 files, 10,000 total entries, and 32 MiB of normalized metadata. Partial batches exit 1; `batch-limit-exceeded` exits 2. Empty directories complete without creating a local directory.
79
112
 
80
- Offline schema discovery accepts `schema output --revision 2|2.1` and `schema jsonl --revision 2|2.1`; default output is the latest `2.1` artifact.
113
+ Offline schema discovery prints schemas directly, without loading config or contacting the API:
114
+
115
+ ```bash
116
+ moredrive schema output --revision 2.1
117
+ moredrive schema jsonl --revision 2.1
118
+ ```
119
+
120
+ The default is revision `2.1`; `--revision 2` selects the immutable legacy artifact. Revision `2.1` covers recursive batches, media and streaming; the JSON envelope still uses `schemaVersion: "moredrive.cli.v2"`.
81
121
 
82
122
  Automation must close child stdin unless a command explicitly consumes it. For stdin commands, write the input and close the stream to deliver EOF. Drain stdout and stderr concurrently while the process runs; do not wait for process exit before reading JSONL. Credential stdin is limited to 64 KiB, while `write` is bounded by `--max-bytes`. SIGINT cancels a pending stdin read and returns exit 130.
83
123
 
@@ -91,12 +131,16 @@ moredrive download /docs/a.zip --to ./a.zip --concurrency 8 --part-size 64MiB --
91
131
  moredrive download /docs/a.zip --to ./a.zip --no-resume --overwrite --json
92
132
  moredrive download /docs/a.zip --to ./a.zip --user-agent pan.baidu.com --header "X-Trace: 1" --json
93
133
  moredrive read /docs/spec.md --max-bytes 1048576 --json
134
+ moredrive cat /docs/spec.md --max-bytes 1048576 --json
94
135
  moredrive upload ./a.md /docs/a.md --parents --json
95
136
  echo "hello" | moredrive write /docs/hello.txt --json
96
137
  echo "hello" | moredrive write /new/docs/hello.txt --parents --json
97
- echo "replacement" | moredrive write /docs/hello.txt --overwrite --idempotency-key <stable-key> --json
138
+ # Only for an authorized replacement; reuse this key for the same intent.
139
+ echo "replacement" | moredrive write /docs/hello.txt --overwrite --idempotency-key write-example-20261107 --json
98
140
  ```
99
141
 
142
+ `cat` is an alias for `read`; the default read bound is 1 MiB. `write` consumes stdin up to `--max-bytes` (default 10 MiB), creates only when absent, and requires `--overwrite` for replacement. `upload` is also create-only by default, supports `--parents`, `--dry-run`, `--content-type` and `--idempotency-key`, and defaults to six parallel slices (`--concurrency`). After an ambiguous write/upload, retry the same intent with its reported key, content, path and flags; keys must be 16-128 characters using letters, digits, `.`, `_`, `:`, or `-`.
143
+
100
144
  Download always uses `dlink` direct transport in Node and sends `User-Agent: pan.baidu.com` by default. CLI does not call Worker download proxy. Large files at or above `download.multiRangeMinBytes` use bounded multi-range requests when the dlink host supports `Range`; the default range part size is `64MiB` and default concurrency is `8`. Completed ranges are stored in `target.part.json` and can be resumed. Final targets are only renamed into place after all parts complete.
101
145
 
102
146
  Download flags:
@@ -111,9 +155,34 @@ Download flags:
111
155
  | `--header <name:value>` | none | Repeatable dlink request header; sensitive and downloader-controlled headers are rejected. |
112
156
  | `--recursive` | off | Download a Personal Drive directory as a preserved-path batch. |
113
157
  | `--file-concurrency <n>` | `3` | Concurrent files in recursive mode, from `1` to `16`. |
158
+ | `--preserve-path` | off | Preserve the remote file path below `--to`; recursive mode always preserves paths. |
114
159
 
115
160
  Upload requires `slice_upload_ticket` from `drive/upload/init` and uploads slices directly to the ticket endpoint. CLI does not fall back to Worker `drive/upload/slice`.
116
161
 
162
+ ## Transfer limits
163
+
164
+ `--upload-limit <rate>` and `--download-limit <rate>` accept bytes/second or explicit `KiB/s` and `MiB/s`; `0` means unlimited. Non-zero rates must resolve to an integer byte/second value no greater than 10 GiB/s. Invalid values fail locally. Persistent defaults live in the selected profile:
165
+
166
+ ```bash
167
+ moredrive config set transfer.uploadSpeedLimit '512 KiB/s'
168
+ moredrive config set transfer.downloadSpeedLimit '2 MiB/s'
169
+ moredrive upload ./example.bin /example.bin --upload-limit '128 KiB/s'
170
+ moredrive download /example.bin --to ./example.bin --download-limit 0
171
+ ```
172
+
173
+ Flags override defaults without saving them and may follow the subcommand. Upload and download each share a budget across files, connections and retries within one CLI process, including public-share downloads, `read`/`write` and local player streaming. Separate processes do not share budgets; login and listing are not throttled. Limits permit short bursts and do not guarantee throughput. Waiting for bandwidth is cancellable; real server-side task deadlines still apply.
174
+
175
+ ## Local player streaming
176
+
177
+ ```bash
178
+ moredrive stream /videos/example.mp4 --jsonl --quiet
179
+ moredrive stream fs_id:123 --port 0 --download-limit '2 MiB/s' --jsonl
180
+ ```
181
+
182
+ This authenticated Personal Drive command serves one file to VLC/mpv over a random `http://127.0.0.1:PORT/SESSION` URL, without downloading the complete file or launching a player. Wait for the JSONL `ready` event before opening its URL; keep the CLI running and drain stdout/stderr concurrently. `--json` is rejected. `--port` accepts `0-65535`, with `0` choosing a random port by default. `--media-mode auto` (default) decrypts supported marked media; `--media-mode raw` serves stored bytes. `--decrypt` remains an explicit selector.
183
+
184
+ The service lives until Ctrl+C/SIGTERM, including long player pauses, and the old URL fails after shutdown. It supports GET/HEAD and one byte Range, rejects multiple ranges, and requires reliable file content identity. Content changes or lost access terminate the service. The session URL grants access to the local stream: keep it private and stop the process after playback. JSONL emits `ready`, then exactly one top-level `result` or `failed`; normal stop returns `data.status: "stopped"`, while failures use the error envelope.
185
+
117
186
  ## Public Shares
118
187
 
119
188
  ### Save external Baidu shares (login required)
@@ -134,11 +203,12 @@ Only `completed` exits 0 by default. With `--no-wait`, `accepted` also exits 0.
134
203
  ### Read MoreDrive public shares
135
204
 
136
205
  ```bash
137
- moredrive share access <share-id> --password <code> --json
138
- moredrive share ls <share-id> / --share-token <token> --json
139
- moredrive share stat <share-id> fs_id:123 --share-token <token> --json
140
- moredrive share download <share-id> fs_id:123 --share-token <token> --to ./a.zip --json
141
- moredrive share download <share-id> fs_id:123 --share-token <token> --to ./a.zip --concurrency 8 --jsonl
206
+ moredrive share access <share-id> --password-stdin --save-token-to ./new-share-token --json
207
+ moredrive share ls <share-id> / --share-token-file ./new-share-token --json
208
+ moredrive share stat <share-id> fs_id:123 --share-token-file ./new-share-token --json
209
+ moredrive share read <share-id> fs_id:123 --share-token-file ./new-share-token --max-bytes 1048576 --json
210
+ moredrive share download <share-id> fs_id:123 --share-token-file ./new-share-token --to ./a.zip --json
211
+ moredrive share download <share-id> fs_id:123 --share-token-file ./new-share-token --to ./a.zip --concurrency 8 --jsonl
142
212
  ```
143
213
 
144
214
  Worker APIs: `share/:id/access`, `share/:id/list`, `share/:id/file`.
@@ -147,6 +217,10 @@ Share download uses `share file -> dlink -> direct download`. It supports the sa
147
217
  Use exactly one share token source: `--share-token`, `--share-token-file`, or `MOREDRIVE_SHARE_TOKEN`.
148
218
  `share access --save-token-to <new-path>` creates a 0600 file and refuses to overwrite an existing file or symbolic link.
149
219
 
220
+ ## Diagnostics
221
+
222
+ `moredrive diagnostics --json` queries basic API health without requiring login. It still reads and validates local config; unlike offline schema discovery, this command needs network access.
223
+
150
224
  ## Exit Codes
151
225
 
152
226
  | Code | Meaning |
@@ -166,6 +240,11 @@ Use exactly one share token source: `--share-token`, `--share-token-file`, or `M
166
240
 
167
241
  ## 显式媒体工具
168
242
 
243
+ ```bash
244
+ moredrive media encrypt ./photo.png --out ./photo.__md1x.png --json
245
+ moredrive media decrypt ./photo.__md1x.png --out ./restored.png --json
246
+ ```
247
+
169
248
  `moredrive media encrypt <input> --out <output>`、`media decrypt` 可未登录、断网使用。目录须加 `--recursive`;输出文件必须使用对应的 x1 标记/明文扩展名。输入不变,已有输出不覆盖,不跟随符号链接,目录结构保留。转换逐 64 KiB 流式处理;未知/重复/历史标记及类型冲突逐项报错。取消退出 130,部分失败退出非零并保留成功项。
170
249
 
171
250
  `moredrive media thumbnails /remote/directory --out /absolute/new-pack.mdtp --decoder /absolute/path/to/ffmpeg --json` 独立读取当前账户的远端个人目录,在本地生成兼容包,**尚未上传**。只复用身份匹配且有效的旧 poster;新视频使用累计有界 Range,不退回完整下载。生成步骤不调用云端文件写 API。仅本地媒体不能代替远端对象身份。
@@ -175,3 +254,24 @@ Use exactly one share token source: `--share-token`, `--share-token-file`, or `M
175
254
  输出包括所属账户、远端目录、逐项身份/结果/稳定原因、原媒体实际读取字节、旧包读取字节及产物路径。进度仅写 stderr。默认视频每请求最多 64 KiB、累计 8 MiB/256 请求/30 秒,重复读取和跳转计入预算;图片输入最多 128 MiB,单项解码最多 32M 像素,poster 最大 320×320/2 MiB。旧包读取限 512 MiB/180 秒,manifest 最大 64 MiB;超限安全失败,不修改云端。产物流式拼装,临时文件在输出同一文件系统,失败或取消回收。
176
255
 
177
256
  首次发布可用普通上传命令将产物显式上传到固定包名 `.__moredrive_thumbnails.__md1x.mdtp`。已有包须遵循普通上传显式冲突规则;日常增量维护推荐 Desktop 补齐。跨账户或重新上传原件会改变身份,需要重新生成。弱加密不能保护敏感信息。
257
+
258
+ ## v1.5 自动媒体处理
259
+
260
+ 普通 `upload`、`write`、`download`、`read`/`cat`、`share download`/`read` 和 `stream` 默认 `--media-mode auto`;`link --raw` 的含义不变。SDK 原始接口仍默认 raw。auto 上传按最终目录策略转换,下载清除支持标记并还原明文;未知/重复标记、已识别类型矛盾和输出名称碰撞停止该项,不自动退回原样。显式明文输出名不能带 `.__md` 保留标记,`--overwrite` 不绕过去标记碰撞。普通文件与真实缩略图包保持原字节。
261
+
262
+ ```sh
263
+ moredrive config set media.mode auto
264
+ moredrive config set media.thumbnails auto
265
+ moredrive config set media.decoderPath '/absolute/path with spaces/ffmpeg'
266
+ moredrive upload ./photo.png /photos/photo.png --thumbnails auto
267
+ moredrive download /photos/photo.__md1x.png --to ./photo.png
268
+ moredrive upload ./data.bin /backup/data.bin --media-mode raw --thumbnails off
269
+ ```
270
+
271
+ 单次参数优先于 profile;upload/write 还支持 `--decoder <absolute-path>`。非法枚举和相对 decoder 路径是参数错误;有效绝对路径缺失只影响缩略图。不会搜索 PATH、下载或安装 FFmpeg。`write` 保留有界 stdin 上限。
272
+
273
+ 原件结果位于 `data.completed`,表示决定位于 `data.media`,封面结果位于 `data.thumbnail`;封面 `unavailable`/`pending` 不把成功原件改为失败。仅本批新成功的弱媒体上传触发生成,重放回执不补图;失败可使用显式 `media thumbnails` 生成并单独上传。关闭缩略图仍对同目录已发起操作对账/安全回退,不启动新生成。发布待核对时保留配置目录内 `media-publications` 记录,不手动删除未知结果记录或他人 generation。
274
+
275
+ 包发布请求明确被拒绝时记录确定失败,在旧包身份未变、正式路径未被占用的前提下恢复旧包。恢复或清理明确失败后,后续对账可在重新核对身份后发起新的恢复/清理尝试;超时、限流、服务错误、幂等键冲突和结果不明不据此重放。正式路径被外部文件占用时保留外部文件、备份及恢复记录。
276
+
277
+ 显式云端图片补图使用有界完整 GET,不依赖 Range;解码器读取本地内存服务。视频仍使用受控 Range。显式媒体命令只生成本地结果,不自动发布。缩略图不额外 hash/快照/复核本地源,允许使用上传后改变的本地内容;原件传输完整性保护不变。
@@ -0,0 +1,60 @@
1
+ # AI Tooling Guide
2
+
3
+ Recommended defaults for agents:
4
+
5
+ ```bash
6
+ moredrive <command> --json --quiet
7
+ ```
8
+
9
+ Use `MOREDRIVE_TOKEN` for ephemeral automation. Use `--config` and `--profile` when a persistent local profile is required.
10
+
11
+ Start with the bundled `skills/moredrive-cli/SKILL.md`; `moredrive --help` prints its installed path. The [command guide](./commands.md) is the maintained reference. For long-running `stream`, use `--jsonl --quiet` instead of `--json`, wait for `ready`, and keep draining both output pipes until a terminal event. Offline `schema output` and `schema jsonl` print the schema itself, without a command-result envelope.
12
+
13
+ Safe read pattern:
14
+
15
+ ```bash
16
+ moredrive stat /docs/spec.md --json
17
+ moredrive read /docs/spec.md --max-bytes 1048576 --json
18
+ ```
19
+
20
+ Safe write pattern:
21
+
22
+ ```bash
23
+ printf '%s' "$CONTENT" | moredrive write /docs/output.md --max-bytes 1048576 --json
24
+ ```
25
+
26
+ This is create-only. Add `--overwrite` only when replacement is intended and authorized, after checking the target. Retain the reported idempotency key after an ambiguous write and retry the same content, path and flags with that key. Close stdin after supplying input; drain stdout and stderr concurrently.
27
+
28
+ Safe cleanup pattern:
29
+
30
+ ```bash
31
+ moredrive rm /tmp/agent-run --recursive --yes --json
32
+ ```
33
+
34
+ Recovery hints:
35
+
36
+ | `error.code` | Suggested action |
37
+ | --- | --- |
38
+ | `auth-required`, `auth-expired` | Ask user to log in or provide `MOREDRIVE_TOKEN`. |
39
+ | `not-found` | Re-list parent directory, then retry with the exact path. |
40
+ | `conflict` | Verify the local or remote target and obtain any missing replacement/destination-change authorization. |
41
+ | `invalid-argument` | Fix command arguments; do not retry unchanged. |
42
+ | `network-timeout`, `network-unreachable`, `upstream-error` | Retry with bounded backoff only when `error.retriable` is true; preserve the operation's recovery key. |
43
+ | `operation-submit-ambiguous` | Retry only the same intent with its reported idempotency key. |
44
+ | `unsupported` | Inspect the reason: direct-transfer capability, media decoder or file identity may be unavailable. |
45
+
46
+ Large outputs:
47
+
48
+ - `read` defaults to 1 MB.
49
+ - `write` defaults to 10 MB stdin limit.
50
+ - Use `download` for binary or large files.
51
+
52
+ Security:
53
+
54
+ - Never log `--token`, `MOREDRIVE_TOKEN`, share token, or raw dlink.
55
+ - Prefer `link` without `--raw`.
56
+ - Treat `link --raw`, `share access` token output and the `stream` session URL as sensitive output.
57
+
58
+ Saved profiles support automatic session refresh; explicit token/base-URL overrides disable profile refresh for that invocation. App tokens use argv > environment > profile precedence, while password and share-token input sources are mutually exclusive. See [authentication](./commands.md#auth) for details.
59
+
60
+ Use the command guide for [transfer limits](./commands.md#transfer-limits), [local playback](./commands.md#local-player-streaming), and explicit media conversion/thumbnail generation. A generated thumbnail pack remains local until separately uploaded. Ordinary transfers preserve file bytes.
package/docs/commands.md CHANGED
@@ -1,11 +1,25 @@
1
1
  # CLI Commands
2
2
 
3
+ Use `moredrive --help` and `moredrive <command> --help` for the complete argument contract. Examples below use placeholders for account names, paths and IDs.
4
+
3
5
  Global options:
4
6
 
5
7
  ```bash
6
8
  moredrive [command] --base-url <url> --profile default --config ./config.json --json
7
9
  ```
8
10
 
11
+ | Option | Behavior |
12
+ | --- | --- |
13
+ | `--base-url <url>` | API endpoint override; disables profile session refresh for this invocation. |
14
+ | `--token <token>` | App-token override; prefer the environment to avoid exposing credentials in argv. |
15
+ | `--profile <name>`, `--config <path>` | Select a local profile or config file. |
16
+ | `--json`, `--jsonl` | Final JSON object or JSONL events; mutually exclusive. `stream` requires JSONL for machine output. |
17
+ | `--quiet`, `--verbose` | Suppress human diagnostics or enable redacted diagnostics on stderr. |
18
+ | `--upload-limit <rate>`, `--download-limit <rate>` | Override the process-wide upload/download budget without saving config. See transfer limits below. |
19
+ | `--timeout <ms>` | Positive API request timeout; distinct from operation wait timeouts and stream lifetime. |
20
+ | `--no-color` | Disable ANSI colors. |
21
+ | `--version`, `--help` | Print the executable version or help. |
22
+
9
23
  Environment variables:
10
24
 
11
25
  - `MOREDRIVE_BASE_URL`
@@ -21,6 +35,7 @@ Environment variables:
21
35
  moredrive login --username alice --password-stdin --save --json
22
36
  moredrive logout --json
23
37
  moredrive whoami --json
38
+ moredrive quota --json
24
39
  ```
25
40
 
26
41
  Worker APIs: `POST /api/auth/login`, `GET /api/auth/me`.
@@ -28,6 +43,10 @@ Worker APIs: `POST /api/auth/login`, `GET /api/auth/me`.
28
43
  `login` never prints the token. With `--save`, the token is stored in the selected profile.
29
44
  `--username` is required. Select exactly one password source: `--password` or `--password-stdin`.
30
45
 
46
+ App-token resolution uses the first non-empty value: `--token`, `MOREDRIVE_TOKEN`, selected profile `accessToken`, then legacy profile `token`. Multiple app-token sources are accepted with that precedence; they are not mutually exclusive. Password flags, share-token sources and `config set token` value sources are mutually exclusive within each group.
47
+
48
+ `login --save` stores access/refresh tokens and their expirations when the server provides a session. Saved profiles refresh access tokens automatically. Explicit `--token`/`MOREDRIVE_TOKEN` or `--base-url`/`MOREDRIVE_BASE_URL` overrides disable use of the profile refresh token for that invocation, even when the supplied base URL matches the saved URL. `logout` attempts refresh-session revocation and clears local credentials even if the server is unavailable. Inspect `data.serverRevocation`: only `revoked` or `already-revoked` confirms revocation; local removal alone does not. Legacy token-only profiles have no refresh session to revoke.
49
+
31
50
  ## Config
32
51
 
33
52
  ```bash
@@ -51,6 +70,8 @@ Config output redacts tokens and includes the resolved `download` profile defaul
51
70
  `partSizeBytes`, `multiRangeMinBytes`, `maxRequestsPerDownload`, and `downloadInflightBytes` must be positive
52
71
  integers; `dlinkSoftTtlSeconds`, `maxDlinkRefreshPerDownload`, and `progressIntervalMs` may be zero.
53
72
 
73
+ `config set token` accepts exactly one of a literal value, `--stdin`, or `--from-file <path>`. Stdin/file input is supported only for `token`. Prefer these over a literal token in argv. Config files support `moredrive.config.v2` (including shared CLI/Sync sessions) and legacy `moredrive.config.v1`; config updates preserve the Sync namespace. Transfer default keys are documented below.
74
+
54
75
  ## Drive
55
76
 
56
77
  ```bash
@@ -69,6 +90,18 @@ Worker APIs: `drive/list`, `drive/search`, `drive/file/:fs_id`, `drive/mkdir`, `
69
90
 
70
91
  `rm` requires `--yes`. Directory deletion also requires `--recursive`.
71
92
 
93
+ `MOREDRIVE_ASSUME_YES=1` also permits deletion. `rm --dry-run` inspects the target without submitting a deletion or requiring `--yes`; directory preflight still requires `--recursive`. `/` is always refused.
94
+
95
+ `ls` returns one page by default. Use `--start` for pagination or `--all` for all pages; JSON collection is bounded to 10,000 items, while JSONL emits `item` events as pages arrive. `--dirs-only` and `--files-only` filter entries.
96
+
97
+ `rename`, `mv`, `cp` and `rm` support `--idempotency-key`, `--wait`/`--no-wait`, `--operation-timeout` (default `10m`) and `--poll-interval` (default `750` ms, zero allowed). Retain the operation ID and idempotency key after uncertain submission; query the same operation rather than creating a new intent:
98
+
99
+ ```bash
100
+ moredrive operation status <operation-id> --json
101
+ ```
102
+
103
+ By default only `completed` exits 0; `--no-wait` also permits `accepted`. Other unfinished/failed statuses exit 1 (`cancelled` exits 130). A success envelope means the request succeeded, so inspect `data.status` and the exit code. A dry run is a local inspection result, not an operation completion.
104
+
72
105
  Recursive download:
73
106
 
74
107
  ```bash
@@ -77,7 +110,14 @@ moredrive download /docs --to ./downloads --recursive --jsonl
77
110
 
78
111
  This scans the complete Personal Drive tree and preserves `/docs/...` below the local root. It uses three file workers by default (`--file-concurrency 1-16`); `--concurrency` remains per-file Range concurrency. The scan is bounded at 5,000 files, 10,000 total entries, and 32 MiB of normalized metadata. Partial batches exit 1; `batch-limit-exceeded` exits 2. Empty directories complete without creating a local directory.
79
112
 
80
- Offline schema discovery accepts `schema output --revision 2|2.1` and `schema jsonl --revision 2|2.1`; default output is the latest `2.1` artifact.
113
+ Offline schema discovery prints schemas directly, without loading config or contacting the API:
114
+
115
+ ```bash
116
+ moredrive schema output --revision 2.1
117
+ moredrive schema jsonl --revision 2.1
118
+ ```
119
+
120
+ The default is revision `2.1`; `--revision 2` selects the immutable legacy artifact. Revision `2.1` covers recursive batches, media and streaming; the JSON envelope still uses `schemaVersion: "moredrive.cli.v2"`.
81
121
 
82
122
  Automation must close child stdin unless a command explicitly consumes it. For stdin commands, write the input and close the stream to deliver EOF. Drain stdout and stderr concurrently while the process runs; do not wait for process exit before reading JSONL. Credential stdin is limited to 64 KiB, while `write` is bounded by `--max-bytes`. SIGINT cancels a pending stdin read and returns exit 130.
83
123
 
@@ -91,12 +131,16 @@ moredrive download /docs/a.zip --to ./a.zip --concurrency 8 --part-size 64MiB --
91
131
  moredrive download /docs/a.zip --to ./a.zip --no-resume --overwrite --json
92
132
  moredrive download /docs/a.zip --to ./a.zip --user-agent pan.baidu.com --header "X-Trace: 1" --json
93
133
  moredrive read /docs/spec.md --max-bytes 1048576 --json
134
+ moredrive cat /docs/spec.md --max-bytes 1048576 --json
94
135
  moredrive upload ./a.md /docs/a.md --parents --json
95
136
  echo "hello" | moredrive write /docs/hello.txt --json
96
137
  echo "hello" | moredrive write /new/docs/hello.txt --parents --json
97
- echo "replacement" | moredrive write /docs/hello.txt --overwrite --idempotency-key <stable-key> --json
138
+ # Only for an authorized replacement; reuse this key for the same intent.
139
+ echo "replacement" | moredrive write /docs/hello.txt --overwrite --idempotency-key write-example-20261107 --json
98
140
  ```
99
141
 
142
+ `cat` is an alias for `read`; the default read bound is 1 MiB. `write` consumes stdin up to `--max-bytes` (default 10 MiB), creates only when absent, and requires `--overwrite` for replacement. `upload` is also create-only by default, supports `--parents`, `--dry-run`, `--content-type` and `--idempotency-key`, and defaults to six parallel slices (`--concurrency`). After an ambiguous write/upload, retry the same intent with its reported key, content, path and flags; keys must be 16-128 characters using letters, digits, `.`, `_`, `:`, or `-`.
143
+
100
144
  Download always uses `dlink` direct transport in Node and sends `User-Agent: pan.baidu.com` by default. CLI does not call Worker download proxy. Large files at or above `download.multiRangeMinBytes` use bounded multi-range requests when the dlink host supports `Range`; the default range part size is `64MiB` and default concurrency is `8`. Completed ranges are stored in `target.part.json` and can be resumed. Final targets are only renamed into place after all parts complete.
101
145
 
102
146
  Download flags:
@@ -111,9 +155,34 @@ Download flags:
111
155
  | `--header <name:value>` | none | Repeatable dlink request header; sensitive and downloader-controlled headers are rejected. |
112
156
  | `--recursive` | off | Download a Personal Drive directory as a preserved-path batch. |
113
157
  | `--file-concurrency <n>` | `3` | Concurrent files in recursive mode, from `1` to `16`. |
158
+ | `--preserve-path` | off | Preserve the remote file path below `--to`; recursive mode always preserves paths. |
114
159
 
115
160
  Upload requires `slice_upload_ticket` from `drive/upload/init` and uploads slices directly to the ticket endpoint. CLI does not fall back to Worker `drive/upload/slice`.
116
161
 
162
+ ## Transfer limits
163
+
164
+ `--upload-limit <rate>` and `--download-limit <rate>` accept bytes/second or explicit `KiB/s` and `MiB/s`; `0` means unlimited. Non-zero rates must resolve to an integer byte/second value no greater than 10 GiB/s. Invalid values fail locally. Persistent defaults live in the selected profile:
165
+
166
+ ```bash
167
+ moredrive config set transfer.uploadSpeedLimit '512 KiB/s'
168
+ moredrive config set transfer.downloadSpeedLimit '2 MiB/s'
169
+ moredrive upload ./example.bin /example.bin --upload-limit '128 KiB/s'
170
+ moredrive download /example.bin --to ./example.bin --download-limit 0
171
+ ```
172
+
173
+ Flags override defaults without saving them and may follow the subcommand. Upload and download each share a budget across files, connections and retries within one CLI process, including public-share downloads, `read`/`write` and local player streaming. Separate processes do not share budgets; login and listing are not throttled. Limits permit short bursts and do not guarantee throughput. Waiting for bandwidth is cancellable; real server-side task deadlines still apply.
174
+
175
+ ## Local player streaming
176
+
177
+ ```bash
178
+ moredrive stream /videos/example.mp4 --jsonl --quiet
179
+ moredrive stream fs_id:123 --port 0 --download-limit '2 MiB/s' --jsonl
180
+ ```
181
+
182
+ This authenticated Personal Drive command serves one file to VLC/mpv over a random `http://127.0.0.1:PORT/SESSION` URL, without downloading the complete file or launching a player. Wait for the JSONL `ready` event before opening its URL; keep the CLI running and drain stdout/stderr concurrently. `--json` is rejected. `--port` accepts `0-65535`, with `0` choosing a random port by default. `--media-mode auto` (default) decrypts supported marked media; `--media-mode raw` serves stored bytes. `--decrypt` remains an explicit selector.
183
+
184
+ The service lives until Ctrl+C/SIGTERM, including long player pauses, and the old URL fails after shutdown. It supports GET/HEAD and one byte Range, rejects multiple ranges, and requires reliable file content identity. Content changes or lost access terminate the service. The session URL grants access to the local stream: keep it private and stop the process after playback. JSONL emits `ready`, then exactly one top-level `result` or `failed`; normal stop returns `data.status: "stopped"`, while failures use the error envelope.
185
+
117
186
  ## Public Shares
118
187
 
119
188
  ### Save external Baidu shares (login required)
@@ -134,11 +203,12 @@ Only `completed` exits 0 by default. With `--no-wait`, `accepted` also exits 0.
134
203
  ### Read MoreDrive public shares
135
204
 
136
205
  ```bash
137
- moredrive share access <share-id> --password <code> --json
138
- moredrive share ls <share-id> / --share-token <token> --json
139
- moredrive share stat <share-id> fs_id:123 --share-token <token> --json
140
- moredrive share download <share-id> fs_id:123 --share-token <token> --to ./a.zip --json
141
- moredrive share download <share-id> fs_id:123 --share-token <token> --to ./a.zip --concurrency 8 --jsonl
206
+ moredrive share access <share-id> --password-stdin --save-token-to ./new-share-token --json
207
+ moredrive share ls <share-id> / --share-token-file ./new-share-token --json
208
+ moredrive share stat <share-id> fs_id:123 --share-token-file ./new-share-token --json
209
+ moredrive share read <share-id> fs_id:123 --share-token-file ./new-share-token --max-bytes 1048576 --json
210
+ moredrive share download <share-id> fs_id:123 --share-token-file ./new-share-token --to ./a.zip --json
211
+ moredrive share download <share-id> fs_id:123 --share-token-file ./new-share-token --to ./a.zip --concurrency 8 --jsonl
142
212
  ```
143
213
 
144
214
  Worker APIs: `share/:id/access`, `share/:id/list`, `share/:id/file`.
@@ -147,6 +217,10 @@ Share download uses `share file -> dlink -> direct download`. It supports the sa
147
217
  Use exactly one share token source: `--share-token`, `--share-token-file`, or `MOREDRIVE_SHARE_TOKEN`.
148
218
  `share access --save-token-to <new-path>` creates a 0600 file and refuses to overwrite an existing file or symbolic link.
149
219
 
220
+ ## Diagnostics
221
+
222
+ `moredrive diagnostics --json` queries basic API health without requiring login. It still reads and validates local config; unlike offline schema discovery, this command needs network access.
223
+
150
224
  ## Exit Codes
151
225
 
152
226
  | Code | Meaning |
@@ -166,6 +240,11 @@ Use exactly one share token source: `--share-token`, `--share-token-file`, or `M
166
240
 
167
241
  ## 显式媒体工具
168
242
 
243
+ ```bash
244
+ moredrive media encrypt ./photo.png --out ./photo.__md1x.png --json
245
+ moredrive media decrypt ./photo.__md1x.png --out ./restored.png --json
246
+ ```
247
+
169
248
  `moredrive media encrypt <input> --out <output>`、`media decrypt` 可未登录、断网使用。目录须加 `--recursive`;输出文件必须使用对应的 x1 标记/明文扩展名。输入不变,已有输出不覆盖,不跟随符号链接,目录结构保留。转换逐 64 KiB 流式处理;未知/重复/历史标记及类型冲突逐项报错。取消退出 130,部分失败退出非零并保留成功项。
170
249
 
171
250
  `moredrive media thumbnails /remote/directory --out /absolute/new-pack.mdtp --decoder /absolute/path/to/ffmpeg --json` 独立读取当前账户的远端个人目录,在本地生成兼容包,**尚未上传**。只复用身份匹配且有效的旧 poster;新视频使用累计有界 Range,不退回完整下载。生成步骤不调用云端文件写 API。仅本地媒体不能代替远端对象身份。
@@ -175,3 +254,24 @@ Use exactly one share token source: `--share-token`, `--share-token-file`, or `M
175
254
  输出包括所属账户、远端目录、逐项身份/结果/稳定原因、原媒体实际读取字节、旧包读取字节及产物路径。进度仅写 stderr。默认视频每请求最多 64 KiB、累计 8 MiB/256 请求/30 秒,重复读取和跳转计入预算;图片输入最多 128 MiB,单项解码最多 32M 像素,poster 最大 320×320/2 MiB。旧包读取限 512 MiB/180 秒,manifest 最大 64 MiB;超限安全失败,不修改云端。产物流式拼装,临时文件在输出同一文件系统,失败或取消回收。
176
255
 
177
256
  首次发布可用普通上传命令将产物显式上传到固定包名 `.__moredrive_thumbnails.__md1x.mdtp`。已有包须遵循普通上传显式冲突规则;日常增量维护推荐 Desktop 补齐。跨账户或重新上传原件会改变身份,需要重新生成。弱加密不能保护敏感信息。
257
+
258
+ ## v1.5 自动媒体处理
259
+
260
+ 普通 `upload`、`write`、`download`、`read`/`cat`、`share download`/`read` 和 `stream` 默认 `--media-mode auto`;`link --raw` 的含义不变。SDK 原始接口仍默认 raw。auto 上传按最终目录策略转换,下载清除支持标记并还原明文;未知/重复标记、已识别类型矛盾和输出名称碰撞停止该项,不自动退回原样。显式明文输出名不能带 `.__md` 保留标记,`--overwrite` 不绕过去标记碰撞。普通文件与真实缩略图包保持原字节。
261
+
262
+ ```sh
263
+ moredrive config set media.mode auto
264
+ moredrive config set media.thumbnails auto
265
+ moredrive config set media.decoderPath '/absolute/path with spaces/ffmpeg'
266
+ moredrive upload ./photo.png /photos/photo.png --thumbnails auto
267
+ moredrive download /photos/photo.__md1x.png --to ./photo.png
268
+ moredrive upload ./data.bin /backup/data.bin --media-mode raw --thumbnails off
269
+ ```
270
+
271
+ 单次参数优先于 profile;upload/write 还支持 `--decoder <absolute-path>`。非法枚举和相对 decoder 路径是参数错误;有效绝对路径缺失只影响缩略图。不会搜索 PATH、下载或安装 FFmpeg。`write` 保留有界 stdin 上限。
272
+
273
+ 原件结果位于 `data.completed`,表示决定位于 `data.media`,封面结果位于 `data.thumbnail`;封面 `unavailable`/`pending` 不把成功原件改为失败。仅本批新成功的弱媒体上传触发生成,重放回执不补图;失败可使用显式 `media thumbnails` 生成并单独上传。关闭缩略图仍对同目录已发起操作对账/安全回退,不启动新生成。发布待核对时保留配置目录内 `media-publications` 记录,不手动删除未知结果记录或他人 generation。
274
+
275
+ 包发布请求明确被拒绝时记录确定失败,在旧包身份未变、正式路径未被占用的前提下恢复旧包。恢复或清理明确失败后,后续对账可在重新核对身份后发起新的恢复/清理尝试;超时、限流、服务错误、幂等键冲突和结果不明不据此重放。正式路径被外部文件占用时保留外部文件、备份及恢复记录。
276
+
277
+ 显式云端图片补图使用有界完整 GET,不依赖 Range;解码器读取本地内存服务。视频仍使用受控 Range。显式媒体命令只生成本地结果,不自动发布。缩略图不额外 hash/快照/复核本地源,允许使用上传后改变的本地内容;原件传输完整性保护不变。
@@ -1,6 +1,6 @@
1
1
  # JSON Contract
2
2
 
3
- Every `--json` command writes exactly one JSON object to stdout.
3
+ Completed `--json` actions write exactly one result envelope to stdout. Help/version are discovery output, and offline `schema output`/`schema jsonl` print the schema itself without an envelope. Long-running `stream` rejects `--json`; use `--jsonl`.
4
4
 
5
5
  Success:
6
6
 
@@ -54,5 +54,9 @@ Rules:
54
54
  - The JSONL schema is self-contained and can be compiled directly. Whole-stream validation additionally enforces command-family consistency, event ordering, terminal polarity, and no blank or trailing events.
55
55
  - `--json` and `--jsonl` are mutually exclusive.
56
56
  - `schema output/jsonl --revision 2` selects the legacy artifact; `2.1` and the default select the batch-aware artifact.
57
- - URLs containing `access_token`, token values, passwords, cookies, and Authorization headers are redacted unless the user explicitly asks for `link --raw`.
57
+ - Revision `2.1` also describes current media/stream commands; artifact revision `2.1` is distinct from envelope `schemaVersion: "moredrive.cli.v2"`.
58
+ - Credentials and provider URLs are redacted from ordinary outputs. Intentional sensitive outputs are the provider URL from `link --raw`, the token from `share access` without `--save-token-to`, and the local session URL from `stream`.
58
59
  - Recursive download success data uses `kind: "batch"` with stable item ordering. Batch items never expose provider `fsId`, raw metadata, dlinks, or headers; partial batch success still uses a success envelope and exits 1.
60
+ - `ok: true` reports a successful action/status request, not necessarily a completed operation. Inspect `data.status`, item outcomes and exit code for file operations, external saves and media batches. `--no-wait` allows accepted submissions to exit 0.
61
+ - `stream --jsonl` emits `ready` with `command: "stream"`, `url`, `fsId`, `size`, and `decrypted`, then exactly one `result` or `failed`. Keep reading while the player uses the service; Ctrl+C/SIGTERM normally returns a result with `status: "stopped"` and `bytesServed`.
62
+ - Media conversion and thumbnail generation report per-item status/reason in the final result. Progress diagnostics go to stderr; JSONL still has one top-level terminal event. Thumbnail results include `uploaded: false` and a local pack path; creation alone does not publish a cloud pack.
@@ -1,4 +1,29 @@
1
- # MoreDrive CLI 1.3
1
+ # MoreDrive CLI
2
+
3
+ ## 1.5.0
4
+
5
+ v1.5.0 发行候选;正式上架状态以官网下载目录为准。
6
+
7
+ - 普通传输默认 auto;支持策略驱动弱媒体转换,raw 可固定原字节行为,SDK 默认不变。
8
+ - 新成功上传使用本批本地来源生成并发布兼容封面;FFmpeg 显式配置,缺失仅影响派生结果。
9
+ - 支持 `media.mode`、`media.thumbnails`、`media.decoderPath` 与命令覆盖;JSON revision 2.1 扩展,revision 2 保持不变。
10
+ - 原件转换失败停止该项;封面失败显式补齐,持久发布记录仅用于已发起操作的核对及必要回退。
11
+
12
+ - 修复 macOS 临时目录别名导致自动封面被误判为不安全输出的问题。
13
+
14
+ ## 1.4.0
15
+
16
+ - `stream` serves one Personal Drive file to a local VLC/mpv player over loopback, with bounded Range reads, optional explicit decryption, JSONL `ready` discovery and foreground lifetime until shutdown. `--json` is rejected for this long-running command.
17
+ - `media encrypt` and `media decrypt` provide explicit offline conversion without changing input files or overwriting outputs. `media thumbnails` reads the current account's remote directory and creates a local compatible pack using an explicitly provided FFmpeg; uploading the pack is a separate step. Ordinary transfers preserve bytes.
18
+ - Upload/download limits can be configured per profile or overridden with `--upload-limit`/`--download-limit`. Each direction shares one budget across transfers within a CLI process.
19
+ - Saved login sessions support access-token refresh and best-effort server revocation on logout. Token or base-URL overrides disable profile refresh for that invocation. App tokens use argv/environment/profile precedence; password and share-token input groups remain mutually exclusive.
20
+ - This historical release used package version `1.4.0`; envelope version remains `moredrive.cli.v2`, and current offline schema artifacts are revision `2.1`.
21
+
22
+ ### Documentation maintenance after release
23
+
24
+ The source documentation now covers playback, media tools, limits and session recovery; examples default to create-only writes. Packaging preserves offline schema guidance in the Skill and renders the README filename from the package version. These maintenance changes apply to subsequent builds; already published/frozen 1.4.0 bytes are not rewritten.
25
+
26
+ ## 1.3.0 (historical)
2
27
 
3
28
  - Recursive Personal Drive downloads are available with `download <directory> --recursive`; they preserve remote paths, use bounded file/Range concurrency, and report completed/partial/failed batch results. Scan limits are 5,000 files, 10,000 entries, and 32 MiB metadata.
4
29
  - Batch-aware schema artifacts are published as `v2.1`; offline schema discovery accepts explicit revisions `2` and `2.1`. Revision `2` remains byte-for-byte immutable and validates only the legacy command surface; recursive batch consumers must use `2.1`.
@@ -10,6 +35,6 @@
10
35
  - Offline `schema output` and `schema jsonl` are available without config, token, or network access.
11
36
  - Corrupt or incompatible config is `config-error`/exit 3 and must not be retried as a network failure.
12
37
  - Credential argv remains supported for compatibility but is not recommended. Prefer environment, stdin, and file handoff options.
13
- - Credential sources are mutually exclusive. Share-token file handoff creates a new 0600 file and refuses existing files or symbolic links.
38
+ - Password flags, share-token sources and config token value sources are mutually exclusive. App tokens use argv/environment/profile precedence. Share-token file handoff creates a new 0600 file and refuses existing files or symbolic links.
14
39
  - SIGINT is carried through destructive `rm` preflight and submission, so cancellation during stat cannot continue into deletion.
15
40
  - The file package now contains the Skill, release docs, and schemas. The package filename, manifest, executable, and User-Agent use the CLI package version (`1.3.0`).
@@ -112,6 +112,28 @@
112
112
  "required": [],
113
113
  "additionalProperties": false
114
114
  },
115
+ "media": {
116
+ "type": "object",
117
+ "properties": {
118
+ "mode": {
119
+ "enum": [
120
+ "auto",
121
+ "raw"
122
+ ]
123
+ },
124
+ "thumbnails": {
125
+ "enum": [
126
+ "auto",
127
+ "off"
128
+ ]
129
+ },
130
+ "decoderPath": {
131
+ "type": "string"
132
+ }
133
+ },
134
+ "required": [],
135
+ "additionalProperties": false
136
+ },
115
137
  "createdAt": {
116
138
  "type": "string"
117
139
  },