Fast.io

fastio

适用于 Fastio 云存储平台的命令行界面。使用 Rust 构建，速度快、可靠且支持跨平台。

安装

npm（推荐）

npm install -g @vividengine/fastio-cli

也可以直接运行，无需安装：

npx @vividengine/fastio-cli --help

Shell 脚本

curl -fsSL https://raw.githubusercontent.com/VEngTech/fastio_cli/main/install.sh | sh

下载二进制文件

macOS、Linux 和 Windows 的预构建二进制文件可在 Releases 页面获取。

从源代码构建

需要 Rust 1.88+（edition 2024）：

cargo install --path .

快速开始

# Log in (opens browser for secure authentication)
fastio auth login

# Check auth status
fastio auth status

# List organizations
fastio org list

# Create a workspace
fastio workspace create --org <org_id> "My Workspace"

# Upload a file
fastio upload file --workspace <workspace_id> ./document.pdf

# Download a file
fastio download file --workspace <workspace_id> <node_id> --output ./downloads/

# Ask the AI about your workspace
fastio ai chat --workspace <workspace_id> "What files do I have?"

# Log out
fastio auth logout

身份验证

CLI 支持多种身份验证方式，按以下顺序检查：

1. --token 标志（一次性 bearer token）
2. FASTIO_TOKEN 环境变量
3. FASTIO_API_KEY 环境变量
4. --profile 中存储的凭据（或默认配置文件）

浏览器登录（推荐）

fastio auth login

# Request an admin (`rwa`) access mode, or a read-only one
fastio auth login --admin
fastio auth login --read-only

# Also request permission to change account settings (`userdetails:*:rw`)
fastio auth login --account-settings

auth login 会在浏览器中打开 Fastio 的登录页面（如果你的账户启用了 2FA，也会包含 2FA 步骤）， 并通过一个短期本地回调接收结果。令牌会存储在本地并自动刷新。

--admin 和 --read-only 请求的是权限上限，而非角色：授权页面授予的权限可能低于请求值。随后运行 fastio auth scopes，查看凭据当前实际可执行的操作；fastio auth status 仅显示配置文件登录时缓存的权限范围。

这台机器上没有浏览器？使用 --no-browser：

fastio auth login --no-browser

此选项会打印登录 URL，而不是打开浏览器。在任意设备上打开该 URL 并登录，然后将显示的代码粘贴回 CLI 提示中。

CLI 密码登录已移除——此操作由上述浏览器登录页面处理。若用于无人值守或 CI，请改为创建 API 密钥（见下文）。

API 密钥

# Create an API key
fastio auth api-key create --name "CI pipeline"

# Create one scoped to a single organization, with admin access
fastio auth api-key create --name "release bot" --org 1234567890123456789 --admin

# Use it for subsequent commands
export FASTIO_API_KEY=your-key-here
fastio org list

权限范围采用 entity_type:entity_id:access_mode 字符串，其中访问模式为 r、rw 或 rwa（管理员）。--org / --workspace / --share（可重复使用）和 --all 用于选择实体，--admin / --read-only 用于设置访问模式，而 --account-settings 会为密码、电子邮件和 2FA 注册变更添加 userdetails:*:rw——仅有 rwa 并不会授予这些权限。api-key update 会替换密钥的整个权限范围，因此请先运行 fastio auth api-key get <key-id>，然后重新指定要保留的所有权限范围。如果这些权限范围的访问模式不完全相同，请使用原始 --scopes '[...]' 格式重新指定：--admin 和 --read-only 会应用于请求中的每个实体，因此都无法表示混合权限。笼统使用 --admin 会把只读权限范围也提升为管理员权限，而不只是提升你指定的那项；笼统使用 --read-only 会把可写或管理员权限范围也降级，而不只是缩小你指定的那项。fastio auth oauth narrow <session-id> 会放弃登录会话的权限，并在下次令牌刷新时生效。

服务账户密钥

对于不应以个人身份执行操作的自动化任务，工作区管理员或所有者可以创建一个服务账户——即在一个工作区中具有 viewer 或 editor 角色的非人类成员——并将其密钥提供给任务：

# As the admin: create the account and its first key (the secret is printed once)
fastio service-account create --workspace 1234567890123456789 --name ci-bot --role editor

# In the job: use the secret like any API key
export FASTIO_API_KEY=fio_sa_...
fastio auth status

服务账户密钥仅限其所属的一个工作区使用。

