Your entire Substack, from the terminal.
Read posts. Publish notes. Automate engagement. Power AI agents.
Getting Started • CLI • TUI • MCP Server • Automations • API • Contributing
Substack has no public API. PostCLI fills that gap with a fast, local-first toolkit that puts your entire Substack workflow in the terminal, in a TUI, or behind an AI agent.
CLI Full command suite for posts, notes, comments, profiles, and engagement. Pipe-friendly | TUI Interactive terminal UI with 6 tabs, sub-views, keyboard shortcuts, mouse scroll, and thread navigation. | MCP Server 16 tools for Claude, GPT, and any MCP-compatible AI agent. Read, write, and engage, all through natural language. | Automations Like-back, auto-reply, auto-restack with SQLite-backed dedup engine. No cloud required. |
- Node.js 18+ (LTS recommended)
- Chrome/Chromium with an active Substack session (for auto cookie grab)
- macOS or Linux (Windows support tracked here)
npm install -g @postcli/substackPostCLI grabs session cookies directly from Chrome. Just be logged into Substack in your browser:
postcli-substack auth loginAlternative methods: email OTP or manual cookie paste. See the auth guide.
postcli-substack auth test# Connection successful. Logged in as @yourhandlepostcli-substack posts list # see your posts
postcli-substack notes publish "Hello!"# publish a note
postcli-substack tui # launch the TUIpostcli-substack posts list # your posts (all publications)
postcli-substack posts list --subdomain techblog # specific publication
postcli-substack posts get --slug my-latest-post # full post in markdown
postcli-substack notes list --limit 20 # recent notes
postcli-substack comments list 12345 # comments on a post
postcli-substack feed list --tab for-you # reader feed
postcli-substack profile me # your profile
postcli-substack profile get nicolascole77 # someone else's profilepostcli-substack notes publish "Hello world"# publish a note
postcli-substack notes publish "Something **bold**"# markdown support
postcli-substack notes reply 12345 "Great point"# reply to a note
postcli-substack comments add 12345 "Nice post!"# comment on a postpostcli-substack posts react 12345 # heart a post
postcli-substack notes react 67890 # heart a note
postcli-substack comments react 11111 # heart a comment
postcli-substack posts restack 12345 # restack a post
postcli-substack notes restack 67890 # restack a noteEvery command supports --json for piping and scripting:
postcli-substack posts list --json | jq '.[0].title'
postcli-substack notes list --json --limit 5 | jq '.[] | .id'postcli-substack tui
| Tab | What it shows |
|---|---|
| Notes | Your notes, following, and general feed with sub-tabs |
| Posts | Posts from your publications with mine/following/general |
| Comments | Thread view with parent and child context |
| Feed | Reader feed (for-you, subscribed, categories) |
| Auto | Automation rules and execution logs |
| Profile | Your profile and publication list |
| Key | Action |
|---|---|
tab | Switch between tabs |
1-3 | Switch sub-tabs (mine / following / general) |
up/down | Navigate items |
enter | Open thread / detail view |
r | Reply to note |
l | Like / heart |
s | Restack |
o | Open in browser |
q / esc | Back / quit |
Mouse scroll is supported for navigation.
Connect your Substack to Claude, GPT, or any AI agent via the Model Context Protocol.
postcli-substack --mcpAdd to .claude/settings.json:
{
"mcpServers": {
"substack": {
"command": "postcli-substack",
"args": ["--mcp"]
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"substack": {
"command": "postcli-substack",
"args": ["--mcp"]
}
}
}| Tool | Description |
|---|---|
test_connection | Test authentication |
get_own_profile | Your profile and publications |
get_profile | Profile by subdomain |
list_posts | List posts (all pubs or specific) |
get_post | Full post by slug |
get_post_by_id | Full post by numeric ID |
list_notes | Notes from feed |
list_comments | Comments on a post |
get_feed | Reader feed |
publish_note | Publish a new note |
reply_to_note | Reply to a note |
comment_on_post | Comment on a post |
react_to_post | Heart a post |
react_to_comment | Heart a comment/note |
restack_post | Restack a post |
restack_note | Restack a note |
Local, SQLite-backed automation engine with deduplication. Runs on your machine, no cloud needed.
# See available presets
postcli-substack auto presets
# Create from preset
postcli-substack auto create "like-back" --preset 1
# Run once
postcli-substack auto run 1
# Manage
postcli-substack auto list
postcli-substack auto toggle 1 # enable/disable
postcli-substack auto remove 1 # delete| # | Preset | Trigger | Action |
|---|---|---|---|
| 1 | Like back | Someone likes your note | Like their latest note |
| 2 | Auto-reply to likes | Someone likes your note | Reply with thank you |
| 3 | Auto-restack | New note from a handle | Restack it |
| 4 | Follow back | New follower | Follow them back |
Custom automations can combine any trigger + action. See the automations guide.
Use the client in your own Node.js projects:
import{SubstackClient}from'@postcli/substack/client';constclient=newSubstackClient({token: process.env.SUBSTACK_TOKEN,publicationUrl: 'https://yourpub.substack.com',});// Readconstposts=awaitclient.listPosts({limit: 5});constnotes=awaitclient.listNotes({limit: 10});constprofile=awaitclient.ownProfile();// Writeawaitclient.publishNote('Published via API');awaitclient.replyToNote(12345,'Great note!');awaitclient.commentOnPost(67890,'Nice post');// Engageawaitclient.reactToPost(12345);awaitclient.reactToComment(67890);awaitclient.restackPost(12345);src/
cli/
commands/ # auth, posts, notes, comments, profile, social, auto
tui/ # Interactive terminal UI (React + Ink)
automations/ # SQLite-backed automation engine
formatters.ts # Output formatting (markdown, tables, colors)
chrome-cookies.ts # Chrome cookie extraction
lib/
substack.ts # SubstackClient (core API wrapper)
http.ts # HTTP client with throttling
models.ts # Domain models (Post, Note, Comment, Profile)
types.ts # Substack API response types
mcp/
index.ts # MCP stdio server
tools.ts # 16 tool definitions + handlers
client.ts # Client initialization & config
plugin.ts # Plugin registration for PostCLI ecosystem
Track progress and vote on features via GitHub Issues.
- Read posts, notes, comments, feed
- Publish notes, reply, comment on posts
- React (heart) and restack
- Interactive TUI with 6 tabs
- MCP Server for AI agents (16 tools)
- Automation engine with presets
- Thread view with parent + child context
- Chrome cookie auto-grab
- Profile feed (your activity)
- Publish full posts (draft + publish)
- Analytics dashboard
- Multi-account support
- Scheduled automations (daemon)
- Windows support
- Search posts and notes
- Subscriber management
- Notification feed
Contributions are welcome. Here's how to get started:
git clone https://github.com/postcli/substack.git
cd substack
npm install
npm run build
npm test# Run CLI in dev mode
npm run cli -- notes list
# Run MCP with inspector
npm run dev:mcp
# Run tests
npm test- Open an issue first to discuss the change you'd like to make
- Fork the repo and create a branch from
main - Write tests for new functionality
- Run
npm testandnpm run buildbefore submitting - Keep PRs focused on a single change
Looking for something to work on? Check issues labeled good first issue or help wanted.
PostCLI auto-grabs session cookies from Chrome. You must be logged into Substack in your browser.
postcli-substack auth loginThree auth methods:
| Method | Command | How it works |
|---|---|---|
| Chrome grab (default) | auth login | Reads cookies directly from Chrome's SQLite DB |
| Email OTP | auth login --subdomain yourpub | Sends a magic link to your email |
| Manual paste | auth setup | Paste cookies from Chrome DevTools |
Credentials are stored at ~/.config/postcli/.env with 0600 permissions (owner-only read/write).
This is an unofficial tool, not affiliated with or endorsed by Substack. It interacts with undocumented APIs that may change without notice. Use at your own risk.