Substack API CLI

A robust, machine-friendly Go CLI for interacting with the Substack API. Built according to the go-api-cli-playbook standard, this tool allows you to fetch post listings, resolve user profiles, and download full article content directly as Markdown.

Features

• Profile Resolution: Automatically resolves Substack handles (e.g., openbookandeasypoint) to user IDs.
• Post Listings: Fetch paginated lists of posts for any author.
• Markdown Export: Download full article content. HTML is automatically and cleanly converted to Markdown (including images and links).
• Authentication Support: Bypass paywalls for newsletters you are subscribed to by supplying your Substack session cookie.
• Machine Readable: Supports --json flag for scripting and piping into tools like jq.

Installation

Build from source

Ensure you have Go installed, then run:

git clone https://github.com/leechael/substack-api.git
cd substack-api
make build

The binary will be available at ./bin/substack.

Configuration (Authentication)

For free, public posts, no authentication is required.

However, if you want to access paywalled posts that you have a subscription for, you need to provide your Substack authentication cookie.

Only the substack.sid cookie is required.

How to get your substack.sid:

1. Log in to Substack in your web browser.
2. Open Developer Tools (F12 or Right Click -> Inspect).
3. Go to the Application tab (Chrome/Edge) or Storage tab (Firefox/Safari).
4. Expand Cookies on the left sidebar and select https://substack.com.
5. Find the row where the Name is substack.sid and copy its Value.

How to use it:

You can pass the cookie via an environment variable (recommended) or a CLI flag.

Method 1: Environment Variable (Recommended)

export SUBSTACK_API_TOKEN="substack.sid=YOUR_SID_VALUE_HERE"

Method 2: CLI Flag

./bin/substack get 191858492 --token "substack.sid=YOUR_SID_VALUE_HERE"

Usage

1. List Posts

You can list posts using either a user's handle (from their URL) or their numeric user_id.

# List the 5 most recent posts
./bin/substack list openbookandeasypoint --limit 5

# Output in JSON format (great for scripting)
./bin/substack list openbookandeasypoint --limit 1 --json | jq .

Pagination: If a user has more posts than the limit, the output will include a Next cursor. You can pass this to the --cursor flag to get the next page.

./bin/substack list openbookandeasypoint --limit 12 --cursor "eyJzZXNzaW..."

2. Get Post Details (Markdown)

Retrieve a specific post by its ID (which you can find using the list command). The output is automatically converted to clean Markdown.

./bin/substack get 191858492

To save it directly to a file:

./bin/substack get 191858492 > post.md

Advanced Use Cases

Archiving an entire publication

Because the CLI supports JSON output, you can easily write a wrapper script (e.g., Python or Bash) to loop through pagination, extract post IDs, and fetch the Markdown for an author's entire archive. See the archive.py script pattern for inspiration.