命令参考

本文档详细说明 360disk CLI 支持的 8 个顶级命令组、共 31 个子命令及其参数。

更新时间：2026-05-11

鉴权管理 (auth)

登录并保存 API Key 到本地配置文件。

360disk auth login --api-key <api_key> [--env <env>] [--sub-channel <channel>]

参数

参数名	类型	必填	说明	默认值
`--api-key`	string	✅	API 密钥	—
`--env`	string	❌	环境（prod / test）	`prod`
`--sub-channel`	string	❌	子渠道	`open`

示例

# 登录生产环境
360disk auth login --api-key yunpan_abc123

# 登录测试环境
360disk auth login --api-key yunpan_test456 --env test

输出示例

{
  "success": true,
  "result": {
    "message": "登录成功",
    "configPath": "/Users/you/.360disk/config.json"
  },
  "meta": { "duration_ms": 2, "command": "auth login" }
}

使用 微信扫描小程序登录二维码 完成鉴权，服务端签发 SSO Cookie 后通过 Oauth.getApiKeyByQT 换取 api_key，并写入本地配置（login_mode 等为微信扫码）。

终端流程（未显式写 --format json 且通常未单独使用 --quiet）：默认在终端输出字符二维码；也可 --qr-mode file 将 PNG 写入本地路径（或临时目录），手机扫描图片完成登录。
流式 JSON（显式 --format json，或与 --quiet 组合进入两行输出模式）：stdout 第一行为二维码元数据，stdout 第二行为登录结束后的完整结果 JSON；宿主无需终端绘图，适合 Agent / IDE 插件解析。

360disk auth login-wechat [--timeout <sec>] [--interval <ms>] [--qr-mode <terminal|file>] [--qr-file <path>] [--env <env>] [--sub-channel <channel>] [--format <json|text>] [--quiet]

参数

参数名	类型	必填	说明	默认值
`--timeout`	number	❌	轮询总超时（秒）	`120`
`--interval`	number	❌	轮询间隔（毫秒）	`1500`
`--qr-mode`	string	❌	二维码呈现：`terminal`（终端字符码）或 `file`（落盘 PNG）	`terminal`
`--qr-file`	string	❌	与 `--qr-mode=file` 联用时指定 PNG 绝对/相对路径；未指定则写入系统临时目录	—
`--env`	string	❌	环境（`prod` / `test`）	`prod`
`--sub-channel`	string	❌	子渠道	`open`
`--format`	string	❌	输出格式（与子命令一致时生效）	`json`
`--quiet`	flag	❌	静默	—

--qr-file 说明

仅在 --qr-mode=file 时生效；terminal 模式下若误传 --qr-file 会被忽略。

输出行为

1）阻塞终端流程（未显式 --format json 且未仅依赖 --quiet 走两行模式时）

stderr：进度文案。
--qr-mode=terminal（默认）：字符矩阵二维码输出到终端（解码自服务端 PNG）。
--qr-mode=file：将服务端返回的 PNG 写入 --qr-file 给定路径（未给则自动生成临时文件名），stderr 打印绝对路径提示扫码。
登录成功后：stdout 为普通 CLIResponse JSON，或 --format text 时的简短文案。

2）流式 JSON（显式 --format json，或与 --quiet 触发的两行模式）

第一行（发起轮询之前立即打印，单行紧凑 JSON）：
- 当 --qr-mode=terminal（默认） 时，type 为 qr，字段包括：qr_key、qr_image_data_url（data:image/png;base64,...，兼容旧版集成）、 qr_image_mime（image/png）、 qr_image_base64（裸 Base64，便于宿主自行拼接 data:${mime};base64,${base64}）、expires_in（秒，对应 --timeout）。
- 当 --qr-mode=file 时，type 为 qr_file，含 qr_key、 qr_image_path（PNG 绝对路径）、qr_image_mime、expires_in；不内联长 Base64/Data URL，适合禁止 data: URL、或应以本地文件附件展示二维码的场景。
第二行：登录结束后输出完整 success / result / meta（与普通命令一致的 CLI JSON）。

第一行吐出后 CLI 会持续轮询扫码状态直至成功或超时。

示例

360disk auth login-wechat
360disk auth login-wechat --env test --timeout 180

# 终端流程：PNG 写到指定路径后再用微信扫码该图片
360disk auth login-wechat --qr-mode file --qr-file /tmp/360disk-wechat-qr.png

# 流式 JSON：集成方读取两行 stdout（可先仅读第一行渲染二维码）
360disk auth login-wechat --format json

# 流式 JSON + 文件模式：首行 small payload（qr_file），由宿主打开 qr_image_path 展示
360disk auth login-wechat --format json --qr-mode file --qr-file /tmp/360disk-wechat-qr.png

成功时 result 常见字段

message（如「微信扫码登录成功」）、login_mode（wechat_qr）、qid、username、nickname、configPath。

常见错误码

code	含义
`22`	扫码轮询超时
`27`	换取 API Key 失败（如云盘 `Oauth.getApiKeyByQT` 返回业务错误）

更多扫码专用错误码见进阶用法 · 错误码。

auth whoami

查看当前鉴权状态。API Key 部分脱敏显示。

360disk auth whoami

参数

无参数

提示

