Buttondown CLI

flowchart
  laptop[Local machine]
  buttondown_cli[Buttondown CLI]
  buttondown_api[Buttondown API]
  laptop -->|"buttondown pull"| buttondown_cli
  buttondown_cli -->|"GET /emails"| buttondown_api
  buttondown_api -->|"200 OK"| buttondown_cli
  buttondown_cli -->|"./buttondown/emails/hello.md"| laptop

The Buttondown CLI (Command Line Interface) is a powerful tool that lets you manage your newsletter content from your local machine. It enables workflows like editing newsletters in your preferred text editor, backing up your content, and syncing media files.

Install the CLI globally using npm:

npm install -g @buttondown/cli

Or use it with npx without installing:

npx @buttondown/cli

The CLI provides several capabilities:

• Work offline with your newsletter content
• Edit in your favorite editor using Markdown
• Version control your newsletters with Git or other tools
• Sync content bidirectionally between your computer and Buttondown
• Manage media files like images and attachments
• Automate workflows with scripts

Before using the CLI, you need to authenticate with your Buttondown API key:

buttondown login

You'll be prompted to enter your API key, which you can find in your Buttondown settings.

To download your newsletters from Buttondown:

buttondown pull

This creates a ./buttondown directory with all your content.

Create a new draft:

buttondown create --title="My Newsletter Issue #1"

Then edit the created Markdown file with your preferred editor.

When you're ready to save your changes back to Buttondown:

buttondown push

Important: buttondown push doesn't publish emails with the status: draft field, which is the default status for new emails. See the Publishing Behavior section below for details on how to actually send your emails.

When you run buttondown push, it syncs your content to Buttondown maintaining the status in the frontmatter. Here's how publishing works:

The status field in your email's frontmatter determines what happens:

More information on statuses is available in the API reference.

The CLI creates this structure in your local folder:

Each newsletter is stored as a Markdown file with YAML frontmatter:

---
id: email-id
subject: My Newsletter Issue #1
status: draft
email_type: public
slug: newsletter-issue-1
publish_date: 2023-04-27T09:00:00Z
created: 2023-04-25T15:32:18Z
modified: 2023-04-26T10:45:22Z
description: A brief description of this newsletter issue for SEO and archives
image: https://placecats.com/1200/630
attachments:
  - attachment-id-1
  - attachment-id-2
---

# My Newsletter Issue #1

Hello subscribers!

This is the content of my email...

When creating emails via the CLI, only one field is truly required:

All other fields are optional and have sensible defaults:

• Maximum length: 1000 characters
• XSS validation: Subject is validated against XSS attacks
• Required: Cannot be empty when creating via API

• Format: Accepts HTML or Markdown
• Null characters: Not allowed in body content
• XSS validation: Body is validated against XSS attacks
• Default: Empty string if not provided

• Format: Must be URL-safe (validated with Django's validate_slug)
• Maximum length: 100 characters
• Uniqueness: Must be unique within the newsletter
• Auto-generation: Generated from subject if not provided

---
subject: "Newsletter #42: The Ultimate Question"
email_type: public
status: draft
slug: newsletter-42-ultimate-question
description: "Our 42nd newsletter covering the ultimate question of life, the universe, and everything"
---

# Newsletter #42: The Ultimate Question

Welcome to our 42nd newsletter...

---
subject: "Weekly Digest - January 17, 2024"
email_type: public
status: scheduled
publish_date: 2024-01-17T15:00:00.000Z
---

# Weekly Digest

This week's highlights...

---
subject: "Premium Analysis: Market Trends"
email_type: premium
status: about_to_send
description: "Deep dive analysis available only to premium subscribers"
---

# Premium Analysis: Market Trends

Dear premium subscribers...

# Create a directory for your newsletter
mkdir my-newsletter
cd my-newsletter

# Pull all your content from Buttondown
buttondown pull

# Pull latest changes
buttondown pull

# Create a new draft
buttondown create --title="This Week's Update"

# Edit the file in your editor
# Push to save as draft
buttondown push

# When ready to send, edit frontmatter to set status: scheduled
# Then push again to schedule the email
buttondown push

1. Add images to the media/ directory
2. Reference them in your Markdown:

![My Image](../media/my-image.png)

1. When you buttondown push, the CLI uploads the images and updates the URLs

mkdir buttondown-backup
cd buttondown-backup
buttondown pull

Consider adding this to a scheduled task for regular backups.

You can work with different newsletters using different directories:

buttondown pull --directory=./newsletter1
buttondown pull --directory=./newsletter2

# Initialize a Git repository
git init

# Pull content from Buttondown
buttondown pull

# Add and commit the files
git add .
git commit -m "Initial import from Buttondown"

Create a script like publish.sh:

#!/bin/bash
# Pull latest changes
buttondown pull

# Create a new draft with today's date
TITLE="Newsletter $(date +%Y-%m-%d)"
buttondown create --title="$TITLE"

# Open in your editor
code ./buttondown/emails/

Make it executable with chmod +x publish.sh

If you encounter authentication errors:

buttondown logout
buttondown login

If you've modified the same email both locally and on Buttondown:

1. Back up your local changes: cp -r ./buttondown ./buttondown-backup
2. Pull fresh content: buttondown pull --force
3. Manually merge the differences
4. Push the resolved content: buttondown push

The CLI provides specific error messages for common issues:

• Missing title: Error: --title is required for the create command
• Invalid format: Skipping [file]: Invalid format (missing frontmatter)
• Upload failures: Failed to upload image [filename]: [error message]
• API errors: Failed to create email: [error details]

For more information, contact Buttondown support.