### Install and Use BestBlogs CLI

Source: https://github.com/ginobefun/bestblogs/blob/main/README.md

Install the official command-line tool globally and use it for authentication, setup, discovery, reading, and capturing content. All commands support a --json mode for AI consumption.

```bash
npm install -g @bestblogs/cli
bestblogs auth login
bestblogs intake setup           # 冷启动：选兴趣标签
bestblogs discover today --limit 20
bestblogs read deep <resourceId>
bestblogs capture bookmark add <resourceId> --note "值得反复读"
```

--------------------------------

### Install BestBlogs Agent Skills

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Install all BestBlogs Agent Skills with a single command. After installation, you can interact with BestBlogs using natural language prompts.

```bash
npx @bestblogs/skills           # Install all Skills in one step
# After install, just say: "What's worth reading on BestBlogs today?"
```

--------------------------------

### Install BestBlogs CLI

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Installs the BestBlogs CLI globally and logs in. This is a prerequisite for using the skills.

```bash
npm install -g @bestblogs/cli
bestblogs auth login
```

--------------------------------

### Install Skills using npm Package

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Installs skills for agents using the @bestblogs/skills npm package. Includes commands to install and list available skills.

```bash
npx @bestblogs/skills install --client codex
npx @bestblogs/skills install --client claude
npx @bestblogs/skills list
```

--------------------------------

### Install and Use BestBlogs Skills

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Install BestBlogs agent skills to enable AI agents like Claude Code and Codex to actively invoke BestBlogs capabilities. Shows commands for installation and upgrading.

```bash
npx @bestblogs/skills             # Install to Claude Code and Codex by default
npx @bestblogs/skills --client codex
npx @bestblogs/skills upgrade     # Upgrade to the latest version
```

--------------------------------

### Install and Use BestBlogs CLI

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Install the BestBlogs CLI globally and log in with your API key. Use it to discover content and read articles.

```bash
npm install -g @bestblogs/cli
bestblogs auth login           # Enter your API Key (generate in Settings)
bestblogs discover today       # Today's most worth-reading content
bestblogs read deep <id>       # Deep-read one article
```

--------------------------------

### Install and Use BestBlogs CLI

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Install the official command-line tool globally and use it to authenticate, set up interests, discover content, read articles, and capture bookmarks.

```bash
npm install -g @bestblogs/cli
bestblogs auth login
bestblogs intake setup           # Cold start: pick interest tags
bestblogs discover today --limit 20
bestblogs read deep <resourceId>
bestblogs capture bookmark add <resourceId> --note "Worth re-reading"
```

--------------------------------

### CLI - Intake Setup

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Sets up the user's interest profile for content discovery by allowing selection of interest tags.

```APIDOC
## bestblogs intake setup

### Description
Initiates the cold-start onboarding process by allowing users to pick interest tags for their profile.

### Method
CLI Command

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
bestblogs intake setup
```

