flowus-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FlowUs CLI

Use the FlowUs CLI (

flowus

) for FlowUs V2 API work: pages, blocks, databases, search, Markdown content, and files.

The CLI source repository may be private. Do not ask the user to clone source code before using the CLI. Install or update the released binary from the FlowUs CDN when the command is missing or outdated.

Do not assume old FlowUs skill names such as

flowus-auth

flowus-page

, or

flowus:flowus-login

使用FlowUs CLI（

flowus

）完成FlowUs V2 API相关工作：页面、区块、数据库、搜索、Markdown内容及文件操作。

CLI的源代码仓库可能为私有。请勿要求用户在使用CLI前克隆源代码。当命令缺失或版本过时，请从FlowUs CDN安装或更新已发布的二进制文件。

请勿沿用旧的FlowUs技能名称，如

flowus-auth

、

flowus-page

或

flowus:flowus-login

。

Mandatory preflight

强制预检步骤

When this skill is selected for any FlowUs task, complete this preflight before API work, searches, reads, writes, counts, uploads, or endpoint-specific planning:

Ensure the released CLI binary is installed:

bash

command -v flowus >/dev/null 2>&1 || curl -fsSL https://cdn2.flowus.cn/flowus-cli/install | bash
flowus version

Verify authentication and active identity:

bash

flowus --json doctor
flowus --json whoami

Continue only when the checks show authenticated FlowUs credentials. If authentication is missing or invalid, do not immediately tell the user to run a login command. Choose and start the authentication path yourself:

If
```
FLOWUS_TOKEN
```
is already set, rerun
```
flowus --json doctor
```
and
```
flowus --json whoami
```
; do not ask for another login.
If the session is a local GUI or browser-capable environment, run
```
flowus login --browser
```
yourself, let the user finish the browser approval, then rerun
```
flowus --json doctor
```
and
```
flowus --json whoami
```
. Treat local macOS/Windows/Linux desktop sessions, shells with
```
DISPLAY
```
or
```
WAYLAND_DISPLAY
```
, or environments with a working system browser opener as browser-capable unless SSH, CI, container, or headless environment variables clearly say otherwise. If unsure, try browser login first and fall back only after it fails or times out.
If the session is SSH, CI, headless, or browser login times out, run
```
flowus --json login --manual
```
yourself and summarize its setup instructions. Manual setup produces a token workflow; it does not authenticate the CLI by itself. Stop until
```
FLOWUS_TOKEN
```
or saved credentials are available.

Do not run plain

flowus login

in agent sessions because it can block on an interactive method prompt. Do not make API calls or draw conclusions from incomplete data until authentication is verified.

Use this browser login command when the environment supports it:

bash

flowus login --browser

Use manual setup only for headless or remote environments:

bash

flowus --json login --manual

On Windows PowerShell, install with:

powershell

irm https://cdn2.flowus.cn/flowus-cli/install.ps1 | iex
flowus version

If a command is missing or help output looks stale, run:

bash

flowus update

Useful install overrides:

```
FLOWUS_INSTALL_DIR
```
- install directory.
```
FLOWUS_VERSION
```
- exact release version, such as
```
v0.1.10
```
.
```
FLOWUS_CLI_RELEASE_BASE_URL
```
- alternate release base URL for tests.

当选择本技能执行任何FlowUs任务时，在进行API操作、搜索、读取、写入、计数、上传或特定端点规划之前，必须完成以下预检：

确保已安装已发布的CLI二进制文件：

bash

command -v flowus >/dev/null 2>&1 || curl -fsSL https://cdn2.flowus.cn/flowus-cli/install | bash
flowus version

验证身份验证状态及当前身份：

bash

flowus --json doctor
flowus --json whoami

仅当检查结果显示已通过FlowUs身份验证时，才可继续操作。如果身份验证缺失或无效，请勿直接告知用户运行登录命令，请自行选择并启动身份验证流程：

