Add posts, drafts, scheduling and Notes

Author: dynabe

create_draft.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Turn a Markdown file into a Substack draft, keeping headings, bold, links and lists.
+
+    python create_draft.py --file essay.md
+    python create_draft.py --file essay.md --audience only_paid
+
+The first "# " heading becomes the title and a "## " or _italic_ line right
+under it the subtitle. Images must be URLs; local paths are reported, not
+uploaded. Nothing is sent: schedule it with schedule_post.py or open the edit link.
+"""
+import argparse
+import json
+import re
+import sys
+
+from cotlet_client import call, read_markdown, run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--file", required=True, help="Markdown file")
+    parser.add_argument("--title", help="Override the title taken from the file")
+    parser.add_argument("--subtitle", help="Override the subtitle taken from the file")
+    parser.add_argument("--audience", choices=["everyone", "only_paid", "founding"], default="everyone")
+    args = parser.parse_args()
+
+    title, subtitle, body = read_markdown(args.file)
+    local = [src for src in re.findall(r"!\[[^\]]*\]\(([^)\s]+)", body) if not src.startswith(("http://", "https://"))]
+    for src in local:
+        print(f"Warning: image {src} is a local path; replace it with a hosted URL", file=sys.stderr)
+
+    draft = call("create_draft", {
+        "title": args.title or title,
+        "subtitle": args.subtitle or subtitle,
+        "body_markdown": body,
+        "audience": args.audience,
+    })
+    print(json.dumps(draft, indent=2))
+
+
+if __name__ == "__main__":
+    run(main)

export_posts.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Export your Substack posts as Markdown files, one per post, including the paywalled part of your own posts.
+
+    python export_posts.py --dir posts
+    python export_posts.py --dir posts --since 2026-01-01
+    python export_posts.py --dir drafts --status draft
+
+Each file is named after the post URL slug and starts with the title and subtitle.
+Images stay as URLs. Works for the publication your Substack account publishes to.
+"""
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from cotlet_client import call, paginate, run
+
+
+def slug(post: dict) -> str:
+    source = (post.get("url") or "").rstrip("/").rsplit("/", 1)[-1] or post.get("title") or post["post_id"]
+    return re.sub(r"[^a-z0-9]+", "-", source.lower()).strip("-") or post["post_id"]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--dir", required=True, help="Folder to write the .md files to")
+    parser.add_argument("--status", choices=["published", "draft", "scheduled"], default="published")
+    parser.add_argument("--since", help="Only posts published on or after this date (YYYY-MM-DD)")
+    parser.add_argument("--max", type=int, help="Stop after this many posts")
+    args = parser.parse_args()
+
+    out = Path(args.dir)
+    out.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for item in paginate("list_posts", {"status": args.status, "limit": 50}, "posts", args.max):
+        if args.since and item.get("published_at") and item["published_at"][:10] < args.since:
+            break  # newest first: everything after this is older
+        post = call("get_post", {"post_id": item["post_id"]})
+        head = f"# {post['title']}\n\n" + (f"_{post['subtitle']}_\n\n" if post.get("subtitle") else "")
+        path = out / f"{slug(post)}.md"
+        path.write_text(head + post.get("body_markdown", "") + "\n", encoding="utf-8")
+        print(f"  {path}", file=sys.stderr)
+        count += 1
+    print(f"Exported {count} posts to {out}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    run(main)

get_post.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Get one Substack post with its full body as Markdown, audience, URL and dates.
+
+    python get_post.py --post-id 148213977
+    python get_post.py --post-id 148213977 --markdown > the-quiet-launch.md
+"""
+import argparse
+import json
+
+from cotlet_client import call, run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--post-id", required=True, help="Post ID from list_posts.py")
+    parser.add_argument("--markdown", action="store_true", help="Print only the post as Markdown")
+    args = parser.parse_args()
+
+    post = call("get_post", {"post_id": args.post_id})
+    if args.markdown:
+        print(f"# {post['title']}\n")
+        if post.get("subtitle"):
+            print(f"_{post['subtitle']}_\n")
+        print(post.get("body_markdown", ""))
+    else:
+        print(json.dumps(post, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    run(main)

list_posts.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""List the posts of your Substack publication: published, drafts or scheduled, newest first.
+
+    python list_posts.py
+    python list_posts.py --status scheduled
+    python list_posts.py --status draft --out drafts.csv
+
+Scheduled posts include their publish time. Pages are followed automatically.
+"""
+import argparse
+
+from cotlet_client import paginate, run, write_rows
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--status", choices=["published", "draft", "scheduled"], default="published")
+    parser.add_argument("--max", type=int, help="Stop after this many posts")
+    parser.add_argument("--out", help="Save to .csv or .json instead of printing")
+    args = parser.parse_args()
+
+    rows = list(paginate("list_posts", {"status": args.status, "limit": 50}, "posts", args.max))
+    write_rows(rows, args.out)
+
+
+if __name__ == "__main__":
+    run(main)

publish_note.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Post a Substack Note now or at a set time, optionally with a link card to one of your posts.
+
+    python publish_note.py --body "Tuesday's essay is out." --link-latest
+    python publish_note.py --body "Part two is coming." --link-post-id 148213977 --at 2026-10-14T12:00:00-04:00
+
+Notes are up to 1,000 characters and are not emailed to subscribers.
+"""
+import argparse
+import json
+
+from cotlet_client import call, run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--body", required=True, help="Note text, up to 1,000 characters")
+    link = parser.add_mutually_exclusive_group()
+    link.add_argument("--link-post-id", help="Attach this post as a card")
+    link.add_argument("--link-latest", action="store_true", help="Attach your latest published post")
+    parser.add_argument("--at", help="ISO 8601 time with offset. Omit to post now")
+    args = parser.parse_args()
+    if len(args.body) > 1000:
+        parser.error(f"Note is {len(args.body)} characters, the limit is 1,000")
+
+    post_id = args.link_post_id
+    if args.link_latest:
+        posts = call("list_posts", {"status": "published", "limit": 1}).get("posts", [])
+        post_id = posts[0]["post_id"] if posts else None
+
+    print(json.dumps(call("publish_note", {"body": args.body, "link_post_id": post_id, "publish_at": args.at}), indent=2))
+
+
+if __name__ == "__main__":
+    run(main)

publish_post.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Publish a Substack draft now, on the web and by email unless you pass --web-only.
+
+    python publish_post.py --post-id 148420031
+    python publish_post.py --post-id 148420031 --web-only
+
+A sent email cannot be recalled. By default Cotlet asks you to confirm first.
+"""
+import argparse
+import json
+
+from cotlet_client import call, run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--post-id", required=True, help="Draft ID")
+    parser.add_argument("--web-only", action="store_true", help="Publish on the web without emailing subscribers")
+    args = parser.parse_args()
+
+    print(json.dumps(call("publish_post", {"post_id": args.post_id, "send_email": not args.web_only}), indent=2))
+
+
+if __name__ == "__main__":
+    run(main)

schedule_post.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Schedule a Substack post for a set time, on the web and by email, from a draft or straight from a Markdown file.
+
+    python schedule_post.py --post-id 148420031 --at 2026-10-14T08:00:00-04:00
+    python schedule_post.py --file essay.md --at 2026-10-14T08:00:00-04:00 --note "New essay: why we stopped shipping on Fridays"
+    python schedule_post.py --post-id 148420031 --at 2026-10-17T07:00:00+01:00 --web-only
+
+Always give the time with its offset. Substack schedules at most three months
+ahead and emails a post only once. The script stops if another post is already
+scheduled for the same day, unless you pass --allow-same-day.
+"""
+import argparse
+import json
+from datetime import datetime, timedelta, timezone
+
+from cotlet_client import call, paginate, read_markdown, run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument("--post-id", help="Draft ID")
+    src.add_argument("--file", help="Create the draft from this Markdown file first")
+    parser.add_argument("--at", required=True, help="ISO 8601 time with offset, e.g. 2026-10-14T08:00:00-04:00")
+    parser.add_argument("--audience", choices=["everyone", "only_paid", "founding"], default="everyone", help="With --file")
+    parser.add_argument("--web-only", action="store_true", help="Publish on the web without emailing subscribers")
+    parser.add_argument("--note", help="Also schedule a Note with a link card to the post")
+    parser.add_argument("--note-delay", type=float, default=4, help="Hours after the post for the Note. Default: 4")
+    parser.add_argument("--allow-same-day", action="store_true")
+    args = parser.parse_args()
+
+    at = datetime.fromisoformat(args.at)
+    if at.tzinfo is None:
+        parser.error("--at needs a time zone offset, e.g. -04:00 or +01:00")
+    now = datetime.now(timezone.utc)
+    if at <= now:
+        parser.error("--at is in the past")
+    if at > now + timedelta(days=92):
+        parser.error("Substack schedules at most three months ahead")
+
+    if not args.allow_same_day:
+        for post in paginate("list_posts", {"status": "scheduled", "limit": 50}, "posts"):
+            when = post.get("publish_at") or post.get("published_at")
+            if when and datetime.fromisoformat(when.replace("Z", "+00:00")).astimezone(at.tzinfo).date() == at.date():
+                parser.exit(1, f"Already scheduled that day: {post['title']} ({post['post_id']}). Use --allow-same-day.\n")
+
+    post_id = args.post_id
+    if args.file:
+        title, subtitle, body = read_markdown(args.file)
+        post_id = call("create_draft", {"title": title, "subtitle": subtitle, "body_markdown": body, "audience": args.audience})["post_id"]
+
+    scheduled = call("schedule_post", {"post_id": post_id, "publish_at": at.isoformat(), "send_email": not args.web_only})
+    print(json.dumps(scheduled, indent=2))
+    if args.note:
+        note_at = (at + timedelta(hours=args.note_delay)).isoformat()
+        print(json.dumps(call("publish_note", {"body": args.note, "link_post_id": post_id, "publish_at": note_at}), indent=2))
+
+
+if __name__ == "__main__":
+    run(main)

update_draft.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Change the title, subtitle, body or audience of a Substack draft. Published posts are not changed.
+
+    python update_draft.py --post-id 148420031 --file essay.md
+    python update_draft.py --post-id 148420031 --title "Notes on pricing, part 2"
+"""
+import argparse
+import json
+
+from cotlet_client import call, read_markdown, run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--post-id", required=True, help="Draft ID from create_draft.py or list_posts.py --status draft")
+    parser.add_argument("--file", help="Replace title, subtitle and body from this Markdown file")
+    parser.add_argument("--title")
+    parser.add_argument("--subtitle")
+    parser.add_argument("--audience", choices=["everyone", "only_paid", "founding"])
+    args = parser.parse_args()
+
+    fields = {}
+    if args.file:
+        title, subtitle, body = read_markdown(args.file)
+        fields.update({"title": title, "subtitle": subtitle, "body_markdown": body})
+    fields.update({k: v for k, v in {"title": args.title, "subtitle": args.subtitle, "audience": args.audience}.items() if v})
+    fields = {k: v for k, v in fields.items() if v is not None}
+    if not fields:
+        parser.error("pass --file or at least one of --title, --subtitle, --audience")
+
+    print(json.dumps(call("update_draft", {"post_id": args.post_id, "fields": fields}), indent=2))
+
+
+if __name__ == "__main__":
+    run(main)