paper-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

paper CLI — Academic Paper Management

paper CLI — 学术论文管理

paper

is a local-first CLI tool for managing academic papers with AI-powered semantic search. It stores data in SQLite databases and uses FAISS vector stores for similarity search.

paper

是一款本地优先的CLI工具，用于管理学术论文，具备AI驱动的语义搜索功能。它将数据存储在SQLite数据库中，并使用FAISS向量存储进行相似度搜索。

Installation

安装

The tool is published on npm as

paper-manager

. It requires Node.js >= 24.

bash

undefined

该工具在npm上以

paper-manager

的名称发布，要求Node.js >= 24。

bash

undefined

Global install (recommended — makes

paper

available everywhere)

全局安装（推荐——可在任意位置使用

paper

命令）

npm install -g paper-manager

Or with pnpm

或使用pnpm安装

pnpm add -g paper-manager

Verify installation

验证安装

paper --version


After installing, run `paper --help` to see available commands. You'll need to configure an embedding model before using knowledge base features — see the Setup Workflow section below.

paper --version


安装完成后，运行`paper --help`查看可用命令。在使用知识库功能前，你需要先配置嵌入模型——请参阅下方的设置流程章节。

Core Concepts

核心概念

Scope: User vs Project

作用域：用户级 vs 项目级

Every resource (config, knowledge base, literature) lives in one of two scopes:

Project scope (default): stored in
```
./.paper-manager/
```
— tied to the current directory, good for project-specific paper collections
User scope (
```
--user
```
flag): stored in
```
~/.paper-manager/
```
— shared across all projects, good for a personal paper library

Project-level config overrides user-level config. When looking up a knowledge base or literature, the tool checks project scope first, then falls back to user scope.

所有资源（配置、知识库、文献）都属于以下两种作用域之一：

项目级作用域（默认）：存储在
```
./.paper-manager/
```
中——与当前目录绑定，适合项目专属的论文合集
用户级作用域（使用
```
--user
```
参数）：存储在
```
~/.paper-manager/
```
中——可在所有项目间共享，适合个人论文库

项目级配置会覆盖用户级配置。当查找知识库或文献时，工具会先检查项目级作用域，再回退到用户级作用域。

Data Hierarchy

数据层级

Config (embedding models)
  └── Knowledge Base (has a name, description, and embedding model)
        └── Literature (a paper with metadata, PDF, and vector embeddings)
              └── Notes (key-value pairs for personal annotations)

You must configure an embedding model before creating a knowledge base, and you must create a knowledge base before adding literature.

配置（嵌入模型）
  └── 知识库（包含名称、描述和嵌入模型）
        └── 文献（包含元数据、PDF和向量嵌入的论文）
              └── 笔记（用于个人注释的键值对）

在创建知识库前，你必须先配置嵌入模型；在添加文献前，你必须先创建知识库。

Setup Workflow

设置流程

Before using

paper

, configure at least one embedding model. The config value for

embeddingModels

is a JSON object mapping model IDs to their settings:

bash

undefined

使用

paper

前，至少需要配置一个嵌入模型。

embeddingModels

的配置值是一个JSON对象，映射模型ID到其设置：

bash

undefined

Set up an embedding model (OpenAI-compatible provider)

设置嵌入模型（兼容OpenAI的提供商）

paper config set embeddingModels '{"my-model": {"provider": "openai", "model": "text-embedding-3-small", "apiKey": "sk-...", "dimensions": 1536}}' --user

Set a default model so you don't have to specify it every time

设置默认模型，避免每次都指定

paper config set defaultEmbeddingModelId my-model --user


The embedding model config fields:
- `provider`: currently only `"openai"` (works with any OpenAI-compatible API)
- `model`: the model name (e.g., `"text-embedding-3-small"`)
- `baseUrl`: optional custom API endpoint
- `apiKey`: API key for the provider
- `dimensions`: embedding vector dimensions (e.g., 1536)

paper config set defaultEmbeddingModelId my-model --user


嵌入模型的配置字段：
- `provider`：目前仅支持`"openai"`（适用于任何兼容OpenAI的API）
- `model`：模型名称（例如`"text-embedding-3-small"`）
- `baseUrl`：可选的自定义API端点
- `apiKey`：提供商的API密钥
- `dimensions`：嵌入向量的维度（例如1536）

Command Reference

命令参考

paper config — Configuration Management