若使用 微信扫码登录（auth login-wechat），result 中还可包含 login_mode: "wechat_qr" 与 sso_user（如 qid、nickname）等字段。

输出示例

{
  "success": true,
  "result": {
    "logged_in": true,
    "api_key": "yunpan_abc***",
    "ecs_env": "prod",
    "sub_channel": "open",
    "config_path": "/Users/you/.360disk/config.json"
  },
  "meta": { "duration_ms": 1, "command": "auth whoami" }
}

Text 格式输出（--format text）：

已登录
API Key: yunpan_abc***
环境: prod
渠道: open

auth logout

退出登录，清除本地配置文件。

360disk auth logout

参数

无参数

用户信息 (user)

user info

获取当前账号的用户详细信息，包括昵称、QID、存储空间、VIP 等级等。

360disk user info

参数

无参数

输出示例

JSON 格式：

{
  "success": true,
  "result": {
    "data": {
      "nickname": "张三",
      "qid": "123456",
      "space_used": 1073741824,
      "space_total": 10737418240,
      "vip_type": "普通用户"
    }
  },
  "meta": { "duration_ms": 156, "command": "user info" }
}

Text 格式（--format text）：

昵称: 张三
QID: 123456
空间: 1.00 GB / 10.00 GB
VIP: 普通用户

提示

Text 格式兼容多种 API 返回字段，无论接口返回 name/nickname、used_size/space_used 等不同命名，均可正确显示。

目录操作 (dir)

dir ls

列出云盘指定目录下的文件和文件夹，支持分页查询。

360disk dir ls [path] [--page <n>] [--size <n>]

参数

参数名	类型	必填	说明	默认值
`path`	string	❌	目录路径	`/`
`--page`	number	❌	页码（从 0 开始）	`0`
`--size`	number	❌	每页数量	`50`

示例

# 列出根目录
360disk dir ls

# 列出指定目录
360disk dir ls /工作目录/

# 分页查询
360disk dir ls /工作目录/ --page 1 --size 20

关于示例中的“目录名”

这里的 /工作目录/ 只是目录路径示例（文件夹），不是“文档类型”。你也可以替换为自己网盘里的任意目录路径。

输出示例

Text 格式（--format text）：

类型  名称          大小       修改时间            NID
----  ----          ----       --------            ---
d     工作目录      -          2026-03-20 14:30    abc123
d     图片          -          2026-03-18 09:15    def456
-     readme.txt    1.2 KB     2026-03-22 16:45    ghi789
共 3 项，第 0 页

dir mkdir

创建新文件夹。

360disk dir mkdir <path>

参数

参数名	类型	必填	说明
`path`	string	✅	文件夹路径

示例

# 创建一级目录
360disk dir mkdir /工作目录/

# 创建多级目录
360disk dir mkdir /工作/项目A/文件夹/

注意

文件夹路径必须以 / 开头

文件操作 (file)

file mv

移动文件或文件夹到目标目录，支持批量移动。

360disk file mv <src> <dest>

参数

参数名	类型	必填	说明
`src`	string	✅	源路径，多个文件用 `\|` 分隔
`dest`	string	✅	目标文件夹路径

示例

# 移动单个文件
360disk file mv /文件夹/草稿.docx /归档/

# 移动单个目录（src 末尾 / 可省略，CLI 会自动按目录重试）
360disk file mv /文件夹/项目资料 /归档/

# 移动路径含空格的文件（必须加引号）
360disk file mv "/我的文档/报告 2026.docx" "/归档/"

# 批量移动（| 在 shell 中是管道符，必须用引号包裹整个 src）
360disk file mv "/文件夹/a.txt|/文件夹/b.txt" "/归档/"

路径引号规则

路径含空格：必须用双引号包裹，否则 shell 会将空格解析为参数分隔符
多文件 | 分隔：| 是 shell 管道符，整个 src 参数必须用引号包裹
错误写法：360disk file mv /文件夹/a.txt|/文件夹/b.txt /归档/（会被 shell 解析为管道）
正确写法：360disk file mv "/文件夹/a.txt|/文件夹/b.txt" "/归档/"

获取精确路径

使用 360disk dir ls <目录> 查看文件列表，复制 名称 列的精确路径（包含空格和大小写），避免手动输入出错。

目录路径兼容

file mv 在移动单个目录时，src 末尾 / 可以省略。
例如 360disk file mv /项目资料 /归档/ 与 360disk file mv /项目资料/ /归档/ 均可。

file trans-copy

将一个或多个文件转移或复制到目标目录。

360disk file trans-copy <src> <dest> [--delete <0|1>] [--replace <0|1>] [--src-ks-id <id>] [--new-ks-id <id>]

参数

参数名	类型	必填	说明
`src`	string	✅	源文件完整路径，多个路径用 `\|` 分隔
`dest`	string	✅	目标目录路径，必须以 `/` 开头
`--delete`	number	❌	是否删除源文件：`1`=转移，`0`=复制，默认 `1`
`--replace`	number	❌	同名处理策略：`0`=重命名，`1`=覆盖，默认 `0`
`--src-ks-id`	string	❌	源文件所在群组 `ks_id`
`--new-ks-id`	string	❌	目标目录所在群组 `ks_id`

注意

