shiori-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shiori-cli

Unofficial CLI client for Shiori, a read-later / bookmark service.

这是Shiori（一款稍后阅读/书签服务，官网：https://www.shiori.sh/）的非官方CLI客户端。

Prerequisites

前置条件

Ensure

SHIORI_API_KEY

is set before running any command. The CLI refuses to run without it.

bash

export SHIORI_API_KEY="shk_..."

Optionally override the API endpoint:

bash

export SHIORI_API_BASE_URL="https://custom.host"

运行任何命令前请确保已设置

SHIORI_API_KEY

，否则CLI将无法运行。

bash

export SHIORI_API_KEY="shk_..."

（可选）覆盖API端点：

bash

export SHIORI_API_BASE_URL="https://custom.host"

Quick Start

快速开始

bash

undefined

bash

undefined

List unread links

列出未读链接

shiori list --read unread

Save a new link

保存新链接

shiori add "https://example.com/article"

Mark as read

标记为已读

shiori read --id "link-id"

Delete

删除链接

shiori delete "link-id"


Append `--json` to any command for machine-readable JSON output.

shiori delete "link-id"


在任意命令后添加`--json`参数可获取机器可读的JSON格式输出。

Command Overview

命令概览

Command	Purpose	Key args
`list`	List saved links	`--limit` , `--offset` , `--read` , `--sort`
`add <url>`	Save a new link	`--title` , `--read`
`read`	Mark links as read	`--id` (repeatable)
`unread`	Mark links as unread	`--id` (repeatable)
`delete <id>`	Delete a link	positional `id`

For full option details, default values, and output format specs, see references/cli-reference.md.

命令	用途	关键参数
`list`	列出已保存的链接	`--limit` , `--offset` , `--read` , `--sort`
`add <url>`	保存新链接	`--title` , `--read`
`read`	将链接标记为已读	`--id` （可重复使用）
`unread`	将链接标记为未读	`--id` （可重复使用）
`delete <id>`	删除链接	位置参数 `id`

如需了解完整的选项详情、默认值和输出格式规范，请查看references/cli-reference.md。

Workflow

工作流程

Check environment - Verify
```
SHIORI_API_KEY
```
is set. If not, instruct the user to set it.
Choose command - Pick from
```
list
```
,
```
add
```
,
```
read
```
,
```
unread
```
,
```
delete
```
based on intent.
Choose output mode - Use
```
--json
```
when parsing output programmatically; omit for human-readable plain text.
Handle errors - Check stderr and exit code. Common issues:
- ```
MISSING_API_KEY
```
  : API key not configured
- ```
UNAUTHORIZED
```
  : Invalid API key
- ```
RATE_LIMITED
```
  : Back off and retry (the CLI auto-retries up to 2 times)
- ```
NETWORK_ERROR
```
  : Check connectivity

检查环境 - 确认已设置
```
SHIORI_API_KEY
```
，若未设置则指导用户进行配置。
选择命令 - 根据需求从
```
list
```
、
```
add
```
、
```
read
```
、
```
unread
```
、
```
delete
```
中选择对应命令。
选择输出模式 - 若需通过程序解析输出，使用
```
--json
```
参数；若供人类阅读则省略该参数。
错误处理 - 检查标准错误输出和退出码。常见问题：
- ```
MISSING_API_KEY
```
  ：未配置API密钥
- ```
UNAUTHORIZED
```
  ：API密钥无效
- ```
RATE_LIMITED
```
  ：请等待后重试（CLI会自动重试最多2次）
- ```
NETWORK_ERROR
```
  ：检查网络连接

Common Patterns

常见使用模式

List then bulk-mark as read

列出后批量标记为已读

bash

undefined

bash

undefined

Get unread links as JSON, extract IDs, mark all as read

获取未读链接的JSON格式输出，提取ID，然后标记全部为已读

shiori list --read unread --json shiori read --id "id1" --id "id2" --id "id3"

undefined

shiori list --read unread --json shiori read --id "id1" --id "id2" --id "id3"

undefined

Save and immediately mark as read

保存链接并立即标记为已读

bash

shiori add "https://example.com" --read

bash

shiori add "https://example.com" --read

Paginated listing

分页列出链接

bash

shiori list --limit 20 --offset 0
shiori list --limit 20 --offset 20

bash

shiori list --limit 20 --offset 0
shiori list --limit 20 --offset 20

Error Handling Reference

错误处理参考

See references/cli-reference.md for the full error code table and output format specifications.

完整的错误码表格和输出格式规范请查看references/cli-reference.md。