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

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.