若已设置
```
FLOWUS_TOKEN
```
，重新运行
```
flowus --json doctor
```
和
```
flowus --json whoami
```
；无需要求用户再次登录。
若会话处于本地GUI或支持浏览器的环境中，自行运行
```
flowus login --browser
```
，让用户完成浏览器端的授权操作，然后重新运行
```
flowus --json doctor
```
和
```
flowus --json whoami
```
。除非SSH、CI、容器或无头环境变量明确表明不支持，否则将本地macOS/Windows/Linux桌面会话、带有
```
DISPLAY
```
或
```
WAYLAND_DISPLAY
```
的Shell，或能正常调用系统浏览器的环境视为支持浏览器的环境。若不确定，先尝试浏览器登录，仅在失败或超时后再改用其他方式。
若会话处于SSH、CI、无头环境，或浏览器登录超时，自行运行
```
flowus --json login --manual
```
并总结其设置说明。手动设置会生成一个令牌流程，但它本身不会完成CLI的身份验证。请等待
```
FLOWUS_TOKEN
```
或已保存的凭证可用后再继续。

请勿在Agent会话中运行普通的

flowus login

命令，因为它可能会在交互式方法提示处阻塞。在身份验证完成前，请勿进行API调用或根据不完整的数据得出结论。

当环境支持时，使用以下浏览器登录命令：

bash

flowus login --browser

仅在无头或远程环境中使用手动设置：

bash

flowus --json login --manual

在Windows PowerShell中，使用以下命令安装：

powershell

irm https://cdn2.flowus.cn/flowus-cli/install.ps1 | iex
flowus version

若命令缺失或帮助输出显示过时，请运行：

bash

flowus update

实用的安装覆盖参数：

```
FLOWUS_INSTALL_DIR
```
- 安装目录。
```
FLOWUS_VERSION
```
- 确切的发布版本，例如
```
v0.1.10
```
。
```
FLOWUS_CLI_RELEASE_BASE_URL
```
- 用于测试的替代发布基础URL。

First rule: ask the CLI

首要规则：查询CLI

The CLI is self-documenting. Prefer these commands over guessing syntax or request fields:

```
flowus --help
```
- list global options and top-level commands.
```
flowus help <command...>
```
- show usage, options, examples, and notes for any command or subcommand.
```
flowus api ls
```
- list public API endpoints and request field hints.
```
flowus api ls --plain
```
- compact endpoint list for scanning.
```
flowus api --docs <PATH> -X <METHOD>
```
- show agent-readable Markdown docs for one endpoint, including parameters, examples, and safety notes.
```
flowus api --spec <PATH> -X <METHOD>
```
- show the exact embedded OpenAPI fragment for one endpoint.
```
flowus --json doctor
```
- inspect local authentication and configuration state when auth or base URL selection is unclear.
```
flowus --json whoami
```
- verify the active FlowUs identity.
```
flowus markdown get <page-id>
```
- retrieve page content as Markdown.

If you are unsure about syntax, request body fields, pagination, auth source, or command coverage, run help first.

CLI自带文档说明。优先使用以下命令，而非猜测语法或请求字段：

```
flowus --help
```
- 列出全局选项和顶级命令。
```
flowus help <command...>
```
- 显示任意命令或子命令的用法、选项、示例及注意事项。
```
flowus api ls
```
- 列出公开API端点及请求字段提示。
```
flowus api ls --plain
```
- 简洁的端点列表，便于浏览。
```
flowus api --docs <PATH> -X <METHOD>
```
- 显示Agent可读的Markdown文档，包含参数、示例及安全说明。
```
flowus api --spec <PATH> -X <METHOD>
```
- 显示单个端点的精确嵌入式OpenAPI片段。
```
flowus --json doctor
```
- 当身份验证或基础URL选择不明确时，检查本地身份验证和配置状态。
```
flowus --json whoami
```
- 验证当前活跃的FlowUs身份。
```
flowus markdown get <page-id>
```
- 以Markdown格式获取页面内容。

若对语法、请求体字段、分页、身份验证来源或命令覆盖范围不确定，请先运行帮助命令。

Authentication and configuration

身份验证与配置

Select authentication automatically; do not ask the user to choose a login method unless both browser and token setup are impossible. Credential precedence is:

```
--token <token>
```
```
FLOWUS_TOKEN
```
saved login credentials in the FlowUs credential store

Use these checks:

bash

flowus --json doctor
flowus --json whoami

If no token is available, first try

flowus login --browser

from local GUI or browser-capable sessions. Use manual setup only when browser OAuth is not possible:

bash

flowus --json login --manual

Do not ask the user to paste bearer tokens into chat. Ask them to provide credentials through

FLOWUS_TOKEN

, saved login credentials, or an approved secret channel, then rerun

flowus --json doctor

and

flowus --json whoami

