cubox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cubox-cli

Manage Cubox bookmarks via the

cubox-cli

command-line tool.

通过

cubox-cli

命令行工具管理Cubox书签。

Authentication

身份验证

If any command fails with "not logged in", run

cubox-cli auth login

and follow the interactive prompts.

如果任何命令返回“未登录”错误，请运行

cubox-cli auth login

并按照交互式提示操作。

Commands

命令

All commands output JSON by default. Add

-o pretty

for indented JSON,

-o text

for human-readable output.

所有命令默认输出JSON格式。添加

-o pretty

可获得缩进格式的JSON，添加

-o text

可获得易读的文本输出。

List Folders

列出文件夹

bash

cubox-cli folder list

Returns:

[{ "id", "nested_name", "name", "parent_id", "uncategorized" }]

bash

cubox-cli folder list

[{ "id", "nested_name", "name", "parent_id", "uncategorized" }]

List Tags

列出标签

bash

cubox-cli tag list

Returns:

[{ "id", "nested_name", "name", "parent_id" }]

bash

cubox-cli tag list

[{ "id", "nested_name", "name", "parent_id" }]

Filter / Search Cards

筛选/搜索卡片

bash

cubox-cli card list [flags]

Flags:

```
--folder ID,...
```
— filter by folder IDs
```
--tag ID,...
```
— filter by tag IDs
```
--starred
```
— starred cards only
```
--read
```
/
```
--unread
```
— filter by read status
```
--annotated
```
— cards with annotations only
```
--keyword TEXT
```
— search by keyword
```
--start-time
```
,
```
--end-time
```
— filter by time range (see Time filtering below)
```
--limit N
```
— page size (default 50)
```
--last-id CARD_ID
```
— cursor pagination (non-search mode)
```
--page N
```
— page-based pagination (search mode, 1-based)
```
--all
```
— auto-paginate all results

Pagination rules:

When
```
--keyword
```
is set (search mode): use
```
--page
```
for pagination,
```
--last-id
```
is ignored
When
```
--keyword
```
is not set (browse mode): use
```
--last-id
```
for cursor-based pagination

Returns:

[{ "id", "title", "description", "domain", "read", "starred", "tags", "folder", "url", ... }]

bash

cubox-cli card list [flags]

可选参数：

```
--folder ID,...
```
— 按文件夹ID筛选
```
--tag ID,...
```
— 按标签ID筛选
```
--starred
```
— 仅显示已收藏的卡片
```
--read
```
/
```
--unread
```
— 按阅读状态筛选
```
--annotated
```
— 仅显示带有注释的卡片
```
--keyword TEXT
```
— 按关键词搜索
```
--start-time
```
,
```
--end-time
```
— 按时间范围筛选（见下方时间过滤）
```
--limit N
```
— 每页数量（默认50）
```
--last-id CARD_ID
```
— 游标分页（非搜索模式）
```
--page N
```
— 基于页码的分页（搜索模式，从1开始）
```
--all
```
— 自动分页获取所有结果

分页规则：

设置
```
--keyword
```
时（搜索模式）：使用
```
--page
```
进行分页，
```
--last-id
```
会被忽略
未设置
```
--keyword
```
时（浏览模式）：使用
```
--last-id
```
进行游标分页

[{ "id", "title", "description", "domain", "read", "starred", "tags", "folder", "url", ... }]

Get Card Detail

获取卡片详情

bash

cubox-cli card detail --id CARD_ID

Returns full card with

content

(markdown),

author

annotations

, and

insight

(AI summary + Q&A). Use

-o text

to output only the markdown content.

bash

cubox-cli card detail --id CARD_ID

返回包含

content

（markdown格式）、

author

、

annotations

和

insight

（AI摘要与问答）的完整卡片信息。使用

-o text

可仅输出markdown内容。

RAG Semantic Search

RAG语义搜索

bash

cubox-cli card rag --query "QUERY_TEXT"

Semantic search via natural language. Unlike

--keyword

, RAG understands intent and returns conceptually relevant cards. Must-read: RAG workflow — covers when to use RAG vs keyword, query refinement, progressive detail fetching, and re-ranking.

Returns:

[{ "id", "title", "description", "domain", "tags", "folder", "url", ... }]

(same Card shape as

card list

)

bash

cubox-cli card rag --query "QUERY_TEXT"

通过自然语言进行语义搜索。与

--keyword

