OpenList CLI

OpenList 命令行工具，用于管理文件、分享、用户及后台配置。

安装

bash

# npm
npm install -g @tnnevol/openlist-cli

# pnpm
pnpm add -g @tnnevol/openlist-cli

# 直接运行（无需安装）
npx @tnnevol/openlist-cli <command>

如果国外镜像源下载较慢或安装异常，可切换为 npm 淘宝源重试：

bash

npm i -g @tnnevol/openlist-cli@latest --registry=https://registry.npmmirror.com/

安装后检查版本：

bash

openlist-cli --version

也可免安装运行：npx -y @tnnevol/openlist-cli <command>。

快速开始

bash

# 1. 登录（使用 Token，在 Web 界面获取）
openlist-cli auth login --base-url http://localhost:5244 --token your-token

# 2. 列出根目录
openlist-cli fs list /

# 3. 上传文件
openlist-cli fs put ./local-file.txt /remote-dir/

# 4. 创建分享
openlist-cli share create --path /share-dir

配置

配置优先级：CLI 选项 > 环境变量 > 配置文件

配置文件

路径：~/.openlist/config.json

json

{
  "baseUrl": "http://localhost:5244",
  "token": "your-api-token"
}

使用 openlist-cli auth login 自动生成，无需手动创建。

环境变量

变量	说明
`OPENLIST_BASE_URL`	OpenList 服务地址
`OPENLIST_TOKEN`	API Token

全局选项

所有命令均支持以下全局选项：

选项	说明
`--base-url <url>`	OpenList 服务地址
`--token <token>`	API Token
`--pretty`	美化 JSON 输出

分页：列表命令（fs list / fs search / share list / admin user|storage|meta list）默认 --page 1、--per-page 30；输出在 data 同级附带 pagination（page / perPage / total / totalPages，其中 totalPages = ⌈total / perPage⌉）。

命令

auth - 账号管理

命令	说明	示例
`auth login`	登录并保存配置	`openlist-cli auth login --base-url http://... --token xxx`
`auth logout`	退出登录并清除本地配置	`openlist-cli auth logout`
`auth status`	查看当前登录状态	`openlist-cli auth status`

auth login 选项：

选项	说明
`--base-url <url>`	服务地址
`--token <token>`	API Token

fs - 文件管理

命令	说明
`fs list <path>`	列出目录内容
`fs get <path>`	获取文件或目录信息
`fs search`	搜索文件和目录
`fs dirs <path>`	获取目录树
`fs mkdir <path>`	创建目录
`fs rename <path> <name>`	重命名文件或目录
`fs move`	移动文件或目录
`fs copy`	复制文件或目录
`fs remove`	删除文件或目录
`fs put <local> <remote>`	上传文件（流式）
`fs form <local> <remote>`	上传文件（表单模式）
`fs batch-rename`	批量重命名
`fs regex-rename`	正则批量重命名
`fs recursive-move`	递归移动
`fs remove-empty-dirs <path>`	删除空目录
`fs archive-decompress`	解压压缩包
`fs archive-meta <path>`	获取压缩包元信息
`fs archive-list`	列出压缩包内容

bash

# 列出目录（分页）
openlist-cli fs list / --page 1 --per-page 50

# 搜索文件
openlist-cli fs search -k report -p /documents

# 复制文件
openlist-cli fs copy --src-dir /docs --dst-dir /backup --names a.txt,b.txt

# 移动文件
openlist-cli fs move --src-dir /docs --dst-dir /archive --names old.txt

# 删除文件
openlist-cli fs remove --dir /docs --names old.txt,temp.txt

# 上传文件
openlist-cli fs put ./report.pdf /documents/

# 正则重命名
openlist-cli fs regex-rename --src-dir /photos --src-name-regex "IMG_(\d+)" --new-name-regex "Photo_$1"

# 批量重命名
openlist-cli fs batch-rename --src-dir /docs --rename-objects '[{"src_name":"a.txt","new_name":"b.txt"}]'

命令	说明
`share list`	列出所有分享
`share get <id>`	获取分享详情
`share create`	创建文件分享（`--path` 支持逗号分隔多个）
`share update <id>`	更新分享（需 `--path` 指定文件）
`share delete <id>`	删除分享
`share enable <id>`	启用分享
`share disable <id>`	禁用分享

bash

# 创建带密码的分享
openlist-cli share create --path /shared --password secret

# 创建带过期时间的分享（RFC3339）
openlist-cli share create --path /shared --expires 2027-01-01T00:00:00Z

# 更新分享（需重新指定 --path）
openlist-cli share update <id> --path /shared --password newpass

# 分页列出分享
openlist-cli share list --page 1 --per-page 50

me - 用户信息

命令	说明
`me get`	获取当前用户信息

admin - 后台管理

按资源分组：admin <资源> <操作>。

资源	操作
`admin user`	`list` / `get <id>` / `create` / `update <id>` / `delete <id>`
`admin storage`	`list` / `get <id>` / `create` / `update <id>` / `delete <id>` / `enable <id>` / `disable <id>` / `load-all`
`admin meta`	`list` / `get <id>` / `create` / `update <id>` / `delete <id>`
`admin setting`	`list` / `get <key>` / `save` / `delete <key>` / `reset-token`
`admin driver`	`list` / `names` / `info <name>`
`admin index`	`build` / `stop` / `clear` / `progress` / `update`

说明：get/delete 等按 ?id= 查询；setting 的 get/delete 按 key；create/update/save 使用 --file <path> 或 --data <json> 传入 JSON 体。

bash

# 列出用户
openlist-cli admin user list

# 按 key 获取设置
openlist-cli admin setting get version

# 创建存储（从 JSON 文件）
openlist-cli admin storage create --file ./storage-config.json

