substack-api 1.1.3__tar.gz → 1.2.0__tar.gz

{substack_api-1.1.3 → substack_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substack-api
-Version: 1.1.3
+Version: 1.2.0
 Summary: Unofficial wrapper for the Substack API
 Project-URL: Homepage, https://github.com/nhagar/substack_api
 Project-URL: Bug Tracker, https://github.com/nhagar/substack_api/issues
@@ -31,11 +31,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
 

{substack_api-1.1.3 → substack_api-1.2.0}/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
 

substack_api-1.2.0/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`.

{substack_api-1.1.3 → substack_api-1.2.0}/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

{substack_api-1.1.3 → substack_api-1.2.0}/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.

{substack_api-1.1.3 → substack_api-1.2.0}/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:

{substack_api-1.1.3 → substack_api-1.2.0}/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-1.2.0/substack_api/__main__.py

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

substack_api-1.2.0/substack_api/cli.py

@@ -0,0 +1,301 @@
+"""Command-line interface for substack_api."""
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from substack_api import (
+    Category,
+    Newsletter,
+    Post,
+    SubstackAuth,
+    User,
+    __version__,
+    list_all_categories,
+    resolve_handle_redirect,
+)
+
+QUICKSTART_TEXT = """\
+substack — CLI for reading Substack newsletters, posts, and user profiles.
+
+All output is JSON by default. Add --pretty for human-readable formatting.
+Use --cookies <path> to authenticate for paywalled content.
+
+COMMANDS
+========
+
+Newsletter:
+  substack newsletter posts <url> [--sort new|top|pinned|community] [--limit N]
+  substack newsletter search <url> <query> [--limit N]
+  substack newsletter podcasts <url> [--limit N]
+  substack newsletter recs <url>
+  substack newsletter authors <url>
+
+Post:
+  substack post metadata <url>
+  substack post content <url>
+  substack post paywalled <url>
+
+User:
+  substack user info <username>
+  substack user subscriptions <username>
+
+Categories:
+  substack categories
+  substack category newsletters --name <name> [--metadata]
+  substack category newsletters --id <id> [--metadata]
+
+Other:
+  substack resolve-handle <handle>
+  substack version
+
+EXAMPLES
+========
+
+  # List the 5 newest posts from a newsletter
+  substack newsletter posts https://example.substack.com --limit 5
+
+  # Search for posts about a topic
+  substack newsletter search https://example.substack.com "machine learning"
+
+  # Get full metadata for a specific post
+  substack post metadata https://example.substack.com/p/my-post --pretty
+
+  # Check if a post is paywalled
+  substack post paywalled https://example.substack.com/p/my-post
+
+  # Get the HTML content of a post (with auth for paywalled content)
+  substack --cookies cookies.json post content https://example.substack.com/p/paid-post
+
+  # Look up a user's subscriptions
+  substack user subscriptions username
+
+  # Browse newsletter categories
+  substack categories
+  substack category newsletters --name Technology
+
+  # Resolve a renamed user handle
+  substack resolve-handle oldusername
+
+NOTES
+=====
+- API calls include a 2-second delay to be respectful to Substack's servers.
+- Use --limit to avoid long waits when fetching posts from large newsletters.
+- The cookies file should be a JSON file containing Substack session cookies.
+"""
+
+
+def _json_out(data: Any, pretty: bool = False) -> None:
+    """Print data as JSON to stdout."""
+    indent = 2 if pretty else None
+    json.dump(data, sys.stdout, indent=indent, default=str)
+    sys.stdout.write("\n")
+
+
+def _get_auth(cookies_path: str | None):
+    """Build auth object if cookies path provided."""
+    if cookies_path:
+        return SubstackAuth(cookies_path)
+    return None
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="substack",
+        description="CLI for the substack_api library",
+    )
+    parser.add_argument(
+        "--cookies", metavar="PATH", help="Path to cookies JSON file for auth"
+    )
+    parser.add_argument(
+        "--pretty", action="store_true", help="Pretty-print JSON output"
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # quickstart
+    subparsers.add_parser("quickstart", help="Print developer quickstart guide")
+
+    # version
+    subparsers.add_parser("version", help="Print version")
+
+    # --- newsletter ---
+    nl_parser = subparsers.add_parser("newsletter", help="Newsletter operations")
+    nl_sub = nl_parser.add_subparsers(dest="subcommand")
+
+    nl_posts = nl_sub.add_parser("posts", help="Get posts from a newsletter")
+    nl_posts.add_argument("url", help="Newsletter URL")
+    nl_posts.add_argument(
+        "--sort",
+        default="new",
+        choices=["new", "top", "pinned", "community"],
+        help="Sort order (default: new)",
+    )
+    nl_posts.add_argument("--limit", type=int, help="Max number of posts")
+
+    nl_search = nl_sub.add_parser("search", help="Search posts in a newsletter")
+    nl_search.add_argument("url", help="Newsletter URL")
+    nl_search.add_argument("query", help="Search query")
+    nl_search.add_argument("--limit", type=int, help="Max number of results")
+
+    nl_podcasts = nl_sub.add_parser("podcasts", help="Get podcasts from a newsletter")
+    nl_podcasts.add_argument("url", help="Newsletter URL")
+    nl_podcasts.add_argument("--limit", type=int, help="Max number of podcasts")
+
+    nl_recs = nl_sub.add_parser("recs", help="Get newsletter recommendations")
+    nl_recs.add_argument("url", help="Newsletter URL")
+
+    nl_authors = nl_sub.add_parser("authors", help="Get newsletter authors")
+    nl_authors.add_argument("url", help="Newsletter URL")
+
+    # --- post ---
+    post_parser = subparsers.add_parser("post", help="Post operations")
+    post_sub = post_parser.add_subparsers(dest="subcommand")
+
+    post_meta = post_sub.add_parser("metadata", help="Get post metadata")
+    post_meta.add_argument("url", help="Post URL")
+
+    post_content = post_sub.add_parser("content", help="Get post HTML content")
+    post_content.add_argument("url", help="Post URL")
+
+    post_pay = post_sub.add_parser("paywalled", help="Check if post is paywalled")
+    post_pay.add_argument("url", help="Post URL")
+
+    # --- user ---
+    user_parser = subparsers.add_parser("user", help="User operations")
+    user_sub = user_parser.add_subparsers(dest="subcommand")
+
+    user_info = user_sub.add_parser("info", help="Get user profile info")
+    user_info.add_argument("username", help="Substack username")
+
+    user_subs = user_sub.add_parser("subscriptions", help="Get user subscriptions")
+    user_subs.add_argument("username", help="Substack username")
+
+    # --- categories ---
+    subparsers.add_parser("categories", help="List all categories")
+
+    # --- category ---
+    cat_parser = subparsers.add_parser("category", help="Category operations")
+    cat_sub = cat_parser.add_subparsers(dest="subcommand")
+
+    cat_nl = cat_sub.add_parser("newsletters", help="Get newsletters in a category")
+    cat_nl_group = cat_nl.add_mutually_exclusive_group(required=True)
+    cat_nl_group.add_argument("--name", help="Category name")
+    cat_nl_group.add_argument("--id", type=int, help="Category ID")
+    cat_nl.add_argument(
+        "--metadata", action="store_true", help="Include full metadata"
+    )
+
+    # --- resolve-handle ---
+    rh = subparsers.add_parser("resolve-handle", help="Resolve a renamed handle")
+    rh.add_argument("handle", help="The handle to resolve")
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> None:
+    """Dispatch to the appropriate handler based on parsed args."""
+    pretty = args.pretty
+
+    if args.command == "quickstart":
+        print(QUICKSTART_TEXT)
+        return
+
+    if args.command == "version":
+        print(__version__)
+        return
+
+    if args.command == "newsletter":
+        if not args.subcommand:
+            print("Usage: substack newsletter {posts,search,podcasts,recs,authors}", file=sys.stderr)
+            sys.exit(1)
+
+        auth = _get_auth(args.cookies)
+        nl = Newsletter(args.url, auth=auth)
+
+        if args.subcommand == "posts":
+            posts = nl.get_posts(sorting=args.sort, limit=args.limit)
+            _json_out([{"url": p.url} for p in posts], pretty)
+        elif args.subcommand == "search":
+            posts = nl.search_posts(query=args.query, limit=args.limit)
+            _json_out([{"url": p.url} for p in posts], pretty)
+        elif args.subcommand == "podcasts":
+            posts = nl.get_podcasts(limit=args.limit)
+            _json_out([{"url": p.url} for p in posts], pretty)
+        elif args.subcommand == "recs":
+            recs = nl.get_recommendations()
+            _json_out([{"url": r.url} for r in recs], pretty)
+        elif args.subcommand == "authors":
+            authors = nl.get_authors()
+            _json_out([{"username": a.username} for a in authors], pretty)
+        return
+
+    if args.command == "post":
+        if not args.subcommand:
+            print("Usage: substack post {metadata,content,paywalled}", file=sys.stderr)
+            sys.exit(1)
+
+        auth = _get_auth(args.cookies)
+        post = Post(args.url, auth=auth)
+
+        if args.subcommand == "metadata":
+            _json_out(post.get_metadata(), pretty)
+        elif args.subcommand == "content":
+            _json_out({"url": post.url, "html": post.get_content()}, pretty)
+        elif args.subcommand == "paywalled":
+            _json_out({"url": post.url, "paywalled": post.is_paywalled()}, pretty)
+        return
+
+    if args.command == "user":
+        if not args.subcommand:
+            print("Usage: substack user {info,subscriptions}", file=sys.stderr)
+            sys.exit(1)
+
+        user = User(args.username)
+
+        if args.subcommand == "info":
+            _json_out(user.get_raw_data(), pretty)
+        elif args.subcommand == "subscriptions":
+            _json_out(user.get_subscriptions(), pretty)
+        return
+
+    if args.command == "categories":
+        cats = list_all_categories()
+        _json_out([{"name": name, "id": id} for name, id in cats], pretty)
+        return
+
+    if args.command == "category":
+        if not args.subcommand:
+            print("Usage: substack category {newsletters}", file=sys.stderr)
+            sys.exit(1)
+
+        cat = Category(name=args.name, id=args.id)
+
+        if args.subcommand == "newsletters":
+            if args.metadata:
+                _json_out(cat.get_newsletter_metadata(), pretty)
+            else:
+                _json_out(cat.get_newsletter_urls(), pretty)
+        return
+
+    if args.command == "resolve-handle":
+        result = resolve_handle_redirect(args.handle)
+        _json_out({"old_handle": args.handle, "new_handle": result}, pretty)
+        return
+
+
+def main() -> None:
+    """CLI entry point."""
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        _dispatch(args)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)

{substack_api-1.1.3 → substack_api-1.2.0}/substack_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substack-api
-Version: 1.1.3
+Version: 1.2.0
 Summary: Unofficial wrapper for the Substack API
 Project-URL: Homepage, https://github.com/nhagar/substack_api
 Project-URL: Bug Tracker, https://github.com/nhagar/substack_api/issues
@@ -31,11 +31,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
 

{substack_api-1.1.3 → substack_api-1.2.0}/substack_api.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ uv.lock
 .github/workflows/pull_request.yml
 .github/workflows/release.yml
 docs/authentication.md
+docs/cli.md
 docs/index.md
 docs/installation.md
 docs/user-guide.md
@@ -21,20 +22,24 @@ docs/api-reference/user.md
 docs/css/extra.css
 examples/usage_walkthrough.ipynb
 substack_api/__init__.py
+substack_api/__main__.py
 substack_api/auth.py
 substack_api/category.py
+substack_api/cli.py
 substack_api/newsletter.py
 substack_api/post.py
 substack_api/user.py
 substack_api.egg-info/PKG-INFO
 substack_api.egg-info/SOURCES.txt
 substack_api.egg-info/dependency_links.txt
+substack_api.egg-info/entry_points.txt
 substack_api.egg-info/requires.txt
 substack_api.egg-info/top_level.txt
 tests/__init__.py
 tests/conftest.py
 tests/test_auth.py
 tests/test_category.py
+tests/test_cli.py
 tests/test_newsletter.py
 tests/test_post.py
 tests/test_user.py

substack_api-1.2.0/substack_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+substack = substack_api.cli:main

substack_api-1.2.0/tests/test_cli.py

@@ -0,0 +1,453 @@
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from substack_api.cli import QUICKSTART_TEXT, _build_parser, main
+
+
+class TestBuildParser:
+    def test_newsletter_posts_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "posts", "https://example.substack.com", "--limit", "5"]
+        )
+        assert args.command == "newsletter"
+        assert args.subcommand == "posts"
+        assert args.url == "https://example.substack.com"
+        assert args.limit == 5
+
+    def test_newsletter_posts_sort(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "posts", "https://example.substack.com", "--sort", "top"]
+        )
+        assert args.sort == "top"
+
+    def test_newsletter_posts_default_sort(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "posts", "https://example.substack.com"]
+        )
+        assert args.sort == "new"
+
+    def test_newsletter_search_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "search", "https://example.substack.com", "machine learning"]
+        )
+        assert args.subcommand == "search"
+        assert args.query == "machine learning"
+
+    def test_newsletter_podcasts_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "podcasts", "https://example.substack.com", "--limit", "3"]
+        )
+        assert args.subcommand == "podcasts"
+        assert args.limit == 3
+
+    def test_newsletter_recs_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "recs", "https://example.substack.com"]
+        )
+        assert args.subcommand == "recs"
+
+    def test_newsletter_authors_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["newsletter", "authors", "https://example.substack.com"]
+        )
+        assert args.subcommand == "authors"
+
+    def test_post_metadata_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["post", "metadata", "https://example.substack.com/p/test"]
+        )
+        assert args.command == "post"
+        assert args.subcommand == "metadata"
+        assert args.url == "https://example.substack.com/p/test"
+
+    def test_post_content_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["post", "content", "https://example.substack.com/p/test"]
+        )
+        assert args.subcommand == "content"
+
+    def test_post_paywalled_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["post", "paywalled", "https://example.substack.com/p/test"]
+        )
+        assert args.subcommand == "paywalled"
+
+    def test_user_info_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(["user", "info", "testuser"])
+        assert args.command == "user"
+        assert args.subcommand == "info"
+        assert args.username == "testuser"
+
+    def test_user_subscriptions_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(["user", "subscriptions", "testuser"])
+        assert args.subcommand == "subscriptions"
+
+    def test_categories_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(["categories"])
+        assert args.command == "categories"
+
+    def test_category_newsletters_by_name(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["category", "newsletters", "--name", "Technology"]
+        )
+        assert args.command == "category"
+        assert args.subcommand == "newsletters"
+        assert args.name == "Technology"
+        assert args.id is None
+
+    def test_category_newsletters_by_id(self):
+        parser = _build_parser()
+        args = parser.parse_args(["category", "newsletters", "--id", "42"])
+        assert args.id == 42
+        assert args.name is None
+
+    def test_category_newsletters_metadata_flag(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["category", "newsletters", "--name", "Tech", "--metadata"]
+        )
+        assert args.metadata is True
+
+    def test_resolve_handle_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(["resolve-handle", "olduser"])
+        assert args.command == "resolve-handle"
+        assert args.handle == "olduser"
+
+    def test_global_cookies_option(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["--cookies", "my_cookies.json", "newsletter", "posts", "https://x.substack.com"]
+        )
+        assert args.cookies == "my_cookies.json"
+
+    def test_global_pretty_option(self):
+        parser = _build_parser()
+        args = parser.parse_args(
+            ["--pretty", "categories"]
+        )
+        assert args.pretty is True
+
+    def test_quickstart_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(["quickstart"])
+        assert args.command == "quickstart"
+
+    def test_version_args(self):
+        parser = _build_parser()
+        args = parser.parse_args(["version"])
+        assert args.command == "version"
+
+
+class TestQuickstart:
+    def test_quickstart_output(self, capsys):
+        with patch("sys.argv", ["substack", "quickstart"]):
+            main()
+        out = capsys.readouterr().out
+        assert "substack newsletter posts" in out
+        assert "substack post metadata" in out
+        assert "substack user info" in out
+        assert "substack categories" in out
+        assert "--cookies" in out
+        assert "--pretty" in out
+        assert "EXAMPLES" in out
+
+    def test_quickstart_text_contains_examples(self):
+        assert "substack newsletter search" in QUICKSTART_TEXT
+        assert "substack resolve-handle" in QUICKSTART_TEXT
+
+
+class TestVersion:
+    def test_version_output(self, capsys):
+        with patch("sys.argv", ["substack", "version"]):
+            main()
+        out = capsys.readouterr().out.strip()
+        assert len(out) > 0
+
+
+class TestNewsletterCommands:
+    @patch("substack_api.cli.Newsletter")
+    def test_posts_output(self, MockNewsletter, capsys):
+        mock_post = MagicMock()
+        mock_post.url = "https://example.substack.com/p/test"
+        MockNewsletter.return_value.get_posts.return_value = [mock_post]
+
+        with patch("sys.argv", ["substack", "newsletter", "posts", "https://example.substack.com"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == [{"url": "https://example.substack.com/p/test"}]
+        MockNewsletter.return_value.get_posts.assert_called_once_with(
+            sorting="new", limit=None
+        )
+
+    @patch("substack_api.cli.Newsletter")
+    def test_posts_with_sort_and_limit(self, MockNewsletter, capsys):
+        MockNewsletter.return_value.get_posts.return_value = []
+
+        with patch("sys.argv", ["substack", "newsletter", "posts", "https://x.substack.com", "--sort", "top", "--limit", "3"]):
+            main()
+
+        MockNewsletter.return_value.get_posts.assert_called_once_with(
+            sorting="top", limit=3
+        )
+
+    @patch("substack_api.cli.Newsletter")
+    def test_search_output(self, MockNewsletter, capsys):
+        mock_post = MagicMock()
+        mock_post.url = "https://example.substack.com/p/result"
+        MockNewsletter.return_value.search_posts.return_value = [mock_post]
+
+        with patch("sys.argv", ["substack", "newsletter", "search", "https://example.substack.com", "test query"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == [{"url": "https://example.substack.com/p/result"}]
+        MockNewsletter.return_value.search_posts.assert_called_once_with(
+            query="test query", limit=None
+        )
+
+    @patch("substack_api.cli.Newsletter")
+    def test_podcasts_output(self, MockNewsletter, capsys):
+        MockNewsletter.return_value.get_podcasts.return_value = []
+
+        with patch("sys.argv", ["substack", "newsletter", "podcasts", "https://x.substack.com"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == []
+
+    @patch("substack_api.cli.Newsletter")
+    def test_recs_output(self, MockNewsletter, capsys):
+        mock_nl = MagicMock()
+        mock_nl.url = "https://rec.substack.com"
+        MockNewsletter.return_value.get_recommendations.return_value = [mock_nl]
+
+        with patch("sys.argv", ["substack", "newsletter", "recs", "https://x.substack.com"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == [{"url": "https://rec.substack.com"}]
+
+    @patch("substack_api.cli.Newsletter")
+    def test_authors_output(self, MockNewsletter, capsys):
+        mock_user = MagicMock()
+        mock_user.username = "author1"
+        MockNewsletter.return_value.get_authors.return_value = [mock_user]
+
+        with patch("sys.argv", ["substack", "newsletter", "authors", "https://x.substack.com"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == [{"username": "author1"}]
+
+
+class TestPostCommands:
+    @patch("substack_api.cli.Post")
+    def test_metadata_output(self, MockPost, capsys):
+        MockPost.return_value.get_metadata.return_value = {
+            "title": "Test", "id": 123
+        }
+
+        with patch("sys.argv", ["substack", "post", "metadata", "https://x.substack.com/p/test"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == {"title": "Test", "id": 123}
+
+    @patch("substack_api.cli.Post")
+    def test_content_output(self, MockPost, capsys):
+        MockPost.return_value.url = "https://x.substack.com/p/test"
+        MockPost.return_value.get_content.return_value = "<p>Hello</p>"
+
+        with patch("sys.argv", ["substack", "post", "content", "https://x.substack.com/p/test"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == {"url": "https://x.substack.com/p/test", "html": "<p>Hello</p>"}
+
+    @patch("substack_api.cli.Post")
+    def test_paywalled_output(self, MockPost, capsys):
+        MockPost.return_value.url = "https://x.substack.com/p/test"
+        MockPost.return_value.is_paywalled.return_value = True
+
+        with patch("sys.argv", ["substack", "post", "paywalled", "https://x.substack.com/p/test"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == {"url": "https://x.substack.com/p/test", "paywalled": True}
+
+
+class TestUserCommands:
+    @patch("substack_api.cli.User")
+    def test_info_output(self, MockUser, capsys):
+        MockUser.return_value.get_raw_data.return_value = {
+            "id": 1, "name": "Test User"
+        }
+
+        with patch("sys.argv", ["substack", "user", "info", "testuser"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == {"id": 1, "name": "Test User"}
+
+    @patch("substack_api.cli.User")
+    def test_subscriptions_output(self, MockUser, capsys):
+        MockUser.return_value.get_subscriptions.return_value = [
+            {"publication_name": "Test", "domain": "test.substack.com"}
+        ]
+
+        with patch("sys.argv", ["substack", "user", "subscriptions", "testuser"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert len(data) == 1
+        assert data[0]["publication_name"] == "Test"
+
+
+class TestCategoryCommands:
+    @patch("substack_api.cli.list_all_categories")
+    def test_categories_output(self, mock_list, capsys):
+        mock_list.return_value = [("Technology", 1), ("Culture", 2)]
+
+        with patch("sys.argv", ["substack", "categories"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == [{"name": "Technology", "id": 1}, {"name": "Culture", "id": 2}]
+
+    @patch("substack_api.cli.Category")
+    def test_category_newsletters_urls(self, MockCategory, capsys):
+        MockCategory.return_value.get_newsletter_urls.return_value = [
+            "https://a.substack.com", "https://b.substack.com"
+        ]
+
+        with patch("sys.argv", ["substack", "category", "newsletters", "--name", "Tech"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == ["https://a.substack.com", "https://b.substack.com"]
+
+    @patch("substack_api.cli.Category")
+    def test_category_newsletters_metadata(self, MockCategory, capsys):
+        MockCategory.return_value.get_newsletter_metadata.return_value = [
+            {"name": "A", "url": "https://a.substack.com"}
+        ]
+
+        with patch("sys.argv", ["substack", "category", "newsletters", "--name", "Tech", "--metadata"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == [{"name": "A", "url": "https://a.substack.com"}]
+
+    @patch("substack_api.cli.Category")
+    def test_category_newsletters_by_id(self, MockCategory, capsys):
+        MockCategory.return_value.get_newsletter_urls.return_value = []
+
+        with patch("sys.argv", ["substack", "category", "newsletters", "--id", "42"]):
+            main()
+
+        MockCategory.assert_called_once_with(name=None, id=42)
+
+
+class TestResolveHandle:
+    @patch("substack_api.cli.resolve_handle_redirect")
+    def test_resolve_found(self, mock_resolve, capsys):
+        mock_resolve.return_value = "newuser"
+
+        with patch("sys.argv", ["substack", "resolve-handle", "olduser"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == {"old_handle": "olduser", "new_handle": "newuser"}
+
+    @patch("substack_api.cli.resolve_handle_redirect")
+    def test_resolve_not_found(self, mock_resolve, capsys):
+        mock_resolve.return_value = None
+
+        with patch("sys.argv", ["substack", "resolve-handle", "sameuser"]):
+            main()
+
+        data = json.loads(capsys.readouterr().out)
+        assert data == {"old_handle": "sameuser", "new_handle": None}
+
+
+class TestPrettyOutput:
+    @patch("substack_api.cli.list_all_categories")
+    def test_pretty_flag(self, mock_list, capsys):
+        mock_list.return_value = [("Tech", 1)]
+
+        with patch("sys.argv", ["substack", "--pretty", "categories"]):
+            main()
+
+        out = capsys.readouterr().out
+        # Pretty output has indentation
+        assert "  " in out
+
+
+class TestErrorHandling:
+    def test_no_command_shows_help(self, capsys):
+        with patch("sys.argv", ["substack"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 1
+
+    def test_newsletter_no_subcommand(self, capsys):
+        with patch("sys.argv", ["substack", "newsletter"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 1
+
+    def test_post_no_subcommand(self, capsys):
+        with patch("sys.argv", ["substack", "post"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 1
+
+    def test_user_no_subcommand(self, capsys):
+        with patch("sys.argv", ["substack", "user"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 1
+
+    @patch("substack_api.cli.Newsletter")
+    def test_api_error_exits_with_1(self, MockNewsletter, capsys):
+        MockNewsletter.return_value.get_posts.side_effect = Exception("API Error")
+
+        with patch("sys.argv", ["substack", "newsletter", "posts", "https://x.substack.com"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+            assert exc_info.value.code == 1
+
+        assert "Error" in capsys.readouterr().err
+
+
+class TestAuthIntegration:
+    @patch("substack_api.cli.Post")
+    @patch("substack_api.cli.SubstackAuth")
+    def test_cookies_passed_to_post(self, MockAuth, MockPost, capsys):
+        mock_auth = MagicMock()
+        MockAuth.return_value = mock_auth
+        MockPost.return_value.get_metadata.return_value = {"title": "Test"}
+
+        with patch("sys.argv", ["substack", "--cookies", "cookies.json", "post", "metadata", "https://x.substack.com/p/test"]):
+            main()
+
+        MockAuth.assert_called_once_with("cookies.json")
+        MockPost.assert_called_once_with("https://x.substack.com/p/test", auth=mock_auth)