不同，RAG能理解意图并返回概念相关的卡片。必读：RAG工作流 — 涵盖何时使用RAG而非关键词搜索、查询优化、渐进式详情获取以及重排序。

[{ "id", "title", "description", "domain", "tags", "folder", "url", ... }]

（与

card list

返回的卡片结构一致）

Save Web Pages

保存网页

bash

cubox-cli save URL [URL...] [--title TEXT] [--desc TEXT] [--folder NAME] [--tag NAME,...]
cubox-cli save --json '[{"url":"...","title":"...","description":"..."}]' [--folder NAME] [--tag NAME,...]

Save one or more web pages as bookmarks. Three input modes:

URL arguments — simple:

cubox-cli save https://example.com https://b.com

Single with metadata —

cubox-cli save https://example.com --title "My Page" --desc "A description"

Batch via JSON —

cubox-cli save --json '[{"url":"https://a.com","title":"Title A"}]'

Folders and tags are specified by name (not ID), including nested paths like

"parent/child"

bash

cubox-cli save URL [URL...] [--title TEXT] [--desc TEXT] [--folder NAME] [--tag NAME,...]
cubox-cli save --json '[{"url":"...","title":"...","description":"..."}]' [--folder NAME] [--tag NAME,...]

将一个或多个网页保存为书签。支持三种输入模式：

URL参数模式 — 简单方式：

cubox-cli save https://example.com https://b.com

带元数据的单个URL模式 —

cubox-cli save https://example.com --title "我的页面" --desc "一段描述"

JSON批量模式 —

cubox-cli save --json '[{"url":"https://a.com","title":"标题A"}]'

文件夹和标签通过名称指定（而非ID），包括嵌套路径如

"parent/child"

。

Update a Card

更新卡片

bash

cubox-cli update --id CARD_ID [flags]

Flags:

```
--star
```
/
```
--unstar
```
— toggle star
```
--read
```
/
```
--unread
```
— toggle read status
```
--archive
```
— archive the card
```
--folder NAME
```
— move to folder by name (e.g.
```
"parent/child"
```
;
```
""
```
= Uncategorized)
```
--tag NAME,...
```
— replace all tags (existing tags are removed and replaced)
```
--add-tag NAME,...
```
— add tags without affecting existing ones
```
--remove-tag NAME,...
```
— remove specific tags only
```
--title TEXT
```
— update title
```
--description TEXT
```
— update description

Tag operation guide — choose the right flag based on user intent:

User says	Flag	Behavior
"刷新/更改/替换/设置 tags"	`--tag`	Replaces all tags (old tags removed)
"添加/新增/加上 tags"	`--add-tag`	Appends tags (existing tags kept)
"删除/移除/去掉 tags"	`--remove-tag`	Removes only specified tags

Folders and tags are specified by name (not ID). No need to query IDs first.

bash

cubox-cli update --id CARD_ID [flags]

可选参数：

```
--star
```
/
```
--unstar
```
— 切换收藏状态
```
--read
```
/
```
--unread
```
— 切换阅读状态
```
--archive
```
— 归档卡片
```
--folder NAME
```
— 按名称移动到指定文件夹（例如
```
"parent/child"
```
；
```
""
```
= 未分类）
```
--tag NAME,...
```
— 替换所有标签（现有标签会被移除并替换）
```
--add-tag NAME,...
```
— 添加标签，不影响现有标签
```
--remove-tag NAME,...
```
— 仅移除指定标签
```
--title TEXT
```
— 更新标题
```
--description TEXT
```
— 更新描述

标签操作指南 — 根据用户意图选择正确的参数：

用户表述	参数	行为
"刷新/更改/替换/设置 tags"	`--tag`	替换所有标签（旧标签被移除）
"添加/新增/加上 tags"	`--add-tag`	追加标签（保留现有标签）
"删除/移除/去掉 tags"	`--remove-tag`	仅移除指定标签

文件夹和标签通过名称指定（而非ID），无需先查询ID。

Delete Cards

删除卡片

bash

cubox-cli delete --id CARD_ID [--id ID2,...] [--dry-run]

Delete cards by ID. Always
--dry-run
first. Must-read: Dry Run Policy — agents must preview before deleting.

bash

cubox-cli delete --id CARD_ID [--id ID2,...] [--dry-run]

按ID删除卡片。请始终先执行
--dry-run
。 必读：试运行规则 — 工具必须在删除前预览操作结果。

List Annotations