paper config — 配置管理

bash

paper config list [--user]              # Show all config (merged or user-only)
paper config get <key> [--user]         # Get a specific config value
paper config set <key> <value> [--user] # Set a config value (value is parsed as JSON, falls back to string)
paper config remove <key> [--user]      # Remove a config key

Config keys:

embeddingModels

— a JSON object of

{ [modelId]: { provider, model, baseUrl?, apiKey, dimensions } }

```
defaultEmbeddingModelId
```
— which model ID to use when none is specified

bash

paper config list [--user]              # 显示所有配置（合并后的或仅用户级）
paper config get <key> [--user]         # 获取特定配置值
paper config set <key> <value> [--user] # 设置配置值（值会先解析为JSON，解析失败则存储原始字符串）
paper config remove <key> [--user]      # 删除配置键

配置键：

embeddingModels

— 一个JSON对象，格式为

{ [modelId]: { provider, model, baseUrl?, apiKey, dimensions } }

```
defaultEmbeddingModelId
```
— 未指定模型时使用的模型ID

paper kb — Knowledge Base Management

paper kb — 知识库管理

bash

undefined

bash

undefined

Create a knowledge base (requires an embedding model in config)

创建知识库（要求配置中已有嵌入模型）

paper kb create <name> -d <description> [-e <embedding-model-id>] [--user]

List knowledge bases

列出知识库

paper kb list [--user | --all]

Remove a knowledge base and ALL its data (literatures, PDFs, vectors)

删除知识库及其所有数据（文献、PDF、向量）

paper kb remove <id>

Semantic search across a knowledge base

在知识库中进行语义搜索

paper kb query <id> <query-text> [-k <top-k>] # default top-k is 5


The `<id>` for knowledge bases is a UUID assigned at creation time. Use `paper kb list` to find it.

paper kb query <id> <query-text> [-k <top-k>] # 默认top-k为5


知识库的`<id>`是创建时分配的UUID。使用`paper kb list`命令查看。

paper lit — Literature Management

paper lit — 文献管理

bash

undefined

bash

undefined

Add a paper (extracts PDF, splits text, creates embeddings)

添加论文（提取PDF内容、拆分文本、创建嵌入向量）

paper lit add <kb-id> <pdf-path> [-t <title>]

Title defaults to the PDF filename if not specified

若未指定标题，默认使用PDF文件名

List papers in a knowledge base

列出知识库中的论文

paper lit list <kb-id>

Show full details of a paper

查看论文的完整详情

paper lit show <kb-id> <lit-id>

Update paper metadata

更新论文元数据

paper lit update <kb-id> <lit-id> [options]

-t, --title <title>

--title-translation <translation>

-a, --author <author>

--abstract <abstract>

--summary <summary>

--url <url>

--keywords <comma-separated-keywords>

Remove a paper (deletes DB record, PDF file; vectors remain in store)

删除论文（删除数据库记录和PDF文件；向量仍保留在存储中）

paper lit remove <kb-id> <lit-id>

undefined

paper lit remove <kb-id> <lit-id>

undefined

paper lit note — Literature Notes

paper lit note — 文献笔记

Notes are key-value string pairs attached to a literature entry — useful for personal annotations.

bash

paper lit note list <lit-id>                    # List all notes
paper lit note set <lit-id> <key> <value>       # Set a note
paper lit note remove <lit-id> <key>            # Remove a note

Note: the note commands take

<lit-id>