# 启用/禁用存储
openlist-cli admin storage enable 1
openlist-cli admin storage disable 1

# 构建搜索索引
openlist-cli admin index build

首次安装引导

本引导用于帮助 AI Agent 或用户完成 OpenList CLI 的首次安装、认证和基础验证。完成后，AI Agent 可通过 openlist-cli 管理文件与目录、创建分享、查看用户信息以及进行后台管理（用户/存储/元信息/设置/驱动/索引）。

前置要求

已安装 Node.js（≥ 20.0.0）和 npm/npx。
已拥有可访问的 OpenList 服务地址（Base URL）与一个 API Token。
如需后台管理操作，请确保该 Token 对应账号具备相应权限。

Step 1: 安装或升级 CLI

bash

npm install -g @tnnevol/openlist-cli

安装后检查版本：

bash

openlist-cli --version

Step 2: 获取 API Token

在 OpenList Web 管理界面中获取 Token：

登录 OpenList 管理后台。
打开「管理 → 设置」。
进入「其他」，找到「令牌 / Token」。
复制令牌（或使用永久令牌）。

安全要求：不要把 Token 写入普通日志、聊天记录或仓库文件。

Step 3: 登录 CLI

bash

openlist-cli auth login --base-url <BASE_URL> --token <TOKEN>

登录信息保存到 ~/.openlist/config.json。例如：

bash

openlist-cli auth login --base-url http://localhost:5244 --token <TOKEN>

Step 4: 记录默认服务配置（推荐）

auth login 已将 baseUrl 与 token 持久化到 ~/.openlist/config.json，后续命令会自动读取。

若在项目工作区中供 AI Agent 使用，也可用环境变量（优先级：CLI 选项 > 环境变量 > 配置文件）：

bash

export OPENLIST_BASE_URL="http://localhost:5244"
export OPENLIST_TOKEN="<TOKEN>"

或写入工作区 .env（供 dotenv 加载）：

dotenv

OPENLIST_BASE_URL=http://localhost:5244
OPENLIST_TOKEN=<TOKEN>

建议确保 .gitignore 忽略含密钥的文件，避免提交泄露：

gitignore

.env
*.private.*

Step 5: 验证安装和登录状态

查看可用命令：

bash

openlist-cli --help

查看当前登录身份（相当于 whoami）：

bash

openlist-cli me get

进一步验证资源查询命令，例如列出根目录：

bash

openlist-cli fs list /

或查看登录状态：

bash

openlist-cli auth status

Step 6: 安装 AI Agent Skill（!强制必需）

安装 OpenList AI Agent Skill，让 AI Agent 知道如何正确使用 openlist-cli：

通用方式（skills CLI）

bash

npx -y skills add tnnevol/skills --skill=openlist

该命令会进入交互流程，可按需选择目标 AI Agent 和安装范围。全局安装可加 -g。

Hermes Agent

bash

# 1. 添加 tap（GitHub 仓库）
hermes skills tap add tnnevol/skills
# 2. 查看已配置的 taps
hermes skills tap list
# 3. 从 tap 安装具体 skill
hermes skills install tnnevol/skills/openlist

如果当前环境无法访问安装源，请按所用 AI Agent 的规则手动安装：将本仓库 skills/openlist/（含 SKILL.md 与 references/）复制到 AI Agent 的技能目录。

开发

环境要求

Node.js >= 20.0.0
pnpm（通过 Corepack 管理）

构建

项目位于 monorepo 中，从根目录执行：

bash

# 交互式选择应用后开发
pnpm dev

# 交互式选择应用后构建
pnpm build

# 清理构建产物
pnpm clean

或直接在 openlist-cli 目录下：

bash

pnpm --filter @tnnevol/openlist-cli build

技术栈

TypeScript + ESM
Commander.js - 命令解析
undici - HTTP 客户端
tsup - 构建工具

常见问题

现象	处理
`openlist-cli: command not found`	重新执行全局安装，并确认 npm global bin 在 PATH 中；或改用 `npx -y @tnnevol/openlist-cli`
提示服务地址未配置 / Token 未配置	重新执行 `openlist-cli auth login --base-url <url> --token <token>`，或设置环境变量
认证失败 / 401	确认 Token 有效、`--base-url` 正确、账号具备相应权限
命令参数不确定	执行 `openlist-cli <group> <command> --help` 查看最新用法
Node 版本过低	升级到 Node.js ≥ 20

License

MIT

OpenList CLI ​

安装 ​

快速开始 ​

配置 ​

配置文件 ​

环境变量 ​

全局选项 ​

命令 ​

auth - 账号管理 ​

fs - 文件管理 ​

share - 分享管理 ​

me - 用户信息 ​

admin - 后台管理 ​

首次安装引导 ​

前置要求 ​

Step 1: 安装或升级 CLI ​

Step 2: 获取 API Token ​

Step 3: 登录 CLI ​

Step 4: 记录默认服务配置（推荐） ​

Step 5: 验证安装和登录状态 ​

Step 6: 安装 AI Agent Skill（!强制必需） ​

通用方式（skills CLI） ​

Hermes Agent ​

开发 ​

环境要求 ​

构建 ​

技术栈 ​

常见问题 ​

License ​

OpenList CLI

安装

快速开始

配置

配置文件

环境变量

全局选项

命令

auth - 账号管理

fs - 文件管理

share - 分享管理

me - 用户信息

admin - 后台管理

首次安装引导

前置要求

Step 1: 安装或升级 CLI

Step 2: 获取 API Token

Step 3: 登录 CLI

Step 4: 记录默认服务配置（推荐）

Step 5: 验证安装和登录状态

Step 6: 安装 AI Agent Skill（!强制必需）

通用方式（skills CLI）

Hermes Agent

开发

环境要求

构建

技术栈

常见问题

License