列出注释

bash

cubox-cli annotation list [flags]

Flags:

```
--color Yellow,Green,Blue,Pink,Purple
```
— filter by color
```
--keyword TEXT
```
— search annotations
```
--start-time
```
,
```
--end-time
```
— filter by time range (same formats and rules as card list)
```
--limit N
```
— page size (default 50)
```
--last-id ID
```
— cursor pagination
```
--all
```
— auto-paginate all results

Returns:

[{ "id", "text", "note", "color", "card_id", ... }]

bash

cubox-cli annotation list [flags]

可选参数：

```
--color Yellow,Green,Blue,Pink,Purple
```
— 按颜色筛选
```
--keyword TEXT
```
— 搜索注释
```
--start-time
```
,
```
--end-time
```
— 按时间范围筛选（格式和规则与卡片列表一致）
```
--limit N
```
— 每页数量（默认50）
```
--last-id ID
```
— 游标分页
```
--all
```
— 自动分页获取所有结果

[{ "id", "text", "note", "color", "card_id", ... }]

Cubox Deep Links

Cubox深度链接

Construct clickable Cubox links from any resource ID (card, folder, tag). No API call needed — just the ID + server. Must-read: Deep Links — URL patterns, scheme rules, and examples.

Default:

https://{server}/web/card/{ID}

— use

cubox://

scheme only when explicitly requested.

通过任意资源ID（卡片、文件夹、标签）构建可点击的Cubox链接。无需调用API — 只需ID和服务器地址即可。必读：深度链接 — 包含URL格式、协议规则和示例。

默认格式：

https://{server}/web/card/{ID}

— 仅在明确要求时使用

cubox://

协议。

Time filtering

时间过滤

--start-time

and

--end-time

accept flexible shorthand values. The CLI automatically resolves day-level inputs to the correct boundary:

```
--start-time
```
resolves to start of day (00:00:00.000)
```
--end-time
```
resolves to end of day (23:59:59.999)

Accepted formats:

today

yesterday

now

7d

(7 days ago),

2026-01-01

2026-01-01 15:04:05

, or full ISO timestamp.

Common time query patterns:

Intent	Command
Today's cards	`--start-time today --end-time today`
Yesterday's cards	`--start-time yesterday --end-time yesterday`
Last 7 days	`--start-time 7d --end-time today`
Since a date	`--start-time 2026-01-01`
Up to now	`--end-time now`

--start-time

和

--end-time

接受灵活的简写值。CLI会自动将日期级输入解析为正确的时间边界：

```
--start-time
```
解析为当天开始时间（00:00:00.000）
```
--end-time
```
解析为当天结束时间（23:59:59.999）

支持的格式：

today

、

yesterday

、

now

、

7d

（7天前）、

2026-01-01

、

2026-01-01 15:04:05

或完整的ISO时间戳。

常见时间查询模式：

意图	命令
今日卡片	`--start-time today --end-time today`
昨日卡片	`--start-time yesterday --end-time yesterday`
最近7天卡片	`--start-time 7d --end-time today`
指定日期之后的卡片	`--start-time 2026-01-01`
截至当前的卡片	`--end-time now`

Common Workflows

常见工作流

Browse and read a card detail

浏览并查看卡片详情

bash

cubox-cli folder list
cubox-cli card list --folder FOLDER_ID --limit 10
cubox-cli card detail --id CARD_ID

bash

cubox-cli folder list
cubox-cli card list --folder FOLDER_ID --limit 10
cubox-cli card detail --id CARD_ID

Search for articles

搜索文章

bash

cubox-cli card list --keyword "machine learning" --page 1

bash

cubox-cli card list --keyword "machine learning" --page 1

Save a page and star it

保存页面并收藏

bash

cubox-cli save https://example.com --title "Example" --folder "Reading List"
cubox-cli update --id CARD_ID --star

bash

cubox-cli save https://example.com --title "示例页面" --folder "阅读清单"
cubox-cli update --id CARD_ID --star

List cards with Cubox links

生成带Cubox链接的卡片列表

bash

cubox-cli auth status          # determine server (cubox.pro or cubox.cc)
cubox-cli card list --limit 5  # get cards, then append link from ID

bash

cubox-cli auth status          # 确定服务器地址（cubox.pro 或 cubox.cc）
cubox-cli card list --limit 5  # 获取卡片，然后根据ID拼接链接

For card ID 7247925101516031380 on cubox.pro:

对于cubox.pro上的卡片ID 7247925101516031380：

→ https://cubox.pro/web/card/7247925101516031380

undefined

undefined

Export all annotations

导出所有注释

bash

cubox-cli annotation list --all

bash

cubox-cli annotation list --all

Update Check

版本更新检查

cubox-cli automatically checks for new versions in the background. When a newer version is available, the JSON output will contain a

_notice.update

field:

json

{
  "data": [ "..." ],
  "_notice": {
    "update": {
      "current": "0.1.0",
      "latest": "0.2.0",
      "message": "A new version of cubox-cli is available: 0.1.0 -> 0.2.0",
      "command": "npm update -g cubox-cli && npx skills add OLCUBO/cubox-cli -g -y"
    }
  }
}

When you see
_notice.update
in output, after completing the user's current request, proactively offer to update:

Tell the user the current and latest version numbers
Propose running the update (CLI and Skills must be updated together):

bash

 npm update -g cubox-cli && npx skills add OLCUBO/cubox-cli -g -y

After the update, remind the user: exit and reopen the AI Agent to load the latest Skills

Rule: Do not silently ignore update notices. Even if the current task is unrelated, mention the available update after completing the user's request.

cubox-cli会在后台自动检查新版本。当有可用更新时，JSON输出中会包含

_notice.update

字段：

json

{
  "data": [ "..." ],
  "_notice": {
    "update": {
      "current": "0.1.0",
      "latest": "0.2.0",
      "message": "A new version of cubox-cli is available: 0.1.0 -> 0.2.0",
      "command": "npm update -g cubox-cli && npx skills add OLCUBO/cubox-cli -g -y"
    }
  }
}

当输出中出现
_notice.update
时，完成用户当前请求后，请主动提示更新：

告知用户当前版本和最新版本号
建议执行以下更新命令（CLI和Skills需同时更新）：

bash

 npm update -g cubox-cli && npx skills add OLCUBO/cubox-cli -g -y

更新完成后，提醒用户：退出并重新打开AI Agent以加载最新的Skills

规则：请勿忽略更新提示。即使当前任务无关，完成用户请求后也需告知可用更新。

Security Rules

安全规则

Never expose sensitive credentials in plain text (API key/token, session data, auth headers).
Treat Cubox API tokens as local secrets. Do not commit or copy them into repository files, screenshots, or shared notes.
Before any write/destructive action (
```
save
```
,
```
update
```
,
```
delete
```
), confirm user intent first. For deletion, always run
```
--dry-run
```
and present the preview before execution.
When demonstrating commands, use placeholders (for example
```
YOUR_API_KEY
```
) instead of real values.
Avoid leaving secrets in shell history where possible (for example, prefer temporary environment variables and clear them after use).
If credentials are suspected to be leaked, instruct the user to rotate the Cubox API token from the extensions page immediately.

切勿以明文形式暴露敏感凭证（API密钥/令牌、会话数据、认证头）。
将Cubox API令牌视为本地机密。请勿将其提交到代码仓库、截图或共享笔记中。
在执行任何写入/破坏性操作（
```
save
```
、
```
update
```
、
```
delete
```
）前，先确认用户意图。对于删除操作，必须先执行
```
--dry-run
```
并展示预览结果后再执行。
演示命令时，请使用占位符（例如
```
YOUR_API_KEY
```
）而非真实值。
尽可能避免将机密信息留在shell历史中（例如，优先使用临时环境变量并在使用后清除）。
如果怀疑凭证泄露，请指导用户立即从扩展页面重置Cubox API令牌。

Notes

注意事项

Browse pagination uses cursor-based approach (
```
--last-id
```
). Search pagination uses page numbers (
```
--page
```
).
The
```
nested_name
```
field in folders and tags shows the full hierarchy path (e.g.
```
"Parent/Child"
```
).
Card detail includes AI-generated
```
insight
```
with summary and Q&A pairs when available.
Config is stored at
```
~/.config/cubox-cli/config.json
```
.

浏览模式使用游标分页（
```
--last-id
```
）。搜索模式使用页码分页（
```
--page
```
）。
文件夹和标签中的
```
nested_name
```
字段显示完整的层级路径（例如
```
"Parent/Child"
```
）。
卡片详情包含AI生成的
```
insight
```
（摘要与问答对）（如果可用）。
配置文件存储在
```
~/.config/cubox-cli/config.json
```
。