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
attachments:
  - attachment-id-1
  - attachment-id-2
---

# My Newsletter Issue #1

Hello subscribers!

This is the content of my email...

# 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

For more information, contact Buttondown support.