Substack Ghost CSV Converter

Converts the "Total Email List" and "Subscribers" CSV exports from Substack to a CSV compatible with Ghost.

Install

To install the CLI, which is required for the Usage commands below:

npm install --global @tryghost/migrate

To use this package in your own project:

npm install @tryghost/mg-substack-members-csv --save

or

pnpm add @tryghost/mg-substack-members-csv

Usage

To run a Substack CSV migration, the required command is:

migrate substack-members --pathToFile /path/to/emails.csv

To convert paid subscriptions, add --subs with a second file path:

migrate substack-members --pathToFile /path/to/emails.csv --subs /path/to/members.csv

It's possible to pass more options, in order to achieve a better migration file for Ghost:

• --pathToFile (required)
  • Path to the signups CSV file as generated by Substack ("Total Email List").
  • string - default: null
• -V --verbose
  • Show verbose output
  • bool - default: false
• -s --subs
  • Path to the subscribers CSV file (paid, comp, gift) as generated by Substack ("Subscribers")
  • string - default: null
• -l --limit
  • Define the batch limit for import files
  • int - default: 5000
• --comp
  • Provide two values in the format YY|YYYYMMDD:none|free. YY is the threshold in years or YYYYMMDD as the exact date after which Substack comp members should receive a complimentary plan depending on the expiry date. none|free the option how to import members before this threshold, e. g. 5:free
  • string - default: 0:free
  • Choices: YY:none, YY:free, YYYYMMDD:none, YYYYMMDD:free
• --compLabel
  • Provide a label for Substack comp subscribers
  • string - default: substack-comp
• --gift
  • Provide two values in the format YY|YYYYMMDD:none|free. YY is the threshold in years or YYYYMMDD as the exact date after which Substack gift members should receive a complimentary plan depending on the expiry date. none|free the option how to import members before this threshold, e. g. 5:free
  • string - default: 0:free
  • Choices: YY:none, YY:free, YYYYMMDD:none, YYYYMMDD:free
• --giftLabel
  • Provide a label for Substack gift subscribers
  • string - default: substack-gift
• --freeLabel
  • Provide a label for Substack free subscribers
  • string - default: substack-free
• --paidLabel
  • Provide a label for Substack paid subscribers
  • string - default: substack-paid
• --cache
  • Persist local cache after migration is complete (Only if --zip is true)
  • bool - default: true

A more complex migration command that accounts for Stripe data could look like this:

migrate substack-members --pathToFile /path/to/emails.csv --subs /path/to/members.csv --giftLabel Gifted --freeLabel Free --paidLabel Supporter --compLabel 'Try It Out'

Develop

This is a mono repository, managed with Nx and pnpm workspaces.

Follow the instructions for the top-level repo.

1. git clone this repo & cd into it as usual
2. Run pnpm install to install top-level dependencies.

Run

To run a local development copy, cd into this directory, and use pnpm dev instead of migrate like so:

pnpm dev substack-members --pathToFile /path/to/emails.csv

Test

• pnpm lint run just eslint
• pnpm test run lint and tests

Copyright & License

Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license.