### Response
Confirmation message after interest tags are set.
```

--------------------------------

### Install Skills to Codex Only

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Installs the BestBlogs skills specifically for the Codex agent.

```bash
./install.sh --client codex
```

--------------------------------

### Manual Installation via Git Clone

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Manually installs skills by cloning the repository and creating symbolic links to the Codex skills directory.

```bash
git clone https://github.com/ginobefun/bestblogs-monorepo.git
ln -s $(pwd)/bestblogs-monorepo/bestblogs-skills/skills/* ~/.codex/skills/
```

--------------------------------

### Install Skills to Agents

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Installs the BestBlogs skills by creating symbolic links to agent-specific skill directories. Supports Claude Code and Codex.

```bash
./install.sh
```

--------------------------------

### Install Skills to Claude Code Only

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Installs the BestBlogs skills specifically for the Claude Code agent.

```bash
./install.sh --client claude
```

--------------------------------

### Agent Tool Schema Example

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/README.md

Example of a tool schema definition for an agent, showing how to invoke the 'bestblogs discover today' command with specific parameters and output schema.

```yaml
TOOL_SCHEMA:
  name: bestblogs_discover_today
  invocation: bestblogs discover today --limit 20 --json
  output_schema: see ../bestblogs-cli/src/api/types.ts CandidateExplainSchema
```

--------------------------------

### Skills - Install

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Installs the BestBlogs skills, making BestBlogs capabilities available to AI agents like Claude Code and Codex.

```APIDOC
## npx @bestblogs/skills

### Description
Installs the BestBlogs skills, enabling AI agents to invoke BestBlogs capabilities. Installs to Claude Code and Codex by default.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--client** (string) - Optional - Specifies the client to install skills for (e.g., 'codex').

### Request Example
```bash
npx @bestblogs/skills
npx @bestblogs/skills --client codex
```

### Response
Confirmation message indicating successful installation.
```

--------------------------------

### Install and Use BestBlogs Skills for Agents

Source: https://github.com/ginobefun/bestblogs/blob/main/README.md

Install the BestBlogs Skills package to enable AI agents like Claude Code, Codex, and Cursor to trigger BestBlogs capabilities. The package provides 25 stable primitives.

```bash
npx @bestblogs/skills             # 默认安装到 Claude Code 和 Codex
npx @bestblogs/skills --client codex
npx @bestblogs/skills upgrade     # 升级到最新版
```

--------------------------------

### Browse All Topics (Chinese)

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/bestblogs-topic/SKILL.md

Use this command to get a list of all available topics in Chinese. The output includes details like slug, type, title, summary, and tags.

```bash
bestblogs topics list --lang zh --json
```

--------------------------------

### Skills - Upgrade

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Upgrades the installed BestBlogs skills to the latest available version.

```APIDOC
## npx @bestblogs/skills upgrade

### Description
Upgrades the BestBlogs skills to the latest version.

### Method
CLI Command

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
npx @bestblogs/skills upgrade
```

### Response
Confirmation message indicating successful upgrade.
```

--------------------------------

### Example Topic List Response

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/bestblogs-topic/SKILL.md

This JSON structure represents the response when listing topics. It includes a list of topics with their metadata and the total count.

```json
{
  "success": true,
  "data": {
    "topics": [
      {
        "slug": "vibe-coding",
        "type": "DOMAIN",
        "title": "Vibe Coding",
        "summary": "AI 辅助编程的全新范式……",
        "tagCodes": ["AI_CODING", "LLM"],
        "publishedAt": "2026-04-20T00:00:00Z",
        "pinnedOrder": 1
      }
    ],
    "totalCount": 12
  }
}
```

--------------------------------

### GET /openapi/v2/me/bookmarks

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/05-capture.md

Retrieves a list of the current user's bookmarks. Supports filtering by various criteria, sorting, and pagination.

```APIDOC
## GET /openapi/v2/me/bookmarks

### Description
Retrieves a list of the current user's bookmarks. Supports filtering by various criteria, sorting, and pagination.

### Method
GET

### Endpoint
/openapi/v2/me/bookmarks

### Parameters
#### Query Parameters
- **page** (Integer) - Optional - Current page number
- **pageSize** (Integer) - Optional - Number of items per page, maximum 50
- **tagId** (String) - Optional - Filter by tag ID
- **folderId** (String) - Optional - Filter by folder ID
- **keyword** (String) - Optional - Search by title/note keyword
- **sortBy** (String) - Optional - Sort field: `createdTime` (collection time) / `publishDate` (publish time)
- **sortDirection** (String) - Optional - Sort direction: `ASC` / `DESC`
- **startDate** (String) - Optional - Collection start date (YYYY-MM-DD)
- **endDate** (String) - Optional - Collection end date (YYYY-MM-DD)

### Response
#### Success Response (200)
- **success** (Boolean) - Indicates if the request was successful
- **code** (null) - Error code, null if successful
- **message** (null) - Error message, null if successful
- **requestId** (String) - Unique request ID
- **data** (Object) - Contains the list of bookmarks and pagination info
  - **currentPage** (Integer) - Current page number
  - **pageSize** (Integer) - Items per page
  - **totalCount** (Integer) - Total number of bookmarks
  - **pageCount** (Integer) - Total number of pages
  - **dataList** (Array) - List of bookmark objects
    - **id** (String) - Unique bookmark ID
    - **resourceId** (String) - Resource ID
    - **resourceType** (String) - Content type: `ARTICLE` / `PODCAST` / `VIDEO` / `TWEET`
    - **title** (String) - Content title
    - **summary** (String) - Content summary
    - **cover** (String) - Cover image URL
    - **sourceName** (String) - Source name
    - **resourceUrl** (String) - Original resource URL
    - **publishDate** (String) - Publication date
    - **note** (String) - User note (can be empty)
    - **tagIds** (Array&lt;String&gt;) - Associated tag IDs
    - **folderId** (String) - Folder ID (can be empty)
    - **createdTime** (String) - Collection time

### Response Example
```json
{
  "success": true,
  "code": null,
  "message": null,
  "requestId": "T2f24f1e7328f4e3a80bf82bd452c0192",
  "data": {
    "currentPage": 1,
    "pageSize": 20,
    "totalCount": 42,
    "pageCount": 3,
    "dataList": [
      {
        "id": "BM_abc123",
        "resourceId": "RES_xyz789",
        "resourceType": "ARTICLE",
        "title": "DeepSeek-V3 推理优化实践",
        "summary": "本文详细介绍了 DeepSeek-V3 在推理阶段的优化策略...",
        "cover": "https://cdn.bestblogs.dev/cover/RES_xyz789.jpg",
        "sourceName": "机器之心",
        "resourceUrl": "https://example.com/article",
        "publishDate": "2026-04-19T00:00:00.000Z",
        "note": "重点看第三节的量化策略",
        "tagIds": ["TAG_001", "TAG_002"],
        "folderId": "FOLDER_001",
        "createdTime": "2026-04-20T08:30:00.000Z"
      }
    ]
  }
}
```
```

--------------------------------

### GET /openapi/v2/interests/tags

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/02-intake.md

Retrieves the full library of interest tags, displayed in groups by domain. This can be used for the tag selection page during cold start or for browsing the tag library.

```APIDOC
## GET /openapi/v2/interests/tags

### Description
Retrieves the full library of interest tags, displayed in groups by domain. This can be used for the tag selection page during cold start or for browsing the tag library.

### Method
GET

### Endpoint
/openapi/v2/interests/tags

### Parameters
#### Query Parameters
- **category** (String) - Optional - Filter by category, e.g. `Programming`
- **keyword** (String) - Optional - Keyword search for tag names
- **limit** (Integer) - Optional - Maximum number of results to return, defaults to 100

### Response
#### Success Response (200)
- **groups** (Array) - List of tags grouped by category.
  - **category** (String) - Category name (e.g. `AI & Machine Learning`, `Programming`)
  - **tags** (Array) - List of tags within this category.
    - **id** (String) - Tag unique ID (MongoDB _id)
    - **code** (String) - Tag code, globally unique (e.g. `ai-coding`)
    - **zhName** (String) - Tag Chinese name
    - **enName** (String) - Tag English name
    - **type** (String) - Tag type: `domain` (domain) / `topic` (topic) / `entity` (entity) / `format` (format)
    - **category** (String) - Category it belongs to
    - **parentCode** (String) - Parent tag code
    - **usedInColdStart** (Boolean) - Whether it is used for cold start selection
    - **referenceCount** (Integer) - Number of users who selected this tag, can be used to display popularity for sorting
- **total** (Integer) - Total number of tags (sum of all categories)

#### Response Example
```json
{
  "success": true,
  "code": null,
  "message": null,
  "requestId": "T2f24f1e7328f4e3a80bf82bd452c0192",
  "data": {
    "groups": [
      {
        "category": "AI & Machine Learning",
        "tags": [
          {
            "id": "tag_001",
            "code": "ai-coding",
            "zhName": "AI 编程",
            "enName": "AI Coding",
            "type": "topic",
            "category": "AI & Machine Learning",
            "parentCode": "artificial-intelligence",
            "exposedToUser": true,
            "usedInColdStart": true,
            "enabled": true,
            "referenceCount": 1234
          }
        ]
      }
    ],
    "total": 86
  }
}
```
```

--------------------------------

### Get Interest Tags Library

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/02-intake.md

Retrieves the full list of interest tags, grouped by category. Useful for the cold start tag selection page or tag library browsing. Requires an API Key for authentication.

```json
{
  "success": true,
  "code": null,
  "message": null,
  "requestId": "T2f24f1e7328f4e3a80bf82bd452c0192",
  "data": {
    "groups": [
      {
        "category": "AI & Machine Learning",
        "tags": [
          {
            "id": "tag_001",
            "code": "ai-coding",
            "zhName": "AI 编程",
            "enName": "AI Coding",
            "type": "topic",
            "category": "AI & Machine Learning",
            "parentCode": "artificial-intelligence",
            "exposedToUser": true,
            "usedInColdStart": true,
            "enabled": true,
            "referenceCount": 1234
          }
        ]
      }
    ],
    "total": 86
  }
}
```

--------------------------------

### BestBlogs RSS Feed Examples

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Examples of RSS feed URLs for different content scopes on BestBlogs.dev. These can be used in any RSS reader.

```text
https://www.bestblogs.dev/zh/feeds/rss
https://www.bestblogs.dev/zh/feeds/rss?featured=y
https://www.bestblogs.dev/zh/feeds/rss?category=programming&type=article
https://www.bestblogs.dev/en/feeds/rss?category=ai&minScore=90
https://www.bestblogs.dev/zh/feeds/rss/newsletter
https://www.bestblogs.dev/zh/feeds/rss/daily-brief
```

--------------------------------

### Browse All Topics (English)

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/bestblogs-topic/SKILL.md

Retrieves a list of all available topics in English. This is useful for users who prefer English content or for cross-referencing.

```bash
bestblogs topics list --lang en --json
```

--------------------------------

### Run Synchronization Script

Source: https://github.com/ginobefun/bestblogs/blob/main/CLAUDE.md

Execute the synchronization script from the monorepo root directory to update the public content mirror. Specify an optional path to the BestBlogs monorepo.

```bash
# 在 monorepo 根目录运行
./scripts/sync-to-public.sh [/path/to/BestBlogs]
```

--------------------------------

### Preview Synchronization

Source: https://github.com/ginobefun/bestblogs/blob/main/CLAUDE.md

Run the synchronization script with the --dry-run flag to preview changes without actually writing them to the repository.

```bash
# 仅预览不写入
./scripts/sync-to-public.sh --dry-run
```

--------------------------------

### GET /openapi/v2/me/bookmarks/{resourceId}/check

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/05-capture.md

Checks if a specific content has been bookmarked. Useful for initializing button states in content lists.

```APIDOC
## GET /openapi/v2/me/bookmarks/{resourceId}/check

### Description
Checks if a specific content has been bookmarked. Useful for initializing button states in content lists.

### Method
GET

### Endpoint
/openapi/v2/me/bookmarks/{resourceId}/check

### Parameters
#### Path Parameters
- **resourceId** (String) - Required - Resource ID to check for bookmark status

### Response
#### Success Response (200)
- **success** (Boolean) - Indicates if the request was successful
- **code** (null) - Error code, null if successful
- **message** (null) - Error message, null if successful
- **requestId** (String) - Unique request ID
- **data** (Object) - Contains bookmark status and details
  - **bookmarked** (Boolean) - True if the content is bookmarked, false otherwise
  - **bookmark** (Object or null) - Bookmark details if `bookmarked` is true, otherwise null
    - **id** (String) - Bookmark ID
    - **resourceId** (String) - Resource ID
    - **note** (String) - User note
    - **tagIds** (Array&lt;String&gt;) - Associated tag IDs
    - **createdTime** (String) - Collection time

### Response Example
```json
{
  "success": true,
  "code": null,
  "message": null,
  "requestId": "T2f24f1e7328f4e3a80bf82bd452c0192",
  "data": {
    "bookmarked": true,
    "bookmark": {
      "id": "BM_abc123",
      "resourceId": "RES_xyz789",
      "note": "重点看第三节",
      "tagIds": [],
      "createdTime": "2026-04-20T08:30:00.000Z"
    }
  }
}
```
```

--------------------------------

### View Topic Details (English)

Source: https://github.com/ginobefun/bestblogs/blob/main/skills/bestblogs-topic/SKILL.md

Fetches detailed information for a specific topic slug in English. This command is useful for accessing content in a different language.

```bash
bestblogs topics get vibe-coding --lang en --json
```

--------------------------------

### CLI - Capture Bookmark Add

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Adds a bookmark for a given resource ID, with an optional note.

```APIDOC
## bestblogs capture bookmark add <resourceId>

### Description
Adds a bookmark for a specified resource, allowing an optional note to be attached.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
- **resourceId** (string) - Required - The unique identifier of the resource to bookmark.
#### Query Parameters
- **--note** (string) - Optional - A note to associate with the bookmark.

### Request Example
```bash
bestblogs capture bookmark add <resourceId> --note "Worth re-reading"
```

### Response
Confirmation message indicating the bookmark has been added.
```

--------------------------------

### GET /openapi/v2/me/briefs/history

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/03-discover.md

Retrieves a list of the current user's historical daily briefs, sorted by date in descending order.

```APIDOC
## GET /openapi/v2/me/briefs/history

### Description
Retrieves a list of the current user's historical daily briefs, sorted by date in descending order.

### Method
GET

### Endpoint
/openapi/v2/me/briefs/history

### Parameters
#### Query Parameters
- **page** (Integer) - Optional - Default: 1 - Current page number.
- **pageSize** (Integer) - Optional - Default: 10 - Number of items per page, maximum 30.

### Response
#### Success Response (200)
Returns a list of briefs. Each item follows the format of `GET /openapi/v2/briefs/public/today`, but `contentItems` may be an empty array to save bandwidth.
```

--------------------------------

### CLI - Discover Today

Source: https://github.com/ginobefun/bestblogs/blob/main/README.en.md

Retrieves a list of recommended content for the current day, with an option to limit the number of results.

```APIDOC
## bestblogs discover today

### Description
Fetches today's recommended content. Supports limiting the number of results.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```bash
bestblogs discover today --limit 20
```

### Response
A list of recommended content items.
```

--------------------------------

### GET /openapi/v2/resources/{id}/content

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/04-read.md

Retrieves the main body content of a resource in HTML format, suitable for web rendering scenarios.

```APIDOC
## GET /openapi/v2/resources/{id}/content

### Description
Retrieves the main body content of the resource in HTML format, suitable for web rendering scenarios.

### Method
GET

### Endpoint
/openapi/v2/resources/{id}/content

### Parameters
#### Path Parameters
- **id** (String) - Required - Resource ID (e.g., `RES_abc123`)

### Response
#### Success Response (200)
- **content** (String) - Original main body content (HTML)
- **translateContent** (String) - AI translated content (HTML, provided if the original is in English with a Chinese translation)
```

--------------------------------

### Get Bookmarks List

Source: https://github.com/ginobefun/bestblogs/blob/main/openapi/05-capture.md

Retrieves a list of user's bookmarks with support for filtering, sorting, and pagination. Used to display saved content.

```json
{
  "success": true,
  "code": null,
  "message": null,
  "requestId": "T2f24f1e7328f4e3a80bf82bd452c0192",
  "data": {
    "currentPage": 1,
    "pageSize": 20,
    "totalCount": 42,
    "pageCount": 3,
    "dataList": [
      {
        "id": "BM_abc123",
        "resourceId": "RES_xyz789",
        "resourceType": "ARTICLE",
        "title": "DeepSeek-V3 推理优化实践",
        "summary": "本文详细介绍了 DeepSeek-V3 在推理阶段的优化策略...",
        "cover": "https://cdn.bestblogs.dev/cover/RES_xyz789.jpg",
        "sourceName": "机器之心",
        "resourceUrl": "https://example.com/article",
        "publishDate": "2026-04-19T00:00:00.000Z",
        "note": "重点看第三节的量化策略",
        "tagIds": ["TAG_001", "TAG_002"],
        "folderId": "FOLDER_001",
        "createdTime": "2026-04-20T08:30:00.000Z"
      }
    ]
  }
}
```