shiori-cli

Prerequisites

SHIORI_API_KEY

export SHIORI_API_KEY="shk_..."

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"

--json

Command Overview

list

--limit

--offset

--read

--sort

add <url>

--title

--read

read

--id

unread

--id

delete <id>

id

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