Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/buttondown/cli/llms.txt

Use this file to discover all available pages before exploring further.

​
Welcome to Buttondown CLI

Buttondown CLI is a powerful command-line tool that bridges the gap between Buttondown and your local development environment. Work with your newsletters using your favorite text editor, version control your content, and sync everything seamlessly with Buttondown.

​
What is Buttondown CLI?

Buttondown CLI enables you to:
  • Back up your content - Pull all your emails and media from Buttondown to your local machine
  • Work locally - Edit emails in your favorite editor using Markdown with frontmatter
  • Deploy changes - Push your local changes back to Buttondown with a single command
  • Sync media - Upload and download images seamlessly using the Buttondown API
  • Version control - Track your newsletter content with Git and collaborate with your team

Installation

Get started by installing Buttondown CLI via npm, yarn, pnpm, or bun

Quick Start

Follow a step-by-step guide to sync your first newsletter

Commands

Explore all available CLI commands and their options

Configuration

Learn how to configure your sync directory and settings

​
Key Features

​
Local-First Workflow

Edit your newsletters in Markdown format with YAML frontmatter. The CLI maintains a clean directory structure with separate folders for emails and media: 
my-newsletter/
├── .buttondown.json  # Sync configuration
├── emails/           # Your emails as Markdown files
│   ├── newsletter-issue-1.md
│   └── newsletter-issue-2.md
└── media/            # Images and media files
    ├── image1.png
    └── document.pdf

​
Seamless Sync

The CLI automatically tracks your content and media files, preventing duplicate uploads and ensuring consistency between your local files and Buttondown. All sync state is managed in .buttondown.json.

​
Markdown with Frontmatter

Your emails are stored as standard Markdown files with YAML frontmatter for metadata: 
---
subject: My Newsletter Issue #1
status: draft
email_type: public
slug: newsletter-issue-1
publish_date: 2025-04-27T09:00:00Z
---

# My Newsletter Issue #1

Hello subscribers! This is the content of my email...

​
Media Management

Upload images to Buttondown’s media storage and reference them in your emails. The CLI handles image URLs and maintains a mapping between local files and remote URLs.

​
Use Cases

Backup and Version Control: Keep your newsletter content safe with local backups and version control using Git
Team Collaboration: Work on newsletters with your team using familiar development workflows
Offline Editing: Draft and edit newsletters offline, then sync when you’re ready
Content Migration: Easily migrate content between Buttondown accounts or export for other purposes

​
Requirements

​
Getting Started

Ready to start? Head over to the Installation guide to set up Buttondown CLI, then follow the Quick Start guide to sync your first newsletter.