shiori-cli

name	shiori-cli
description	Operate the shiori-cli tool to manage bookmarks/links in the Shiori read-later service. Use when the user wants to save, list, read/unread, or delete links via the shiori CLI, or when automating Shiori bookmark management from the command line.

shiori-cli

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

Prerequisites

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

export SHIORI_API_KEY="shk_..."

Optionally override the API endpoint:

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

Quick Start

# 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.

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.

Workflow

1. Check environment - Verify SHIORI_API_KEY is set. If not, instruct the user to set it.
2. Choose command - Pick from list, add, read, unread, delete based on intent.
3. Choose output mode - Use --json when parsing output programmatically; omit for human-readable plain text.
4. 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

Common Patterns

List then bulk-mark as read

# Get unread links as JSON, extract IDs, mark all as read
shiori list --read unread --json
shiori read --id "id1" --id "id2" --id "id3"

Save and immediately mark as read

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

Paginated listing

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.