cubox-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cubox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# cubox-cli
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
+[![npm version](https://img.shields.io/npm/v/cubox-cli.svg)](https://www.npmjs.com/package/cubox-cli)
+
+[English](./README.md) | [中文版](./README.zh.md)
+
+The official [Cubox](https://cubox.pro) CLI tool — built for humans and AI Agents. Manage your bookmarks, browse collections, and read saved content from the terminal.
+
+[Install](#installation) · [Auth](#authentication) · [Commands](#commands) · [AI Agent](#quick-start-ai-agent) · [Examples](#examples) · [Development](#development)
+
+## Features
+
+| Category | Capabilities |
+|----------|-------------|
+| Groups | List and browse bookmark folders |
+| Tags | List and browse tag hierarchy |
+| Cards | Filter cards by group, type, tag, starred/read/annotated status; cursor-based pagination |
+| Content | Read full article content in markdown format |
+
+## Installation
+
+### Requirements
+
+- Node.js 16+ (for `npm`/`npx`)
+- Go 1.23+ (only for building from source)
+
+### Quick Start (Human Users)
+
+> **For AI Agents:** jump to [Quick Start (AI Agent)](#quick-start-ai-agent) below.
+
+#### Install
+
+**Option 1 — From npm (recommended):**
+
+```bash
+# Install CLI
+npm install -g cubox-cli
+
+# Install CLI Skill (required for AI Agents)
+npx skills add OLCUBO/cubox-cli -g -y
+```
+
+**Option 2 — From source:**
+
+```bash
+git clone https://github.com/OLCUBO/cubox-cli.git
+cd cubox-cli
+make install
+
+# Install CLI Skill (required for AI Agents)
+npx skills add OLCUBO/cubox-cli -g -y
+```
+
+#### Log in
+
+```bash
+cubox-cli auth login
+```
+
+The CLI will guide you through:
+
+1. **Select your server** — `cubox.pro` (China) or `cubox.cc` (international)
+2. **Get your API key** — the CLI shows the URL to open:
+   - China: https://cubox.pro/web/settings/extensions
+   - International: https://cubox.cc/web/settings/extensions
+3. **Paste the API link** — copy the full link (e.g. `https://cubox.pro/c/api/save/abcdefg`) and paste it. The CLI extracts the token automatically.
+
+#### Start using
+
+```bash
+# List your folders
+cubox-cli group list
+
+# List your tags
+cubox-cli tag list
+
+# Browse recent cards
+cubox-cli card list --limit 5 -o pretty
+
+# Read an article
+cubox-cli card content --id CARD_ID
+```
+
+### Quick Start (AI Agent)
+
+> These steps are for AI Agents helping users set up cubox-cli.
+
+**Step 1 — Install**
+
+```bash
+# Install CLI
+npm install -g cubox-cli
+
+# Install CLI Skill (required)
+npx skills add OLCUBO/cubox-cli -g -y
+```
+
+**Step 2 — Authenticate**
+
+Ask the user which server they use (`cubox.pro` or `cubox.cc`), then instruct them to open the extensions settings page and copy their API link:
+
+- China: `https://cubox.pro/web/settings/extensions`
+- International: `https://cubox.cc/web/settings/extensions`
+
+Once the user provides the API link or token, run:
+
+```bash
+cubox-cli auth login --server cubox.pro --token TOKEN
+```
+
+The `--token` flag accepts either the full API link URL or just the token string.
+
+**Step 3 — Verify**
+
+```bash
+cubox-cli auth status
+```
+
+**Step 4 — Use**
+
+```bash
+cubox-cli group list
+cubox-cli card list --limit 10
+```
+
+## Authentication
+
+| Command | Description |
+|---------|-------------|
+| `cubox-cli auth login` | Interactive login (server selection + token input) |
+| `cubox-cli auth login --server cubox.pro --token TOKEN` | Non-interactive login (for agents) |
+| `cubox-cli auth status` | Show current server, masked token, connection test |
+| `cubox-cli auth logout` | Remove saved credentials |
+
+Credentials are stored at `~/.config/cubox-cli/config.json`.
+
+## Commands
+
+### Output Formats
+
+All commands support the `-o` / `--output` flag:
+
+| Flag | Description |
+|------|-------------|
+| `-o json` | Compact JSON (default, agent-friendly) |
+| `-o pretty` | Indented JSON |
+| `-o text` | Human-readable text/tree output |
+
+### `cubox-cli group list`
+
+List all bookmark groups (folders).
+
+```bash
+cubox-cli group list
+cubox-cli group list -o text
+```
+
+**JSON output fields:** `id`, `nested_name`, `name`, `parent_id`, `uncategorized`
+
+### `cubox-cli tag list`
+
+List all tags.
+
+```bash
+cubox-cli tag list
+cubox-cli tag list -o text
+```
+
+**JSON output fields:** `id`, `nested_name`, `name`, `parent_id`
+
+### `cubox-cli card list`
+
+Filter and list bookmark cards.
+
+```bash
+cubox-cli card list [flags]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--group ID,...` | Filter by group/folder IDs |
+| `--type TYPE,...` | Filter by type: `Article`, `Snippet`, `Memo`, `Image`, `Audio`, `Video`, `File` |
+| `--tag ID,...` | Filter by tag IDs |
+| `--starred` | Only starred cards |
+| `--read` | Only read cards |
+| `--unread` | Only unread cards |
+| `--annotated` | Only cards with highlights |
+| `--limit N` | Page size (default 50) |
+| `--cursor ID,TIME` | Resume from last card for pagination |
+| `--all` | Auto-paginate to fetch all results |
+
+**JSON output fields:** `id`, `title`, `description`, `article_title`, `domain`, `type`, `tags`, `url`, `cubox_url`, `words_count`, `create_time`, `update_time`, `highlights`
+
+### `cubox-cli card content --id ID`
+
+Get the full article content in markdown format.
+
+```bash
+cubox-cli card content --id 7247925101516031380
+```
+
+By default outputs raw markdown. Use `-o pretty` for a JSON envelope.
+
+## Examples
+
+### List all starred articles
+
+```bash
+cubox-cli card list --starred --type Article -o pretty
+```
+
+### Browse cards in a specific folder
+
+```bash
+# Find the folder ID
+cubox-cli group list -o text
+
+# List cards in that folder
+cubox-cli card list --group 7230156249357091393 --limit 10
+```
+
+### Read a saved article
+
+```bash
+cubox-cli card content --id 7247925101516031380
+```
+
+### Fetch all annotated cards with highlights
+
+```bash
+cubox-cli card list --annotated --all -o pretty
+```
+
+### Pagination
+
+```bash
+# First page
+cubox-cli card list --limit 5
+
+# Use the last card's ID and update_time for the next page
+cubox-cli card list --limit 5 --cursor "7247925102807877551,2024-12-04T16:23:01:347+08:00"
+```
+
+## Development
+
+### Build from source
+
+```bash
+git clone https://github.com/OLCUBO/cubox-cli.git
+cd cubox-cli
+make build        # build for current platform
+make build-all    # cross-compile for all platforms
+make release      # create release archives
+```
+
+### Project structure
+
+```
+cubox-cli/
+  main.go                 # entry point
+  cmd/                    # cobra commands
+    root.go               # root command, --output flag
+    auth.go               # auth login/status/logout
+    group.go              # group list
+    tag.go                # tag list
+    card.go               # card list, card content
+    version.go            # version
+  internal/
+    client/               # HTTP client + API types
+    config/               # config file management
+  scripts/                # npm distribution wrapper
+  skills/cubox/           # AI Agent skill
+  .github/workflows/      # CI/CD
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,288 @@
+# cubox-cli
+
+[License: MIT](https://opensource.org/licenses/MIT)
+[Go Version](https://go.dev/)
+[npm version](https://www.npmjs.com/package/cubox-cli)
+
+[English](./README.md) | [中文版](./README.zh.md)
+
+[Cubox](https://cubox.pro) 官方命令行工具 — 为人类用户和 AI Agent 而设计。在终端中管理书签、浏览收藏夹、阅读保存的内容。
+
+[安装](#安装) · [认证](#认证) · [命令](#命令) · [AI Agent](#ai-agent-快速开始) · [示例](#示例) · [开发](#开发)
+
+## 功能
+
+
+| 类别  | 能力                             |
+| --- | ------------------------------ |
+| 收藏夹 | 列出和浏览书签文件夹                     |
+| 标签  | 列出和浏览标签层级                      |
+| 卡片  | 按收藏夹、类型、标签、星标/已读/标注状态过滤卡片；游标分页 |
+| 内容  | 以 Markdown 格式阅读文章全文            |
+
+
+## 安装
+
+### 前置要求
+
+- Node.js 16+（用于 `npm`/`npx`）
+- Go 1.23+（仅从源码构建时需要）
+
+### 快速开始（人类用户）
+
+> **AI Agent 请跳转：** [AI Agent 快速开始](#ai-agent-快速开始)
+
+#### 安装
+
+**方式一 — 通过 npm（推荐）：**
+
+```bash
+# 安装 CLI
+npm install -g cubox-cli
+
+# 安装 CLI Skill（AI Agent 必需）
+npx skills add OLCUBO/cubox-cli -g -y
+```
+
+**方式二 — 从源码构建：**
+
+```bash
+git clone https://github.com/OLCUBO/cubox-cli.git
+cd cubox-cli
+make install
+
+# 安装 CLI Skill（AI Agent 必需）
+npx skills add OLCUBO/cubox-cli -g -y
+```
+
+#### 登录
+
+```bash
+cubox-cli auth login
+```
+
+CLI 会引导你完成以下步骤：
+
+1. **选择服务器** — `cubox.pro`（中国）或 `cubox.cc`（国际版）
+2. **获取 API Key** — CLI 会提示打开对应网址：
+  - 中国版：[https://cubox.pro/web/settings/extensions](https://cubox.pro/web/settings/extensions)
+  - 国际版：[https://cubox.cc/web/settings/extensions](https://cubox.cc/web/settings/extensions)
+3. **粘贴 API 链接** — 复制完整链接（如 `https://cubox.pro/c/api/save/abcdefg`）并粘贴。CLI 会自动提取 token。
+
+#### 开始使用
+
+```bash
+# 列出收藏夹
+cubox-cli group list
+
+# 列出标签
+cubox-cli tag list
+
+# 浏览最近的卡片
+cubox-cli card list --limit 5 -o pretty
+
+# 阅读一篇文章
+cubox-cli card content --id CARD_ID
+```
+
+### AI Agent 快速开始
+
+> 以下步骤适用于 AI Agent 帮助用户设置 cubox-cli。
+
+**步骤 1 — 安装**
+
+```bash
+# 安装 CLI
+npm install -g cubox-cli
+
+# 安装 CLI Skill（必需）
+npx skills add OLCUBO/cubox-cli -g -y
+```
+
+**步骤 2 — 认证**
+
+询问用户使用哪个服务器（`cubox.pro` 或 `cubox.cc`），然后引导用户打开扩展设置页面并复制 API 链接：
+
+- 中国版：`https://cubox.pro/web/settings/extensions`
+- 国际版：`https://cubox.cc/web/settings/extensions`
+
+用户提供 API 链接或 token 后执行：
+
+```bash
+cubox-cli auth login --server cubox.pro --token TOKEN
+```
+
+`--token` 参数接受完整的 API 链接 URL 或纯 token 字符串。
+
+**步骤 3 — 验证**
+
+```bash
+cubox-cli auth status
+```
+
+**步骤 4 — 使用**
+
+```bash
+cubox-cli group list
+cubox-cli card list --limit 10
+```
+
+## 认证
+
+
+| 命令                                                      | 说明                      |
+| ------------------------------------------------------- | ----------------------- |
+| `cubox-cli auth login`                                  | 交互式登录（选择服务器 + 输入 token） |
+| `cubox-cli auth login --server cubox.pro --token TOKEN` | 非交互式登录（适用于 Agent）       |
+| `cubox-cli auth status`                                 | 显示当前服务器、脱敏 token、连接测试   |
+| `cubox-cli auth logout`                                 | 删除已保存的凭证                |
+
+
+凭证保存在 `~/.config/cubox-cli/config.json`。
+
+## 命令
+
+### 输出格式
+
+所有命令支持 `-o` / `--output` 参数：
+
+
+| 参数          | 说明                   |
+| ----------- | -------------------- |
+| `-o json`   | 紧凑 JSON（默认，适合 Agent） |
+| `-o pretty` | 格式化 JSON             |
+| `-o text`   | 人类可读的文本/树形输出         |
+
+
+### `cubox-cli group list`
+
+列出所有收藏夹（文件夹）。
+
+```bash
+cubox-cli group list
+cubox-cli group list -o text
+```
+
+**JSON 输出字段：** `id`, `nested_name`, `name`, `parent_id`, `uncategorized`
+
+### `cubox-cli tag list`
+
+列出所有标签。
+
+```bash
+cubox-cli tag list
+cubox-cli tag list -o text
+```
+
+**JSON 输出字段：** `id`, `nested_name`, `name`, `parent_id`
+
+### `cubox-cli card list`
+
+过滤和列出收藏卡片。
+
+```bash
+cubox-cli card list [flags]
+```
+
+
+| 参数                 | 说明                                                                    |
+| ------------------ | --------------------------------------------------------------------- |
+| `--group ID,...`   | 按收藏夹 ID 过滤                                                            |
+| `--type TYPE,...`  | 按类型过滤：`Article`, `Snippet`, `Memo`, `Image`, `Audio`, `Video`, `File` |
+| `--tag ID,...`     | 按标签 ID 过滤                                                             |
+| `--starred`        | 仅星标卡片                                                                 |
+| `--read`           | 仅已读卡片                                                                 |
+| `--unread`         | 仅未读卡片                                                                 |
+| `--annotated`      | 仅有标注的卡片                                                               |
+| `--limit N`        | 每页数量（默认 50）                                                           |
+| `--cursor ID,TIME` | 分页游标，从上一张卡片继续                                                         |
+| `--all`            | 自动翻页获取全部结果                                                            |
+
+
+**JSON 输出字段：** `id`, `title`, `description`, `article_title`, `domain`, `type`, `tags`, `url`, `cubox_url`, `words_count`, `create_time`, `update_time`, `highlights`
+
+### `cubox-cli card content --id ID`
+
+获取文章全文（Markdown 格式）。
+
+```bash
+cubox-cli card content --id 7247925101516031380
+```
+
+默认输出原始 Markdown。使用 `-o pretty` 获取 JSON 包装格式。
+
+## 示例
+
+### 列出所有星标文章
+
+```bash
+cubox-cli card list --starred --type Article -o pretty
+```
+
+### 浏览特定收藏夹的卡片
+
+```bash
+# 查找收藏夹 ID
+cubox-cli group list -o text
+
+# 列出该收藏夹的卡片
+cubox-cli card list --group 7230156249357091393 --limit 10
+```
+
+### 阅读保存的文章
+
+```bash
+cubox-cli card content --id 7247925101516031380
+```
+
+### 获取所有带标注的卡片
+
+```bash
+cubox-cli card list --annotated --all -o pretty
+```
+
+### 分页
+
+```bash
+# 第一页
+cubox-cli card list --limit 5
+
+# 使用最后一张卡片的 ID 和 update_time 获取下一页
+cubox-cli card list --limit 5 --cursor "7247925102807877551,2024-12-04T16:23:01:347+08:00"
+```
+
+## 开发
+
+### 从源码构建
+
+```bash
+git clone https://github.com/OLCUBO/cubox-cli.git
+cd cubox-cli
+make build        # 为当前平台构建
+make build-all    # 交叉编译所有平台
+make release      # 创建发布包
+```
+
+### 项目结构
+
+```
+cubox-cli/
+  main.go                 # 入口
+  cmd/                    # cobra 命令
+    root.go               # 根命令，--output 参数
+    auth.go               # auth login/status/logout
+    group.go              # group list
+    tag.go                # tag list
+    card.go               # card list, card content
+    version.go            # version
+  internal/
+    client/               # HTTP 客户端 + API 类型
+    config/               # 配置文件管理
+  scripts/                # npm 分发包装
+  skills/cubox/           # AI Agent Skill
+  .github/workflows/      # CI/CD
+```
+
+## 许可证
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "cubox-cli",
+  "version": "1.0.0",
+  "description": "The official Cubox CLI tool, built for humans and AI Agents",
+  "bin": {
+    "cubox-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OLCUBO/cubox-cli.git"
+  },
+  "license": "MIT",
+  "files": [
+    "scripts/install.js",
+    "scripts/run.js"
+  ]
+}

package/scripts/install.js

@@ -0,0 +1,92 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const os = require("os");
+
+const VERSION = require("../package.json").version;
+const REPO = "OLCUBO/cubox-cli";
+const NAME = "cubox-cli";
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const platform = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+
+if (!platform || !arch) {
+  console.error(
+    `Unsupported platform: ${process.platform}-${process.arch}`
+  );
+  process.exit(1);
+}
+
+const isWindows = process.platform === "win32";
+const ext = isWindows ? ".zip" : ".tar.gz";
+const archiveName = `${NAME}-${VERSION}-${platform}-${arch}${ext}`;
+const GITHUB_URL = `https://github.com/${REPO}/releases/download/v${VERSION}/${archiveName}`;
+
+const binDir = path.join(__dirname, "..", "bin");
+const dest = path.join(binDir, NAME + (isWindows ? ".exe" : ""));
+
+fs.mkdirSync(binDir, { recursive: true });
+
+function download(url, destPath) {
+  const sslFlag = isWindows ? "--ssl-revoke-best-effort " : "";
+  execSync(
+    `curl ${sslFlag}--fail --location --silent --show-error --connect-timeout 10 --max-time 120 --output "${destPath}" "${url}"`,
+    { stdio: ["ignore", "ignore", "pipe"] }
+  );
+}
+
+function install() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cubox-cli-"));
+  const archivePath = path.join(tmpDir, archiveName);
+
+  try {
+    download(GITHUB_URL, archivePath);
+
+    if (isWindows) {
+      execSync(
+        `powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}'"`,
+        { stdio: "ignore" }
+      );
+    } else {
+      execSync(`tar -xzf "${archivePath}" -C "${tmpDir}"`, {
+        stdio: "ignore",
+      });
+    }
+
+    const binaryName = NAME + (isWindows ? ".exe" : "");
+    const extractedBinary = path.join(tmpDir, binaryName);
+
+    fs.copyFileSync(extractedBinary, dest);
+    fs.chmodSync(dest, 0o755);
+    console.log(`${NAME} v${VERSION} installed successfully`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+try {
+  install();
+} catch (err) {
+  console.error(`Failed to install ${NAME}:`, err.message);
+  console.error(
+    `\nYou can also build from source:\n` +
+    `  git clone https://github.com/${REPO}.git\n` +
+    `  cd cubox-cli\n` +
+    `  make install\n` +
+    `\nIf behind a firewall, try setting a proxy:\n` +
+    `  export https_proxy=http://your-proxy:port\n` +
+    `  npm install -g cubox-cli`
+  );
+  process.exit(1);
+}

package/scripts/run.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const { execFileSync } = require("child_process");
+const path = require("path");
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const bin = path.join(__dirname, "..", "bin", "cubox-cli" + ext);
+
+try {
+  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status || 1);
+}