Quick Start

Get up and running with Buttondown CLI in minutes

Quick Start

This guide will walk you through authenticating with Buttondown, pulling your content, making edits, and pushing changes back.

Step 1: Authenticate

1. Run the login command

   Start by authenticating with your Buttondown API key:

   buttondown login
   

   The CLI will prompt you to enter your API key interactively.

2. Enter your API key

   Paste your API key when prompted. You can find your API key in your Buttondown settings.

   Please enter your Buttondown API key:
   > your-api-key-here
   
3. Confirm authentication

   Once authenticated, you’ll see a success message:

   ✓ Successfully configured API key!
   

You can also provide your API key directly using the --api-key flag:

buttondown login --api-key=your-api-key

Updating Your API Key

If you need to change your API key, use the --force flag:

buttondown login --force

Step 2: Pull Your Content

1. Pull content from Buttondown

   Download all your emails and media files:

   buttondown pull
   

   By default, this creates a ./buttondown directory in your current location.

2. Review the downloaded content

   The CLI will show you what was synced:

   newsletter pulled: 1 updated, 0 created, 0 deleted, 0 failed
   emails pulled: 12 updated, 0 created, 0 deleted, 0 failed
   images pulled: 8 updated, 0 created, 0 deleted, 0 failed
   All content saved to: ./buttondown
   
3. Explore the directory structure

   Check out your local newsletter files:

   cd buttondown
   ls -la
   

   You’ll see:

   • .buttondown.json - Sync state and configuration
   • emails/ - Your newsletters as Markdown files
   • media/ - Downloaded images and attachments

You can specify a custom directory:

buttondown pull --directory=./my-newsletter

Step 3: Edit Your Content

1. Open an email file

   Navigate to the emails directory and open any .md file in your favorite editor:

   cd emails
   vim newsletter-issue-1.md  # or use any editor
   
2. Review the email format

   Your email will have YAML frontmatter followed by Markdown content:

   ---
   subject: My Newsletter Issue #1
   status: draft
   email_type: public
   slug: newsletter-issue-1
   publish_date: 2025-04-27T09:00:00Z
   created: 2025-04-25T15:32:18Z
   modified: 2025-04-26T10:45:22Z
   ---
   
   # My Newsletter Issue #1
   
   Hello subscribers!
   
   This is the content of my email...
   
3. Make your changes

   Edit the content, subject, or any metadata you want to update. Save the file when you’re done.

Don’t modify the id field in the frontmatter - this is used to match your local file with the remote email on Buttondown.

Step 4: Create a New Email (Optional)

You can create new draft emails locally:

buttondown create --title="My New Newsletter" --directory=./buttondown

This creates a new Markdown file with the proper frontmatter structure:

---
subject: My New Newsletter
status: draft
email_type: public
slug: my-new-newsletter
created: 2026-02-28T10:30:00Z
modified: 2026-02-28T10:30:00Z
---

Write your email content here...

Step 5: Add Media

1. Add images to the media folder

   Copy any images you want to use into the media/ directory:

   cp ~/Downloads/my-image.png buttondown/media/
   
2. Reference images in your emails

   After pushing (next step), images are uploaded to Buttondown. You can then reference them using either:

   • Relative paths: ![Alt text](../media/my-image.png)
   • Absolute URLs: ![Alt text](https://buttondown.s3.amazonaws.com/images/...)

Step 6: Push Your Changes

1. Push to Buttondown

   Upload your changes back to Buttondown:

   buttondown push
   
2. Review the sync results

   The CLI shows what was uploaded:

   newsletter pushed: 0 updated, 0 created, 0 deleted, 0 failed
   emails pushed: 2 updated, 1 created, 0 deleted, 0 failed
   images pushed: 1 updated, 0 created, 0 deleted, 0 failed
   
3. Verify on Buttondown

   Log in to your Buttondown dashboard to see your updated content.

The push command is smart - it only uploads files that have changed since the last sync.

Common Workflows

Version Control with Git

Track your newsletter content with Git:

cd buttondown
git init
git add .
git commit -m "Initial newsletter backup"

Regular Backups

Set up a cron job or scheduled task to automatically pull your content:

# Add to crontab (daily at 2am)
0 2 * * * cd /path/to/buttondown && buttondown pull

Team Collaboration

1. One team member pulls content: buttondown pull
2. Commit to Git: git add . && git commit -m "Update newsletter"
3. Push to remote: git push origin main
4. Other team members pull from Git: git pull
5. When ready, push to Buttondown: buttondown push

Next Steps

Now that you’ve completed the quick start:

Explore Commands

Learn about all available CLI commands and options

Configuration

Customize your sync settings and directory structure

Email Format

Deep dive into the email Markdown format and frontmatter

Working with Media

Learn how to manage images and media files