多路径转移/复制时，src 中包含 |，必须整体使用引号包裹。
例如："/文档/a.txt|/文档/b.txt"。

示例

# 转移（默认：删除源文件）
360disk file trans-copy "/文档/a.txt|/文档/b.txt" /归档/

# 复制并覆盖同名文件
360disk file trans-copy /文档/a.txt /备份/ --delete 0 --replace 1

file rename

重命名文件或文件夹。

360disk file rename <path> <new_name>

参数

参数名	类型	必填	说明
`path`	string	✅	原文件/文件夹完整路径（文件夹需以 `/` 结尾）
`new_name`	string	✅	新名称（仅名称，不含父路径）。文件夹末尾 `/` 可省略，CLI 会自动补齐

示例

# 文件重命名
360disk file rename /文件夹/草稿.docx 最终报告.docx

# 文件夹重命名（以下三种写法等效，CLI 自动归一化）
360disk file rename "/我的知识库/" "新知识库"
360disk file rename "/我的知识库/" "新知识库/"
360disk file rename "/我的知识库/" "/新知识库/"

文件夹 new_name 自动归一化

CLI 会自动处理文件夹 new_name 的格式：

末尾 / 可省略，CLI 自动补齐
前导 / 可保留，CLI 自动去掉
若含多级路径（如 a/b），只取最后一段目录名

文件 new_name 不能含路径

文件重命名时，new_name 只能是纯文件名（不含 /）。
如需移动文件到其他目录，请使用 file mv 命令。

file rm

删除文件或文件夹，支持批量删除。

360disk file rm <path> [--batch]

参数

参数名	类型	必填	说明
`path`	string	✅	文件路径，多个用 `\|` 分隔
`--batch`	boolean	❌	批量模式：同时从 stdin 读取路径列表（每行一个）

示例

# 删除单个文件
360disk file rm /临时/test.txt

# 删除目录（末尾 / 可省略，CLI 自动识别）
360disk file rm /bbb/mydir/
360disk file rm /bbb/mydir      # 与上面等效

# 删除多个文件（| 必须在引号内）
360disk file rm "/临时/a.txt|/临时/b.txt"

# 批量删除（macOS/Linux，推荐：stdin 管道；支持文件与目录混合）
cat paths.txt | 360disk file rm /临时/e.txt --batch

Windows 使用说明