角色：viewer（读取、下载、搜索、AI 聊天）或 editor（除 viewer 权限外，还可上传、编辑、移动、重命名、移至回收站、管理元数据和评论）。

管理和共享操作（成员、邀请、创建共享、File Shares、签名、导入、组织变更、永久删除文件或清空回收站、密钥/账户管理）会返回 HTTP 403，原因是 service_account_not_permitted。身份信息读取（auth status、auth check、workspace list）可正常使用，公开共享链接的行为则与匿名请求相同。

密钥无法再次取回；如果丢失，请使用 fastio sa key create 创建新密钥，并使用 fastio sa key revoke 撤销旧密钥。

双重身份验证

# Check 2FA status
fastio auth 2fa status

# Enable 2FA
fastio auth 2fa setup --channel totp

# Verify a pending 2FA code
fastio auth 2fa verify --code <CODE>

auth login 期间的 2FA 在浏览器登录页面处理，不在 CLI 中处理——这些命令用于管理 2FA 设置（注册、状态、禁用）。

输出格式

所有命令都支持使用 --format 控制输出：

# Table format (default for terminals)
fastio org list

# Markdown format (default when piped; optimized for LLM consumers)
fastio org list | cat

# JSON format (for scripts that parse structured output)
fastio org list --format json

# CSV format
fastio org list --format csv

# Explicit markdown (GitHub-flavored, byte-equivalent to the server's ?output=markdown)
fastio org list --format markdown
# `--format md` is accepted as an alias

# Filter specific fields
fastio org list --fields name,id,description

自 2026-04-15 起，非 TTY 场景下的默认格式由 JSON 改为 Markdown。渲染后的输出与 Fastio API 对 ?output=markdown 生成的内容字节等价：包含 **Result:** success|failure 前置内容；将对象类型的错误提升为开头的 # Error 小节；并按插入顺序将其余顶层键分别作为 H1 小节。关联记录数组会渲染为 GFM 管道表格（按插入顺序合并键）；标量列表会渲染为项目符号列表。