directly (not

<kb-id> <lit-id>

笔记是附加在文献条目上的键值字符串对——适用于个人注释。

bash

paper lit note list <lit-id>                    # 列出所有笔记
paper lit note set <lit-id> <key> <value>       # 设置笔记
paper lit note remove <lit-id> <key>            # 删除笔记

注意：笔记命令直接使用

<lit-id>

（而非

<kb-id> <lit-id>

）。

Common Workflows

常见工作流程

First-time setup

首次设置

paper config set embeddingModels '<json>' --user

— configure embedding model

paper config set defaultEmbeddingModelId <id> --user

— set default model

paper config set embeddingModels '<json>' --user

— 配置嵌入模型

paper config set defaultEmbeddingModelId <id> --user

— 设置默认模型

Start a new research project

启动新研究项目

paper kb create "my-project" -d "Papers about X"

— create a project-scoped KB

paper lit add <kb-id> ./paper.pdf -t "Paper Title"

— add papers

paper kb query <kb-id> "your research question"

— search

paper kb create "my-project" -d "关于X的论文"

— 创建项目级知识库

paper lit add <kb-id> ./paper.pdf -t "论文标题"

— 添加论文

paper kb query <kb-id> "你的研究问题"

— 进行搜索

Manage paper metadata

管理论文元数据

```
paper lit list <kb-id>
```
— find the literature ID

paper lit update <kb-id> <lit-id> -a "Author Name" --keywords "ML,NLP"

paper lit note set <lit-id> takeaway "Key insight from this paper"

```
paper lit list <kb-id>
```
— 查找文献ID

paper lit update <kb-id> <lit-id> -a "作者姓名" --keywords "ML,NLP"

paper lit note set <lit-id> takeaway "本文的核心观点"

Important Notes

重要提示

All IDs (knowledge base, literature) are UUIDs — always use
```
list
```
commands to look them up
Adding a paper (
```
lit add
```
) extracts the PDF, splits it into chunks, and creates vector embeddings — this calls the embedding API and may take some time
The
```
kb remove
```
command is destructive: it deletes the knowledge base, all its literatures, PDFs, and vector stores
The
```
--user
```
flag on
```
config
```
/
```
kb create
```
controls scope; omitting it uses project scope
Config values passed to
```
config set
```
are parsed as JSON first; if JSON parsing fails, the raw string is stored

所有ID（知识库、文献）均为UUID——请始终使用
```
list
```
命令查找
添加论文（
```
lit add
```
）会提取PDF内容、拆分为文本块并创建向量嵌入——这会调用嵌入API，可能需要一些时间
```
kb remove
```
命令具有破坏性：它会删除知识库、其下所有文献、PDF和向量存储
```
config
```
/
```
kb create
```
命令中的
```
--user
```
参数控制作用域；省略该参数则使用项目级作用域
传递给
```
config set
```
的配置值会先尝试解析为JSON；若解析失败，则存储原始字符串

paper-cli

Original

Translation

paper CLI — Academic Paper Management

paper CLI — 学术论文管理

Installation

安装

Global install (recommended — makes paper available everywhere)

全局安装（推荐——可在任意位置使用paper命令）

Or with pnpm

或使用pnpm安装

Verify installation

验证安装

Core Concepts

核心概念

Scope: User vs Project

作用域：用户级 vs 项目级

Data Hierarchy

数据层级

Setup Workflow

设置流程

Set up an embedding model (OpenAI-compatible provider)

设置嵌入模型（兼容OpenAI的提供商）

Set a default model so you don't have to specify it every time

设置默认模型，避免每次都指定

Command Reference

命令参考

paper config — Configuration Management

paper config — 配置管理

paper kb — Knowledge Base Management

paper kb — 知识库管理

Create a knowledge base (requires an embedding model in config)

创建知识库（要求配置中已有嵌入模型）

List knowledge bases

列出知识库

Remove a knowledge base and ALL its data (literatures, PDFs, vectors)

删除知识库及其所有数据（文献、PDF、向量）

Semantic search across a knowledge base

在知识库中进行语义搜索

paper lit — Literature Management

paper lit — 文献管理

Add a paper (extracts PDF, splits text, creates embeddings)

添加论文（提取PDF内容、拆分文本、创建嵌入向量）

Title defaults to the PDF filename if not specified

若未指定标题，默认使用PDF文件名

List papers in a knowledge base

列出知识库中的论文

Show full details of a paper

查看论文的完整详情

Update paper metadata

更新论文元数据

-t, --title <title>

-t, --title <title>

--title-translation <translation>

--title-translation <translation>

-a, --author <author>

-a, --author <author>

--abstract <abstract>

--abstract <abstract>

--summary <summary>

--summary <summary>

--url <url>

--url <url>

--keywords <comma-separated-keywords>

--keywords <comma-separated-keywords>

Remove a paper (deletes DB record, PDF file; vectors remain in store)

删除论文（删除数据库记录和PDF文件；向量仍保留在存储中）

paper lit note — Literature Notes

paper lit note — 文献笔记

Common Workflows

常见工作流程

First-time setup

首次设置

Start a new research project

启动新研究项目

Manage paper metadata

管理论文元数据

Important Notes

重要提示

Global install (recommended — makes
`paper`
available everywhere)

全局安装（推荐——可在任意位置使用
`paper`
命令）