scholarinboxcli 0.1.1

CLI for Scholar Inbox (authenticated web API)

scholarinboxcli

CLI for Scholar Inbox, for humans and agents alike.

Installation

pip install scholarinboxcli

Or with uv:

uv pip install scholarinboxcli

Or run directly with uvx (no install):

uvx scholarinboxcli auth login --url "<magic-link-url>"

Auth

# Log in with the magic-link URL from the web app
scholarinboxcli auth login --url "https://www.scholar-inbox.com/login?sha_key=...&date=MM-DD-YYYY"

# Check current session and user info
scholarinboxcli auth status

# Clear local session config
scholarinboxcli auth logout

Note: auth login extracts sha_key from the URL and authenticates via the API.

Config is stored at ~/.config/scholarinboxcli/config.json. You can override the API base with SCHOLAR_INBOX_API_BASE.

Command reference

Top-level commands:

• auth (login/status/logout)
• digest
• trending
• search
• semantic
• interactions
• bookmark (list/add/remove)
• collection (list/create/rename/delete/add/remove/papers/similar)
• conference (list/explore)

Run scholarinboxcli --help or scholarinboxcli <command> --help for full options.

Quickstart

# Fetch a daily digest by date (MM-DD-YYYY)
scholarinboxcli digest --date 01-30-2026 --json

# Trending papers (last 7 days)
scholarinboxcli trending --category ALL --days 7 --json

# Keyword search
scholarinboxcli search "transformers" --limit 5 --json

# Semantic search
scholarinboxcli semantic "graph neural networks" --limit 5 --json

# List your bookmarks
scholarinboxcli bookmark list --json

Collections

# List collections
scholarinboxcli collection list

# Expanded collection names (marks which collections are expanded server-side)
scholarinboxcli collection list --expanded

# Create, rename, delete
scholarinboxcli collection create "My Collection"

# Rename by ID (or name)
scholarinboxcli collection rename 10759 "New Name"

# Delete by ID (or name)
scholarinboxcli collection delete 10759

# Add/remove papers
scholarinboxcli collection add 10759 4559909
scholarinboxcli collection remove 10759 4559909

# Show papers in a collection
scholarinboxcli collection papers 10759

# Similar papers for one or more collections
scholarinboxcli collection similar 10759 12345

# You can also use collection names (case-insensitive). The CLI will
# automatically fetch collection ID mappings from the API when needed.
scholarinboxcli collection papers "AIAgents"
scholarinboxcli collection similar "AIAgents" "Benchmark"

Collection name matching is exact → prefix → contains. If multiple matches exist, the CLI reports ambiguity and shows candidate IDs.

Search

# Full-text keyword search
scholarinboxcli search "transformers" --limit 5

Semantic Search

# Semantic similarity search
scholarinboxcli semantic "graph neural networks" --limit 5

Other commands

# Daily digest view (MM-DD-YYYY)
scholarinboxcli digest --date 01-30-2026

# Trending papers by category
scholarinboxcli trending --category ALL --days 7

# Read/like/dislike interactions feed
scholarinboxcli interactions --type all

# List bookmarks
scholarinboxcli bookmark list

# List known conferences
scholarinboxcli conference list

# Explore conference indices
scholarinboxcli conference explore

Output modes

• TTY: Rich tables
• --json: pretty JSON
• Piped: pretty JSON (auto)

Examples for agents/scripting:

# Auto-JSON when piped
scholarinboxcli collection list | jq '.'

# Explicit JSON output
scholarinboxcli collection papers "AIAgents" --json

# JSON for automation (stable keys)
scholarinboxcli search "diffusion" --json

Tested (2026-02-01)

The following commands were exercised against the live API (with a valid magic-link login) to confirm behavior:

scholarinboxcli --help
scholarinboxcli auth status --json
scholarinboxcli digest --date 01-30-2026 --json
scholarinboxcli trending --category ALL --days 7 --json
scholarinboxcli search "transformers" --limit 5 --json
scholarinboxcli semantic "graph neural networks" --limit 5 --json
scholarinboxcli interactions --type all --json
scholarinboxcli bookmark list --json
scholarinboxcli bookmark add 3302478 --json
scholarinboxcli bookmark remove 3302478 --json
scholarinboxcli collection list --json
scholarinboxcli collection list --expanded --json
scholarinboxcli collection papers "AIAgents" --json
scholarinboxcli collection similar "AIAgents" --json
scholarinboxcli conference list --json
scholarinboxcli conference explore --json

Notes

• Some collection mutations (create/rename/delete/add/remove) rely on best-effort endpoints that may change on the service side. If a mutation fails, try again or use the web UI to validate the current behavior.
• Similar papers for collections uses the server endpoint used by the web UI. Results typically appear under digest_df in JSON responses.

Publish to PyPI

# 1) Build sdist + wheel
uv run --with build python -m build

# 2) Validate metadata/rendering
uvx twine check dist/*

# 3) (Optional) test publish first
uvx twine upload --repository testpypi dist/*

# 4) Publish to PyPI
uvx twine upload dist/*

If using an API token:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<your-pypi-token>

Automated publish is also configured via GitHub Actions:

• Workflow: .github/workflows/publish.yml
• Trigger: push a tag matching v* (for example v0.1.1)
• Auth: PyPI Trusted Publishing (OIDC)