Windows 不支持 echo -e "...\\n..." | 360disk file rm ... --batch 这种删除命令。
Windows cmd 中带括号的 (echo ... & echo ...) | ... 写法也不推荐/不兼容，请不要使用。
cmd 请改用文件管道：type paths.txt | 360disk file rm /临时/e.txt --batch
PowerShell 可用："/临时/c.txtn/bbb/mydir" | 360disk file rm /临时/e.txt --batch`

删除目录

删除目录时，路径末尾的 / 可以省略，CLI 会先按文件尝试删除，若文件不存在则自动补 / 重试（目录模式）。/bbb/mydir 和 /bbb/mydir/ 均可正确删除目录。

注意

多文件删除时，| 必须在引号内。含大量文件时推荐 --batch + stdin 管道模式。

批量模式输出

每项独立记录成功/失败，失败不中断整批，整体 success: true 表示请求本身正常完成（非所有子项都成功）。

全部成功示例：

{
  "success": true,
  "result": {
    "total": 3,
    "succeeded": 3,
    "failed": 0,
    "items": [
      { "index": 0, "input": "/临时/e.txt", "success": true,
        "result": { "errno": 0, "errmsg": "", "data": true } },
      { "index": 1, "input": "/临时/c.txt", "success": true,
        "result": { "errno": 0, "errmsg": "", "data": true } },
      { "index": 2, "input": "/临时/d.txt", "success": true,
        "result": { "errno": 0, "errmsg": "", "data": true } }
    ]
  },
  "meta": { "duration_ms": 980, "command": "file rm --batch" }
}

部分失败示例（文件不存在等）：

{
  "success": true,
  "result": {
    "total": 3,
    "succeeded": 1,
    "failed": 2,
    "items": [
      { "index": 0, "input": "/临时/not-exist-1.txt", "success": false,
        "error": "源文件不存在 (errno: 3008)" },
      { "index": 1, "input": "/临时/e.txt", "success": true,
        "result": { "errno": 0, "errmsg": "", "data": true } },
      { "index": 2, "input": "/临时/not-exist-2.txt", "success": false,
        "error": "源文件不存在 (errno: 3008)" }
    ]
  },
  "meta": { "duration_ms": 930, "command": "file rm --batch" }
}

如何判断批量操作是否完全成功

检查 result.failed === 0，或遍历 result.items 查看 success: false 的项。

file search

按关键词搜索云盘文件，支持按文件类型筛选和分页查询。

360disk file search <keyword> [--type <type>] [--page <n>] [--size <n>]

参数

参数名	类型	必填	说明	默认值
`keyword`	string	✅	搜索关键词	—
`--type`	number	❌	文件类型筛选（见下表）	`-1`
`--page`	number	❌	页码（从 1 开始）	`1`
`--size`	number	❌	每页数量	`20`

文件类型：

值	说明
`-1`	全部类型
`0`	其他
`1`	图片
`2`	文档
`3`	音乐
`4`	视频

示例

# 搜索所有类型
360disk file search "报告"

# 仅搜索文档
360disk file search "报告" --type 2

# 搜索视频并分页
360disk file search "会议" --type 4 --page 1 --size 10

分页提示

当 --page 超过最大页数时，接口会返回空列表，Text 格式（--format text）会显示“无搜索结果”。建议先用 --page 1 确认是否有数据，再逐页翻看。

输出示例

Text 格式（--format text）：

类型  名称              大小       路径                NID
----  ----              ----       ----                ---
-     年度报告.pdf      2.5 MB     /文件夹/              abc123
-     月度报告.xlsx     156 KB     /文件夹/月报/         def456
共找到 2 项

为文件生成分享链接，支持批量分享。

360disk file share <paths>

参数

参数名	类型	必填	说明
`paths`	string	✅	文件路径，多个用 `\|` 分隔

示例

# 分享单个文件
360disk file share /文件夹/报告.pdf

# 分享多个文件（| 必须在引号内）
360disk file share "/文件夹/报告.pdf|/文件夹/数据.xlsx"

注意

多文件分享时，含 | 的参数必须用引号包裹。

file url

获取文件的下载链接。可通过文件路径或 NID 获取。

360disk file url <path> [--nid <nid>]

参数

参数名	类型	必填	说明
`path`	string	✅	文件路径（指定 `--nid` 时可填任意值）
`--nid`	string	❌	文件 NID，指定时忽略 path 参数

示例

# 通过路径获取下载链接
360disk file url /文件夹/报告.pdf

# 通过 NID 获取
360disk file url _ --nid abc123def

提示

NID 可通过 dir ls 或 file search 命令获取

file node-info

根据单个 nid 获取节点信息（可选返回 ks_info）。

360disk file node-info <nid> [--ks-ext <0|1>]

参数

参数名	类型	必填	说明
`nid`	string	✅	节点 nid（仅支持文件夹/知识库）
`--ks-ext`	number	❌	是否返回 ks_info：`0`=不返回，`1`=返回，默认 `0`

示例

# 查询基础节点信息
360disk file node-info 17454790191978055

# 查询节点信息并返回 ks_info
360disk file node-info 17454790191978055 --ks-ext 1

file origin-size

统计目录下所有文件和文件夹（递归）的原始大小。

360disk file origin-size <path>

参数

参数名	类型	必填	说明
`path`	string	✅	目录完整路径，必须以 `/` 开头

示例

360disk file origin-size /mcp/ai-test/666/

file clear-dir

清空目录下文件，保留目录本身（直接删除，不进入回收站）。

360disk file clear-dir <path>

参数

参数名	类型	必填	说明
`path`	string	✅	单个目录路径，必须以 `/` 开头（勿用 `\|` 拼接多个目录，会触发服务端非法字符错误 errno:3022）

注意

该操作具有破坏性，目录中的文件将被直接删除。
每次只支持一个目录；多个目录请逐条执行 file clear-dir，或在脚本中循环调用。

示例

# 清空单个目录
360disk file clear-dir /临时目录/

# 多个目录须分多次执行（勿使用 path1|path2）
360disk file clear-dir /临时目录A/
360disk file clear-dir /临时目录B/

file config

读取/写入/列出配置文件（INI/JSON/YAML）。

360disk file config --path <path> --command <config:*> --type <ini|json|yaml|yml> [--key <key>] [--value <value>] [--content <text>|--stdin]

参数

参数名	类型	必填	说明
`--path`	string	✅	配置文件路径，必须以 `/` 开头
`--command`	string	✅	操作命令：`config:get` / `config:set` / `config:delete` / `config:list` / `config:read` / `config:write`
`--type`	string	✅	配置类型：`ini` / `json` / `yaml` / `yml`
`--key`	string	❌	键路径（如 `app.debug`）
`--value`	string	❌	写入值（`config:set` 场景）
`--content`	string	互斥	整文件内容（仅 `config:write` 场景，与 `--stdin` 互斥）
`--stdin`	boolean	互斥	从标准输入读取整文件内容（仅 `config:write` 场景）

注意

--content 与 --stdin 互斥，且仅在 --command config:write 场景可使用。
其他命令传入 --content/--stdin 会报参数错误。

读取结果在哪看（避免误以为「返回为空」）

默认 JSON（不加 --format text）：响应为 { success, result, meta }，接口体在 result 中，整文件读取看 result.data.config（config:read）。使用 --quiet 时 stdout 仅为接口 JSON，可用 jq '.data.config'。未使用 --quiet 时用 jq '.result.data.config'。
--format text：新版本会在成功提示下方直接打印上述内容（config:read / config:get / config:list 以可读文本或缩进 JSON 展示）。旧版 text 模式曾只打一行成功提示，易被误认为没有数据。

示例

# 读取 JSON 中某个键
360disk file config --path /mcp/app.json --command config:get --type json --key app.name

# 设置 JSON 键值
360disk file config --path /mcp/app.json --command config:set --type json --key app.debug --value true

# 读取整个 YAML
360disk file config --path /mcp/app.yml --command config:read --type yml

# 通过 stdin 写入完整 JSON（macOS / Linux）
cat local-config.json | 360disk file config --path /mcp/app.json --command config:write --type json --stdin

Windows 用法（config:write + --stdin）

config:write 需从管道读入内容；Windows cmd 没有 cat，请使用：

cmd：type local-config.json | 360disk file config --path /mcp/app.json --command config:write --type json --stdin
PowerShell：Get-Content .\local-config.json -Raw | 360disk file config --path /mcp/app.json --command config:write --type json --stdin

file save

通过 URL 或文本内容保存文件到云盘。支持三种数据源（三者互斥）。

360disk file save --url <url> [--dest <path>] [--filename <name>] [--rename <0|1>]
360disk file save --content <text> [--dest <path>] [--filename <name>] [--rename <0|1>]
360disk file save --stdin [--dest <path>] [--filename <name>] [--rename <0|1>]

参数

参数名	类型	必填	说明
`--url`	string	互斥	单个文件下载地址（勿用 `\|` 拼接多个 URL；OpenAPI 会当作一个非法地址导致任务失败）
`--content`	string	互斥	直接传入文件内容（支持 `\n` 转换为换行）
`--stdin`	boolean	互斥	从标准输入读取内容
`--dest`	string	❌	云盘存储路径（以 `/` 开头和结尾）
`--filename`	string	❌	保存的文件名
`--rename`	string	❌	同名文件处理策略：0=直接替换，1=自动重命名。默认 `1`

注意

--url、--content、--stdin 三者互斥，必须且只能使用其中一个。 --url 仅支持一个下载地址，不支持文档旧版中写的「竖线连接多个 URL」；多文件请逐条执行 file save，或在脚本里循环调用。

示例

# 从 URL 下载并保存
360disk file save --url "https://example.com/data.csv" --dest /数据/ --filename report.csv

# 多个 URL 须分多次执行（勿使用 url1|url2）
360disk file save --url "https://example.com/a.pdf" --dest /下载/
360disk file save --url "https://example.com/b.pdf" --dest /下载/

# 保存文本内容
360disk file save --content "# 会议纪要\n- 议题一\n- 议题二" --dest /笔记/ --filename meeting.md

# 覆盖保存（不自动重命名）
360disk file save --url "https://example.com/data.csv" --dest /数据/ --filename report.csv --rename 0

# 从管道读取内容保存
cat report.md | 360disk file save --stdin --dest /文件夹/ --filename report.md

# Windows（cmd）将目录列表保存到云盘
dir /a /q | 360disk file save --stdin --dest /备份/ --filename filelist.docx

换行输入说明

--content 中写入的 \n 会被 CLI 自动转换为真实换行。
对于多行长文本，推荐使用 --stdin（例如 cat report.md | 360disk file save --stdin ...）。

Windows 用法

cmd：type report.md | 360disk file save --stdin --dest /文件夹/ --filename report.md
PowerShell：Get-Content report.md -Raw | 360disk file save --stdin --dest /文件夹/ --filename report.md
cmd 获取目录列表：dir /a /q | 360disk file save --stdin --dest /备份/ --filename filelist.docx

file append

追加内容到云盘已存在的文本文件。支持命令行参数或标准输入管道。

360disk file append <path> [--content <text>] [--stdin]

参数

参数名	类型	必填	说明
`path`	string	✅	云盘文件路径（必须是已存在的文件）
`--content`	string	互斥	要追加的文本内容
`--stdin`	boolean	互斥	从标准输入管道读取要追加的内容

注意

--content 和 --stdin 互斥，必须且只能使用其中一个。

示例

# 直接使用 --content 参数追加内容
360disk file append /工作/日志.txt --content "2026-03-31: 完成需求分析"

# 使用 echo 和管道追加多行内容（macOS / Linux）
echo -e "line 1\nline 2" | 360disk file append /工作/日志.txt --stdin

# 使用 cat 将本地文件内容追加到云盘（macOS / Linux）
cat local_log.md | 360disk file append /项目/开发日志.md --stdin

Windows（cmd）与 file append --stdin

cmd 没有 cat，会把 cat 当作外部命令而报错。请用系统自带的 type 读取本地文件再管道到 360disk（与 file save --stdin 的 Windows 写法一致）：

cmd：type local_log.md | 360disk file append /项目/开发日志.md --stdin
本地路径含空格：type "C:\Users\xxx\Desktop\下载包信息.txt" | 360disk file append /二百/新手文件.docx --stdin
PowerShell：Get-Content .\local_log.md -Raw | 360disk file append /项目/开发日志.md --stdin

不要在 cmd 里使用文档中的 echo -e "...\n..." | ...：cmd 的 echo 不支持 -e，会把 -e 当普通字符输出，且控制台默认多为 GBK，与 CLI 按 UTF-8 读管道时容易 中文乱码。推荐：

多行 + 中文：360disk file append /路径/文件.txt --content "第一行\n第二行"（\n 会转为真实换行）
管道：把内容存成 UTF-8 文本后 type 文件.txt | ...，或 PowerShell：Get-Content .\文件.txt -Encoding utf8 -Raw | ...
若必须用 echo：先执行 chcp 65001 再 echo，并避免使用 -e

新版本 CLI 会对管道内容尝试 GBK 回退解码，并尽量剥掉误传入的 echo -e 前缀，仍建议优先用上述写法。

file exists

检测目标目录下是否存在同名文件（按文件名和文件大小匹配），适用于上传前预检。

360disk file exists --path <path> --files <json>
360disk file exists --path <path> --stdin

参数

参数名	类型	必填	说明
`--path`	string	✅	目标目录，必须以 `/` 开头
`--files`	string(JSON)	互斥	待检测文件数组 JSON，示例：`[{"fname":"a.txt","fsize":123}]`
`--stdin`	boolean	互斥	从标准输入读取 `files` JSON

注意

--files 与 --stdin 互斥，必须且只能传一个。
JSON 中如包含空格或特殊字符，请使用引号包裹整个参数。

Windows（cmd）与引号

cmd.exe 不支持用单引号 ' 包裹参数（与 bash/zsh 不同），若把文档中的 '[{"fname":"a"}]' 原样粘贴，整段会作为非法 JSON 传入。请改用：

双引号 + 转义内部双引号：--files "[{\"fname\":\"report.pdf\",\"fsize\":2048}]"
或 --stdin：把 JSON 存成 UTF-8 文件后，在 cmd 下用 type files.json | 360disk file exists --path /目录/ --stdin（见下方示例）

不要在 cmd 里使用 echo '[{...}]' | ... --stdin：cmd.exe 的 echo 不会像 bash 那样处理单引号，单引号字符会原样进入管道，得到的是 '[{"fname":...}]' 这类 非法 JSON；且 echo 输出编码常为系统 ANSI/GBK，与 CLI 优先按 UTF-8 读 stdin 时也可能不一致。Windows 下走 --stdin 请 type / PowerShell Get-Content -Raw 读文件。

CLI 会尝试剥除外层单引号并修正字面量 \"，仍建议在 cmd 下优先使用双引号 --files 或 type 管道 --stdin。PowerShell 可用单引号整段包裹 --files JSON（一般无需 \"），stdin 仍推荐 -Encoding utf8 读文件。

示例

# 直接传 --files JSON（macOS / Linux：单引号由 shell 剥除）
360disk file exists --path /AI为我下载/20260331/ --files '[{"fname":"report.pdf","fsize":2048}]'

# Windows cmd：使用双引号并对内部 " 转义
360disk file exists --path /AI为我下载/20260331/ --files "[{\"fname\":\"report.pdf\",\"fsize\":2048}]"

# 批量检测多个文件
360disk file exists --path /AI为我下载/20260331/ --files '[{"fname":"a.txt","fsize":123},{"fname":"b.txt","fsize":456}]'

# 从 stdin 读取 JSON（macOS / Linux：shell 剥掉单引号，管道内为标准 JSON）
echo '[{"fname":"a.txt","fsize":123}]' | 360disk file exists --path /AI为我下载/20260331/ --stdin

# Windows cmd：勿用上一行；请先把 JSON 存为 UTF-8 文件（如 files.json），再：
# type files.json | 360disk file exists --path /AI为我下载/20260331/ --stdin

# Windows PowerShell（stdin，推荐 UTF-8）
# Get-Content .\files.json -Raw -Encoding utf8 | 360disk file exists --path /AI为我下载/20260331/ --stdin

file upload

上传本地文件到云盘，支持多文件上传。

360disk file upload <files> [--dest <path>]

参数

参数名	类型	必填	说明	默认值
`files`	string	✅	本地文件路径，多个用逗号分隔	—
`--dest`	string	❌	云盘目标路径	`/`

示例

# 上传单个文件
360disk file upload ./report.pdf --dest /文件夹/

# 上传多个文件
360disk file upload "./a.txt,./b.txt,./c.txt" --dest /备份/

输出示例

Text 格式（--format text）：

上传完成
上传: 2/2 文件，耗时 3.5秒
  - report.pdf
  - data.xlsx

file download

下载云盘文件到本地。

360disk file download <nid> [--dir <path>] [--no-auto]

参数

参数名	类型	必填	说明
`nid`	string	✅	文件 NID（通过 `dir ls` 或 `file search` 获取）
`--dir`	string	❌	本地下载目录（默认 `~/.mcp-downloads`）
`--no-auto`	boolean	❌	仅获取下载链接，不自动下载

示例

# 下载到指定目录
360disk file download abc123 --dir ~/Downloads

# 下载到当前目录
360disk file download abc123 --dir ./

# 仅获取下载链接
360disk file download abc123 --no-auto

目录备份 (claw-backup)

将本地目录下的所有文件递归上传到云盘指定目录，目录结构按相对路径映射到远端（通过上传时的 uploadPath 逐文件指定父目录）。需已配置 API Key。

360disk claw-backup --source-dir <本地目录> --claw-name <云盘目录> [--force]

参数

参数名	类型	必填	说明
`--source-dir`	string	✅	本地源目录（绝对/相对路径均可，会解析为绝对路径）
`--claw-name`	string	✅	云盘目标目录；未以 `/` 开头会自动补上，未以 `/` 结尾会自动补上
`--force`	boolean	❌	强制覆盖云盘同名文件

行为说明

遍历本地目录树，仅上传文件；空目录不会单独创建（若云盘侧上传接口会按需创建父路径，则以接口行为为准）。
对每个文件调用与 file upload 相同的云盘上传能力（CloudOps.upload），继承当前全局 --timeout、--retries、--env、--sub-channel 等（写在子命令前）。

示例

360disk claw-backup --source-dir ~/.cc-switch --claw-name /cc-switch-backup/ --force

输出示例（JSON）

{
  "success": true,
  "result": {
    "source": "/Users/you/.cc-switch",
    "destination": "/cc-switch-backup/",
    "directories_created": 0,
    "files_uploaded": 12,
    "files": ["config.json", "profiles/default.json"]
  },
  "meta": { "duration_ms": 0, "command": "claw-backup" }
}

directories_created 字段当前恒为 0（占位，与实现一致）。

目录恢复 (claw-restore)

将云盘目录递归列目录并下载其中的文件到本地，保持相对路径结构。子目录会在本地先创建，文件通过节点 nid 下载（与 file download 同源能力）。

360disk claw-restore --remote <云盘目录> --target <本地目录>

参数

参数名	类型	必填	说明
`--remote`	string	✅	云盘源目录（路径会规范为以 `/` 开头和结尾）
`--target`	string	✅	本地目标目录（不存在则会递归创建）

行为说明

递归列出 --remote 下所有文件与文件夹；文件节点必须带有 nid，否则无法下载并报错。
下载完成后若临时文件路径与目标路径不一致，会自动 rename 到目标相对路径。

示例

360disk claw-restore --remote /cc-switch-backup/ --target ~/.cc-switch-restored

输出示例（JSON）

{
  "success": true,
  "result": {
    "remote": "/cc-switch-backup/",
    "target": "/Users/you/.cc-switch-restored",
    "directories_restored": 3,
    "files_restored": 12,
    "files": ["config.json", "profiles/default.json"]
  },
  "meta": { "duration_ms": 0, "command": "claw-restore" }
}

自动备份 (claw-auto-backup)

使用 chokidar 监听本地目录变化，在事件触发后防抖约 5 秒，再对对应目录执行一次 claw-backup（子进程调用当前 CLI 入口）。状态持久化在 ~/.360disk/claw-auto-backup.json（若 package.json 中 cli.name 非默认，目录名为 ~/.<cli.name>/）。

常驻进程

enable 会启动独立后台 Node 进程（claw-auto-backup __watch，对用户隐藏）。停用请使用 claw-auto-backup disable，或自行结束对应 PID。关闭终端不会自动停止 watcher（进程已 detached）。

claw-auto-backup enable

启用监听并启动后台 watcher。

360disk claw-auto-backup enable --source-dir <path> --claw-name <云盘路径> [--source-dir <path> --claw-name <云盘路径> ...]

参数

参数名	类型	必填	说明
`--source-dir`	string	✅（可重复）	本地监听目录，与 `--claw-name` 成对出现，且对数必须一致
`--claw-name`	string	✅（可重复）	与上一组 `--source-dir` 一一对应的云盘目录（自动补全首尾 `/`）

约束

多个 --source-dir 不能互相嵌套（父子目录关系会报错）。
--source-dir / --claw-name 各自不能重复。
需已配置 API Key（auth login 或 API_KEY / --api-key）。

监听事件包括：add、addDir、change、unlink、unlinkDir。

示例

# 单对目录
360disk claw-auto-backup enable --source-dir ~/.cc-switch --claw-name /cc-switch-backup/

# 多对目录（重复传入 --source-dir / --claw-name）
360disk claw-auto-backup enable --source-dir ~/项目A --claw-name /backup/A/ --source-dir ~/项目B --claw-name /backup/B/

后台进程会继承启用时的全局选项（如 --env、--sub-channel、--timeout、--retries），API Key 通过子进程环境变量 API_KEY 传递（若启用时使用了 --api-key）。

claw-auto-backup disable

向已记录 PID 的 watcher 发送 SIGTERM，并清理状态中的 pid / instance_id。

360disk claw-auto-backup disable

claw-auto-backup status

查看持久化状态与 watcher 是否仍在运行（通过进程命令行匹配 claw-auto-backup __watch 与 instance_id）。

360disk claw-auto-backup status

JSON 结果中 running 为 true 表示进程存活且匹配；enabled 在 JSON 中会按「逻辑启用且 running」收敛显示（详见实现：enabled && isMatchingWatcherProcess）。

Text 格式会输出 enabled、running、pid、最近备份时间、各对 source-dir -> claw-name 等。

Shell 补全 (completion)

为 bash / zsh 安装命令行自动补全脚本。

completion install

自动检测当前 shell 类型并安装补全脚本。

360disk completion install [--bash] [--zsh]

参数

参数名	类型	必填	说明
`--bash`	boolean	❌	强制安装 bash 补全
`--zsh`	boolean	❌	强制安装 zsh 补全

安装位置

补全脚本：~/.360disk/completion.{bash,zsh}
自动在 ~/.bashrc 或 ~/.zshrc 中添加 source 行

安装后需重载 shell 配置：

source ~/.zshrc    # zsh
source ~/.bashrc   # bash

补全覆盖范围：

顶级命令：auth / user / dir / file / claw-backup / claw-restore / claw-auto-backup / completion / help
子命令：如 360disk file → mv / trans-copy / rename / rm / search / share / url / node-info / origin-size / clear-dir / config / save / append / exists / upload / download；360disk claw-auto-backup → enable / disable / status
选项参数：--page、--size、--format、--type 等
zsh 补全附带中文描述

completion uninstall

卸载补全脚本并清理 shell 配置。

360disk completion uninstall [--bash] [--zsh]

completion script

输出补全脚本到 stdout，适合手动安装或临时使用。

360disk completion script [--bash] [--zsh]

示例

# 临时加载补全
eval "$(360disk completion script)"

# 输出 zsh 补全脚本
360disk completion script --zsh

路径格式规范

类型	格式要求	正确示例	错误示例
文件路径	以 `/` 开头	`/文件夹/报告.pdf`	`文档/报告.pdf`
文件夹路径	以 `/` 开头和结尾	`/文件夹/项目/`	`/文件夹/项目`
`file mv` 的目录源路径（`src`）	末尾 `/` 可省略（单目录场景）	`/文件夹/项目` 或 `/文件夹/项目/`	`文件夹/项目`（未以 `/` 开头）
多个文件	用 `\|` 分隔，整体加引号	`"/文件1.txt\|/文件2.txt"`	`/文件1.txt\|/文件2.txt`（未加引号）
多个本地文件（upload）	用 `,` 分隔	`./a.txt,./b.txt`	`./a.txt\|./b.txt`

Windows 速查

在 Windows 下，cmd.exe 与 bash 差异较大（无 cat、单引号不作字符串定界、file exists 的 JSON 与 stdin 管道规则不同——cmd 下不要用 echo '[...]' | ... --stdin，会得到非法 JSON）。建议优先使用下列写法：

本地文件 → 云盘（file save --stdin）
- cmd：type report.md | 360disk file save --stdin --dest /文件夹/ --filename report.md
- PowerShell：Get-Content report.md -Raw | 360disk file save --stdin --dest /文件夹/ --filename report.md
本地内容追加到云盘已有文件（file append --stdin，勿用 cat）
- cmd：type local_log.md | 360disk file append /项目/开发日志.md --stdin
- PowerShell：Get-Content .\local_log.md -Raw | 360disk file append /项目/开发日志.md --stdin
本地配置 → 云盘（file config 的 config:write + --stdin）
- cmd：type local-config.json | 360disk file config --path /mcp/app.json --command config:write --type json --stdin
- PowerShell：Get-Content .\local-config.json -Raw | 360disk file config --path /mcp/app.json --command config:write --type json --stdin
file exists --files / --stdin（cmd 勿用单引号包 --files JSON；勿用 echo '...' | 走 stdin）
- cmd：360disk file exists --path /目录/ --files "[{\"fname\":\"a.txt\",\"fsize\":123}]"
- PowerShell：360disk file exists --path /目录/ --files '[{"fname":"a.txt","fsize":123}]'
- 长 JSON 或 --stdin：把 UTF-8 JSON 存成 files.json 后 type files.json | 360disk file exists --path /目录/ --stdin；PowerShell：Get-Content .\files.json -Raw -Encoding utf8 | ...（不要照搬文档里 bash 的 echo '[...]' | ...）
批量删除路径列表（file rm --batch）
- cmd：type paths.txt | 360disk file rm /占位路径/ --batch
- PowerShell：见上文 file rm 小节的 Windows 说明。

更细的说明与容错行为见各命令章节：file save、file append、file config、file exists。

下一步

进阶用法 - 管道集成、错误码、CI/CD 场景、目录备份补充说明
安装配置 - 安装方式和鉴权配置

鉴权管理 (auth)​

auth login​

参数​

示例​

输出示例​

auth login-wechat​

参数​

输出行为​

示例​

成功时 result 常见字段​

常见错误码​

auth whoami​

参数​

输出示例​

auth logout​

参数​

用户信息 (user)​

user info​

参数​

输出示例​

目录操作 (dir)​

dir ls​

参数​

示例​

输出示例​

dir mkdir​

参数​

示例​

文件操作 (file)​

file mv​

参数​

示例​

file trans-copy​

参数​

示例​

file rename​

参数​

示例​

file rm​

参数​

示例​

批量模式输出​

file search​

参数​

示例​

输出示例​

file share​

参数​

示例​

file url​

参数​

示例​

file node-info​

参数​

示例​

file origin-size​

参数​

示例​

file clear-dir​

参数​

示例​

file config​

参数​

示例​

file save​

参数​

示例​

file append​

参数​

示例​

file exists​

参数​

示例​

file upload​

参数​

示例​

输出示例​

file download​

参数​

示例​

鉴权管理 (auth)

auth login

参数

示例

输出示例

auth login-wechat

参数

输出行为

示例

成功时 result 常见字段

常见错误码

auth whoami

参数

输出示例

auth logout

参数

用户信息 (user)

user info

参数

输出示例

目录操作 (dir)

dir ls

参数

示例

输出示例

dir mkdir

参数

示例

文件操作 (file)

file mv

参数

示例

file trans-copy

参数

示例

file rename

参数

示例

file rm

参数

示例

批量模式输出

file search

参数

示例

输出示例

file share

参数

示例

file url

参数

示例

file node-info

参数

示例

file origin-size

参数

示例

file clear-dir

参数

示例

file config

参数

示例

file save

参数

示例

file append

参数

示例

file exists

参数

示例

file upload

参数

示例

输出示例

file download

参数

示例