Common environment variables:

```
FLOWUS_TOKEN
```
- bearer token for API calls.
```
FLOWUS_BASE_URL
```
- API base URL; default is
```
https://api.flowus.cn
```
.
```
FLOWUS_CONFIG_DIR
```
- config directory; default follows the FlowUs profile.
```
FLOWUS_USER_AGENT
```
- custom user agent suffix.

Do not print bearer tokens, write them into files, or paste them into request bodies. Do not call the FlowUs V2 API with

curl

; use the CLI so auth, product defaults, retries, and error formatting stay consistent.

自动选择身份验证方式；除非浏览器和令牌设置均不可行，否则请勿让用户选择登录方式。凭证优先级如下：

```
--token <token>
```
```
FLOWUS_TOKEN
```
FlowUs凭证存储中保存的登录凭证

使用以下命令检查：

bash

flowus --json doctor
flowus --json whoami

若没有可用令牌，首先在本地GUI或支持浏览器的会话中尝试

flowus login --browser

。仅当浏览器OAuth不可用时，才使用手动设置：

bash

flowus --json login --manual

请勿要求用户在聊天中粘贴Bearer令牌。请让他们通过

FLOWUS_TOKEN

、已保存的登录凭证或经过批准的保密渠道提供凭证，然后重新运行

flowus --json doctor

和

flowus --json whoami

。

常见环境变量：

```
FLOWUS_TOKEN
```
- API调用使用的Bearer令牌。
```
FLOWUS_BASE_URL
```
- API基础URL；默认值为
```
https://api.flowus.cn
```
。
```
FLOWUS_CONFIG_DIR
```
- 配置目录；默认遵循FlowUs配置文件路径。
```
FLOWUS_USER_AGENT
```
- 自定义用户代理后缀。

请勿打印Bearer令牌、将其写入文件或粘贴到请求体中。请勿使用

curl

调用FlowUs V2 API；请使用CLI，以确保身份验证、产品默认设置、重试机制和错误格式保持一致。

Working rules

操作规则

Use
```
--json
```
for stable machine-readable stdout.
Keep JSON request bodies in local files and pass them with
```
--body <file>
```
.
Keep Markdown replacement content in local files and pass it with
```
--file <file>
```
.
Prefer domain commands over
```
api call
```
;
```
flowus api --docs
```
names a recommended domain command when one exists.
Before write operations, confirm IDs, file paths, URLs, and body files come from user-authorized input.
For paginated commands, inspect JSON output for cursors and repeat with the command's cursor option.
The CLI intentionally rejects DELETE API calls. Do not work around that for destructive operations unless the user explicitly asks for a different tool.

使用
```
--json
```
参数获取稳定的机器可读标准输出。
将JSON请求体保存在本地文件中，并通过
```
--body <file>
```
参数传递。
将Markdown替换内容保存在本地文件中，并通过
```
--file <file>
```
参数传递。
优先使用领域命令而非
```
api call
```
；当存在推荐的领域命令时，
```
flowus api --docs
```
会指明该命令。
在执行写入操作前，确认目标ID、文件路径、URL和请求体文件均来自用户授权的输入。
对于分页命令，检查JSON输出中的游标，并使用命令的游标选项重复执行。
CLI会主动拒绝DELETE API调用。除非用户明确要求使用其他工具，否则请勿绕过此限制执行破坏性操作。

Common workflows

常见工作流

Read a page

读取页面

bash

flowus --json page get <page_id>
flowus markdown get <page_id> > page.md

Use Markdown for page content work whenever possible. It is easier to inspect, edit, and diff than raw block JSON.

bash

flowus --json page get <page_id>
flowus markdown get <page_id> > page.md

尽可能使用Markdown格式处理页面内容。相比原始区块JSON，它更易于检查、编辑和对比差异。

Replace page Markdown

替换页面Markdown内容

bash

flowus markdown put --file page.md <page_id>

Only run this after confirming the target page ID and replacement file.

bash

flowus markdown put --file page.md <page_id>

仅在确认目标页面ID和替换文件后，才可运行此命令。

Create or update a page with JSON

使用JSON创建或更新页面

Create a local JSON body file, then pass it to the CLI:

bash

flowus --json page create --body page.json
flowus --json page update --body patch.json <page_id>

For idempotent creates, use

--idempotency-key <key>

创建本地JSON请求体文件，然后传递给CLI：

