Metadata-Version: 2.4
Name: scholarinboxcli
Version: 0.1.1
Summary: CLI for Scholar Inbox (authenticated web API)
License-Expression: MIT
License-File: LICENSE
Keywords: bibliography,cli,research,scholar
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# scholarinboxcli

CLI for Scholar Inbox, for humans and agents alike.

## Installation

```bash
pip install scholarinboxcli
```

Or with uv:

```bash
uv pip install scholarinboxcli
```

Or run directly with uvx (no install):

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

## Auth

```bash
# 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

```bash
# 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

```bash
# 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

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

## Semantic Search

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

## Other commands

```bash
# 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:

```bash
# 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:

```bash
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

```bash
# 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:

```bash
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)
