Skip to content

Importing course and student data

StratoLMS import commands create editable course-content skeletons and a separate private migration record. They do not migrate an account or replace a payment provider. The Teachable, Podia, and Gumroad commands consume the same small normalized CSV contract; they are not generic native-export readers. Provider-specific mappings require a sanitized representative export and a verified format reference.

Save the file as UTF-8 CSV. A leading Excel byte-order mark, CRLF or LF line breaks, quoted commas and newlines, and doubled quotes inside quoted fields are supported. Header names are trimmed and case-insensitive. Extra columns are ignored. The first occurrence of a recognized header is used.

Header Required Aliases and behavior
email Yes Each non-empty, trimmed value becomes one student migration row. The importer does not verify the address or deduplicate students. Rows without an email are skipped.
course_title No course is an alias. Used as the course title and slug source if course_slug is absent.
course_slug No Must be lowercase canonical kebab-case, up to 63 characters. If absent, a slug is derived from the course title; if both are empty, it becomes imported-course.
purchased_at No Recommended ISO date or timestamp. A value JavaScript cannot parse is omitted from the private record.
module_title No section is an alias. Used only when curriculum rows are provided.
lesson_title No lesson is an alias. Rows without a lesson still create a course and student record.
video_url No video is an alias. Kept in generated lesson files only as a commented source reference to re-host.

The parser reports an error for empty input, a missing email header, an unterminated quoted field, or an unsafe supplied course slug. It does not validate provider export formats, learner eligibility, purchase/refund status, or whether a video URL is still available. Sales rows are data to review, not an authorization decision.

The checked-in inputs in the synthetic fixture directory use reserved .test email addresses. Each provider page shows its corresponding example and expected result:

  • Teachable uses curriculum columns and includes a video reference.
  • Podia exercises the course, section, lesson, and video aliases.
  • Gumroad demonstrates a sales-only row and missing-curriculum warning.

The CLI writes a course to src/content/courses/<course-slug>/_course.mdx. It creates an instructor at src/content/instructors/you.mdx, numbered module directories such as 01-foundations/ with _module.yaml, and numbered lesson files such as 01-anchoring.mdx. Course and lesson slugs are derived from titles by Unicode normalization, lowercase ASCII kebab-case conversion, and a 63-character cap. Rows with the same course and module slug are combined; a lesson slug repeated for that module is emitted once.

If no curriculum columns provide a lesson title, the CLI reports a warning and scaffolds a placeholder Module one and First lesson. Gumroad adds a warning that its sales data is not curriculum. Teachable adds a warning that hosted video must be re-hosted. Every course skeleton is access: free and status: draft, every generated lesson starts with preview: false, and placeholder copy must be replaced before publishing.

The student rows are encoded in a separate file at .stratolms-private/migrations/<run-id>/students.csv. The generated project ignores .stratolms-private/; the content loader and site do not read this record. Keep the original export and migration record in access-controlled storage while reviewing them. Do not commit the record, paste it into an issue, or upload it to a public site. The JSON result reports counts and planned paths, not learner emails or row contents.

Run a dry-run first. It parses the whole input and shows files it would create or skip without writing them:

Terminal window
pnpm stratolms import --from teachable --file=./normalized.csv --dry-run --json

Choose podia or gumroad for the corresponding normalized input. If the preview is correct, write the files and validate them:

Terminal window
pnpm stratolms import --from teachable --file=./normalized.csv
pnpm stratolms check

The importer skips any file that already exists; it does not merge or overwrite creator content. Review each skipped path and integrate any needed information manually. A new import run can create a new dated student record, so the CLI does not promise whole-project idempotence. Compare the generated tree with the preview before repeating an import.

Replace placeholders, confirm you have the rights to each lesson and media asset, and re-host any platform video. The importer does not transfer payments, entitlements, refunds, downloadable files, or course content absent from the CSV. A migration CSV is not proof that a learner should receive access. Decide any replacement access through your new provider after reviewing purchase and refund status with the course owner. Keep the course draft until the free content and site are ready; for paid courses, configure product mapping and qualify checkout, webhook, access, refund, and recovery behavior using the payments guide.

After the reviewed data has been moved to the records you actually need, delete the original exports and private migration CSVs according to your retention policy. Emptying your recycle bin or storage trash may be needed for local copies. Do not delete the generated source files until you have verified the course content you chose to keep.