Merge pull request #20 from NHagar/NHagar/add-cli

Add CLI with quickstart command

Author: NHagar

README.md

@@ -18,11 +18,38 @@ This library provides Python interfaces for interacting with Substack's unoffici
 # Using pip
 pip install substack-api
 
-# Using poetry
-poetry add substack-api
+# Using uv
+uv add substack-api
 ```
 
-## Usage Examples
+## Command-Line Interface
+
+The library includes a CLI for quick access from the terminal. All commands output JSON by default.
+
+```bash
+# Get the 5 newest posts from a newsletter
+substack newsletter posts https://example.substack.com --limit 5
+
+# Search for posts
+substack newsletter search https://example.substack.com "machine learning"
+
+# Get metadata for a specific post
+substack post metadata https://example.substack.com/p/my-post --pretty
+
+# Look up a user's subscriptions
+substack user subscriptions username
+
+# Browse categories
+substack categories
+substack category newsletters --name Technology
+
+# Run the quickstart guide for a full command reference
+substack quickstart
+```
+
+Use `--pretty` for human-readable output and `--cookies <path>` for authenticated access to paywalled content.
+
+## Python Usage Examples
 
 ### Working with Newsletters
 

docs/cli.md

@@ -0,0 +1,176 @@
+# Command-Line Interface
+
+The `substack` CLI provides terminal access to Substack newsletters, posts, users, and categories. All commands output JSON by default.
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--pretty` | Pretty-print JSON output with indentation |
+| `--cookies PATH` | Path to a cookies JSON file for authenticated access to paywalled content |
+
+## Newsletter Commands
+
+### Get posts
+
+```bash
+substack newsletter posts <url> [--sort new|top|pinned|community] [--limit N]
+```
+
+Returns a list of post URLs from the newsletter.
+
+```bash
+# Get the 5 newest posts
+substack newsletter posts https://example.substack.com --limit 5
+
+# Get top posts
+substack newsletter posts https://example.substack.com --sort top --limit 10
+```
+
+### Search posts
+
+```bash
+substack newsletter search <url> <query> [--limit N]
+```
+
+```bash
+substack newsletter search https://example.substack.com "machine learning" --limit 3
+```
+
+### Get podcasts
+
+```bash
+substack newsletter podcasts <url> [--limit N]
+```
+
+### Get recommendations
+
+```bash
+substack newsletter recs <url>
+```
+
+Returns URLs of newsletters recommended by the given newsletter.
+
+### Get authors
+
+```bash
+substack newsletter authors <url>
+```
+
+Returns usernames of the newsletter's authors.
+
+## Post Commands
+
+### Get metadata
+
+```bash
+substack post metadata <url>
+```
+
+Returns the full metadata dictionary for a post.
+
+```bash
+substack post metadata https://example.substack.com/p/my-post --pretty
+```
+
+### Get content
+
+```bash
+substack post content <url>
+```
+
+Returns the post URL and its HTML body content.
+
+### Check paywall status
+
+```bash
+substack post paywalled <url>
+```
+
+Returns whether the post is paywalled.
+
+## User Commands
+
+### Get user info
+
+```bash
+substack user info <username>
+```
+
+Returns the full user profile data.
+
+### Get subscriptions
+
+```bash
+substack user subscriptions <username>
+```
+
+Returns the list of newsletters the user is subscribed to.
+
+## Category Commands
+
+### List all categories
+
+```bash
+substack categories
+```
+
+Returns all available newsletter categories with their names and IDs.
+
+### Get newsletters in a category
+
+```bash
+substack category newsletters --name <name> [--metadata]
+substack category newsletters --id <id> [--metadata]
+```
+
+Returns newsletter URLs in the category. Add `--metadata` to get full newsletter metadata instead.
+
+```bash
+# By name
+substack category newsletters --name Technology
+
+# By ID with full metadata
+substack category newsletters --id 42 --metadata --pretty
+```
+
+## Other Commands
+
+### Resolve a renamed handle
+
+```bash
+substack resolve-handle <handle>
+```
+
+Checks if a Substack user handle has been renamed and returns the new handle.
+
+### Quickstart
+
+```bash
+substack quickstart
+```
+
+Prints a concise reference guide covering all CLI commands and options.
+
+### Version
+
+```bash
+substack version
+```
+
+## Authentication
+
+To access paywalled content from the CLI, pass `--cookies` before the command:
+
+```bash
+substack --cookies cookies.json post content https://example.substack.com/p/paid-post
+substack --cookies cookies.json newsletter posts https://example.substack.com
+```
+
+See the [Authentication Guide](authentication.md) for details on obtaining cookies.
+
+## Notes
+
+- API calls include a 2-second delay to be respectful to Substack's servers. Use `--limit` to avoid long waits on large newsletters.
+- All output is JSON. Pipe to `jq` for further processing, or use `--pretty` for readability.
+- The CLI can also be invoked as `python -m substack_api`.

docs/index.md

@@ -41,7 +41,8 @@ paywalled_content = authenticated_post.get_content()
 
 ## Features
 
-- Simple, intuitive API
+- Simple, intuitive Python API
+- Command-line interface for quick terminal access
 - Comprehensive access to Substack data
 - Pagination support for large collections
 - Automatic caching to minimize API calls

docs/installation.md

@@ -2,8 +2,8 @@
 
 ## Requirements
 
-- Python 3.7 or higher
-- pip (Python package installer)
+- Python 3.12 or higher
+- pip or uv (Python package installer)
 
 ## Install from PyPI
 
@@ -30,3 +30,13 @@ The library has minimal dependencies:
 
 These dependencies will be automatically installed when you install the package.
 
+## CLI
+
+Installing the package also installs the `substack` command-line tool:
+
+```bash
+substack --help
+substack quickstart
+```
+
+See the [CLI Guide](cli.md) for full documentation.

mkdocs.yml

@@ -52,6 +52,7 @@ plugins:
 nav:
   - Home: index.md
   - Installation: installation.md
+  - CLI: cli.md
   - User Guide: user-guide.md
   - Authentication: authentication.md
   - API Reference:

pyproject.toml

@@ -22,6 +22,9 @@ dev = [
     "ruff>=0.9.9",
 ]
 
+[project.scripts]
+substack = "substack_api.cli:main"
+
 [project.urls]
 "Homepage" = "https://github.com/nhagar/substack_api"
 "Bug Tracker" = "https://github.com/nhagar/substack_api/issues"

substack_api/__main__.py

@@ -0,0 +1,3 @@
+from substack_api.cli import main
+
+main()