关于转义的说明：项目符号值和标题文本不会转义——渲染器采取轻量处理方式，以匹配服务端契约，因为输出旨在供人阅读或渲染，而非嵌入其他 Markdown 中。**将输出渲染为 HTML 的下游使用者必须进行清理。**作为 Trojan-Source 防护措施，渲染器会去除 Unicode 双向、零宽和 C0/C1 控制字符；表格单元格会转义 |、\、` 和换行符；类似 HTML 的单元格内容会用行内代码围栏括起。

需要机器可解析输出的管道可以通过 --format json 切换回 JSON。

命令

身份验证与用户

组	说明
auth	登录、登出、2FA、API 密钥、OAuth 会话
user	用户资料、搜索、资产、邀请
configure	CLI 配置档和设置

组织与工作区

组	说明
org	组织 CRUD、账单、成员、转移令牌、发现、资产
workspace	工作区 CRUD、搜索、限制、jobs-status（轮询异步任务）
member	工作区／共享成员管理
service-account	工作区服务账户——使用 API 密钥的非人类成员（别名 sa）：列出、创建、查看信息、更新、停用、启用、删除，以及 key list/create/revoke。仅限管理员／所有者；密钥只显示一次
invitation	列出、接受、拒绝、删除邀请；join 根据邀请的电子邮件键接受或拒绝邀请
dashboard	每个工作区的仪表板卡片流：获取、隐藏、取消隐藏

文件与存储

组	说明
search	统一搜索——在工作区或共享中执行一次查询，结果按 files / metadata / comments 分类。查找任何内容时从这里开始
files	列出、创建文件夹、移动、复制、重命名、删除、移至回收站、版本、搜索（扁平文件列表，使用 --workspace 或 --share）、content（文件提取文本，按可寻址块返回——可用相关性选项 --query、--page、--chunk-from/--chunk-to，或用 --nodes 一次为最多 10 个文件评分）、锁定
upload	文件上传（分块并显示进度）、文本上传、URL 导入、会话管理
download	文件下载（流式传输并显示进度）、文件夹 ZIP、批量下载
lock	获取、检查状态、发送心跳、释放文件锁
metadata	元数据提取与搜索：eligible、details、search，以及单文件异步 extract（会消耗 AI 积分——需要 --confirm-ai-spend；--wait 会轮询至终态）

共享与协作

组	说明
share	共享 CRUD、文件、成员、密码验证
fileshare	文件共享——持久的单文件链接共享（替代已停用的 QuickShare）：创建／列出／查看信息／更新／删除、授权、下载／版本／预览、上传回写、活动、ws-token
comment	评论、回复、反应、附件
event	活动事件、搜索、轮询、组织范围的存储变更流（event changes）
preview	文件预览 URL 和转换
asset	组织／工作区／用户资产管理

AI

组	说明
ripley	Fastio 委派的 AI Agent——提问、聊天、历史记录、消息管理、summary、transactions（ai 是隐藏别名）。--effort normal|high 可选择每条消息的回复力度。搜索不是 Ripley 的动词——请使用 search

平台

分组	描述
apps	应用列表、详情和启动
import	云导入提供方、身份、来源、任务、回写
intents	Agent 意图——宣布你正在做什么，让其他参与者在发生冲突前看到：allocate、list、fill、get、release
mcp	启动内置 MCP 服务，供 AI Agent 使用
completions	生成 Shell 补全（bash、zsh、fish、PowerShell）

实用工具

分组	描述
how-to	关于 Fastio 本身的有据可依的“如何……”解答（别名 howto）
id	离线检查 Fastio 标识符（无需认证或网络）：识别 ID 的实体类型和类别
view	在终端中渲染单个笔记或 .md 文件节点
skill	输出内置 Agent 技能指南
system	API 健康检查：ping、status（无需认证）

MCP 服务模式

CLI 内置了用于 AI Agent 集成的 Model Context Protocol 服务。将其作为子进程运行：

fastio mcp

这会通过标准输入输出将 CLI 的操作路由工具接口公开为 MCP 工具，兼容 Claude Desktop、VS Code 和其他兼容 MCP 的客户端。少数高风险或涉及本地字节数据的操作（签署发送／作废、文件共享上传回写和 ws-token，以及会生成密钥的服务账号管理）仍只能通过 CLI 使用。

默认情况下，工具响应会渲染为 GitHub 风格的 Markdown， 与 Fastio API 的 ?output=markdown 输出逐字节等效。 对于大模型而言，Markdown 比 美化排版的 JSON 更节省 Token，因此 MCP 服务对所有读取和 状态响应都使用 Markdown。

{
  "mcpServers": {
    "fastio": {
      "command": "fastio",
      "args": ["mcp"]
    }
  }
}

筛选可用工具：

fastio mcp --tools auth,org,workspace,files,upload,download

认证和后端遵循标准 CLI 规则：服务会遵循全局 --api-base、--token 和 --profile 标志（以及 FASTIO_TOKEN / FASTIO_API_KEY 环境变量），因此你可以将其指向非默认后端或 配置文件，例如：fastio --profile staging mcp 或 fastio --api-base https://api.example/current mcp。

Shell 补全

为你的 Shell 生成补全：

# Bash
fastio completions bash > ~/.bash_completion.d/fastio

# Zsh
fastio completions zsh > ~/.zfunc/_fastio

# Fish
fastio completions fish > ~/.config/fish/completions/fastio.fish

# PowerShell
fastio completions powershell > _fastio.ps1

配置文件

使用命名配置文件管理多个账号：

# Set up a profile interactively
fastio configure init

# Log in to a specific profile
fastio auth login --profile work

# Use a profile for a command
fastio org list --profile work

# Set default profile
fastio configure set-default work

# List all profiles
fastio configure list

全局选项

标志	描述
--format json|table|csv|markdown	输出格式（通过管道输出时，默认使用 markdown）
--fields name,id,...	筛选输出字段
--detail terse|standard|full	通过 ?output=<detail> 设置服务端响应详细程度；省略时，服务端返回 full 结构
--no-color	禁用彩色输出
--quiet / -q	禁止所有输出
--verbose / -v	提高详细程度；可重复使用（-v 为 info，-vv 为 debug，-vvv 跟踪 API 调用）
--profile <name>	使用命名配置文件
--token <jwt>	一次性 Bearer Token
--api-base <url>	覆盖 API 基础 URL
--version / -V	输出版本（仅限根命令，例如 fastio --version）

配置

配置文件存储在平台配置目录下的 fastio-cli 文件夹中：Linux 上为 $XDG_CONFIG_HOME/fastio-cli（通常是 ~/.config/fastio-cli），macOS 上为 ~/Library/Application Support/fastio-cli，Windows 上为 %APPDATA%\fastio-cli：

文件	用途
config.json	配置文件设置和 API 基础 URL
credentials.json	存储的认证 Token

许可证

Apache License 2.0。详情请参阅 LICENSE。