bash

flowus --json page create --body page.json
flowus --json page update --body patch.json <page_id>

对于幂等创建操作，使用

--idempotency-key <key>

参数。

Blocks and children

区块及子区块

bash

flowus --json block get <block_id>
flowus --json block children <block_id>
flowus --json block append <block_id> --body children.json
flowus --json block update <block_id> --body block-patch.json

bash

flowus --json block get <block_id>
flowus --json block children <block_id>
flowus --json block append <block_id> --body children.json
flowus --json block update <block_id> --body block-patch.json

Databases

数据库

bash

flowus --json database get <database_id>
flowus --json database query <database_id> --body query.json
flowus --json page property get <page_id> <property_id>

Use

flowus api --docs

or command help to inspect filter and sort body shapes before writing

query.json

bash

flowus --json database get <database_id>
flowus --json database query <database_id> --body query.json
flowus --json page property get <page_id> <property_id>

在编写

query.json

之前，使用

flowus api --docs

或命令帮助查看筛选和排序的请求体格式。

Search

搜索

bash

flowus --json search text "roadmap" --page-size 10
flowus --json search semantic "tasks about quarterly planning" --space-id <space_id> --page-size 10

Use text search for exact titles, keywords, and known phrases. Use semantic search when intent matters more than exact wording.

bash

flowus --json search text "roadmap" --page-size 10
flowus --json search semantic "tasks about quarterly planning" --space-id <space_id> --page-size 10

使用文本搜索查找精确标题、关键词和已知短语。当意图比精确措辞更重要时，使用语义搜索。

Files

文件

Upload a local file for a parent page:

bash

flowus --json file upload --parent-page <page_id> ./report.pdf

Append a FlowUs-hosted file block with the returned object name and size:

bash

flowus --json block append-file <block_id> --oss-name <oss_name> --size <bytes>

Append an external file URL:

bash

flowus --json block append-file <block_id> --external-url https://example.com/report.pdf

上传本地文件至父页面：

bash

flowus --json file upload --parent-page <page_id> ./report.pdf

使用返回的对象名称和大小，添加一个FlowUs托管的文件区块：

bash

flowus --json block append-file <block_id> --oss-name <oss_name> --size <bytes>

添加外部文件URL：

bash

flowus --json block append-file <block_id> --external-url https://example.com/report.pdf

Fallback API calls

备用API调用

Use

api call

only when no domain command covers the endpoint. Lookup sequence:

bash

flowus api ls --plain
flowus api --docs /v2/blocks/{block_id}/children -X PATCH
flowus api --spec /v2/blocks/{block_id}/children -X PATCH
flowus --json api call PATCH /v2/blocks/:block_id/children --param block_id=<block_id> --body body.json

--param

fills path placeholders first; remaining keys become query parameters. Use

--header NAME=VALUE

for headers such as

If-Match

仅当没有领域命令覆盖该端点时，才使用

api call

。查找顺序如下：

bash

flowus api ls --plain
flowus api --docs /v2/blocks/{block_id}/children -X PATCH
flowus api --spec /v2/blocks/{block_id}/children -X PATCH
flowus --json api call PATCH /v2/blocks/:block_id/children --param block_id=<block_id> --body body.json

--param

参数首先填充路径占位符；剩余的键将成为查询参数。使用

--header NAME=VALUE

设置

If-Match

等请求头。

Troubleshooting

故障排除

Command not found: install from

https://cdn2.flowus.cn/flowus-cli/install

Unknown command or option: run
```
flowus update
```
, then
```
flowus <command> --help
```
.
Authentication failure: run
```
flowus --json doctor
```
, check
```
FLOWUS_TOKEN
```
, then run
```
flowus login --manual
```
if needed.

Unexpected API shape: run

flowus api --docs <PATH> -X <METHOD>

and

flowus api --spec <PATH> -X <METHOD>

before retrying.

命令未找到：从

https://cdn2.flowus.cn/flowus-cli/install

安装。

未知命令或选项：运行
```
flowus update
```
，然后执行
```
flowus <command> --help
```
。
身份验证失败：运行
```
flowus --json doctor
```
，检查
```
FLOWUS_TOKEN
```
，必要时运行
```
flowus login --manual
```
。

API格式异常：在重试前运行

flowus api --docs <PATH> -X <METHOD>

和

flowus api --spec <PATH> -X <METHOD>

。