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.

The Buttondown CLI creates a well-organized directory structure to manage your newsletter content locally.

​
Directory Overview

When you run buttondown pull, the CLI creates the following structure: 
my-newsletter/
├── .buttondown.json      # Sync state and configuration
├── emails/               # Newsletter emails as Markdown files
│   ├── welcome-email.md
│   ├── issue-001.md
│   └── issue-002.md
├── media/                # Images and media files
│   ├── header-image.png
│   ├── chart.jpg
│   └── logo.svg
├── automations/          # Email automations
│   └── automations.json
├── newsletter/           # Newsletter settings
│   └── newsletter.json
└── snippets/             # Reusable content snippets
    └── snippets.json

​
Core Directories

​
emails/

Contains all your newsletter emails as Markdown files with YAML frontmatter.
  • File naming: Each email is saved as {slug-or-id}.md
  • Format: Markdown with YAML frontmatter (see Email Format)
  • Purpose: Main content for your newsletters
Emails use the slug field for the filename if available, otherwise they fall back to the email’s id.

​
media/

Stores all images and media files downloaded from Buttondown.
  • File naming: Original filename from Buttondown (e.g., header-image.png)
  • Supported formats: PNG, JPG, GIF, SVG, WebP
  • Usage: Referenced in emails using relative paths
Example reference in an email: 
![My chart](../media/chart.jpg)

​
Other Resource Directories

The CLI also syncs additional Buttondown resources:

automations/

Email automation workflows

newsletter/

Newsletter settings and configuration

snippets/

Reusable content snippets

​
State Management File

​
.buttondown.json

This file tracks the sync state and is automatically managed by the CLI. 
{
  "syncedImages": {
    "img_abc123": {
      "id": "img_abc123",
      "localPath": "/absolute/path/to/my-newsletter/media/header.png",
      "url": "https://buttondown.s3.amazonaws.com/images/abc123.png",
      "filename": "header.png"
    }
  }
}
Key responsibilities:
​
syncedImages
object
Maps image IDs to their local paths and remote URLs. This allows the CLI to:
  • Convert absolute URLs to relative paths when pulling
  • Convert relative paths to absolute URLs when pushing
  • Avoid re-uploading images that are already synced
  • Track which images belong to your newsletter
Do not manually edit .buttondown.json unless you know what you’re doing. The CLI relies on this file to track sync state and prevent duplicate uploads.

​
How Files Are Created

​
On Pull

From src/commands/pull.tsx:83-162:
1

Create directories

The CLI creates the base directory structure with mkdir recursive mode.
2

Download resources

Syncs automations, newsletter settings, and snippets first.
3

Download images

Fetches all images from Buttondown and saves them to media/.
4

Download emails

Fetches emails and converts absolute image URLs to relative paths.
5

Update state

Writes the sync state to .buttondown.json.

​
On Push

From src/commands/push.tsx:84-184:
1

Read local files

Scans the directory for modified files.
2

Upload new images

Any images referenced in emails that aren’t in .buttondown.json are uploaded.
3

Convert image paths

Replaces relative image paths with absolute URLs before pushing to Buttondown.
4

Upload changes

Only emails that have changed are uploaded to Buttondown.
5

Update state

Updates .buttondown.json with newly uploaded images.

​
Directory Location

By default, the CLI uses a ./buttondown directory in your current working directory. You can specify a different location: 
buttondown pull --directory=./my-custom-location
buttondown push --directory=./my-custom-location
Use the same --directory flag for both pull and push commands to ensure consistency.

​
Version Control

When using Git or other version control systems: Do commit:
  • emails/ - Your newsletter content
  • media/ - Images and media files (if not too large)
  • automations/, newsletter/, snippets/ - Configuration files
Consider ignoring:
  • .buttondown.json - Contains absolute paths specific to your machine
  • Large media files (add to .gitignore and use Git LFS if needed)
Example .gitignore: 
.buttondown.json
media/*.mp4
media/*.mov

Build docs developers (and LLMs) love

Get started for freeTalk to us