CodePen Commander — Sync, serve, and build local CodePen 2.0 Pens straight from the CLI
Read the original on bram.us ↗I scratched my own itch (again 😅) and built CodePen Commander — a CLI cdpn command to sync, serve, and build local CodePen 2.0 Pens (individually or across entire demo repositories), deploy them, and manage privacy rules right from the terminal.
~
# Show, don’t tell
To immediately jump in: here is “CodePen Commander” in action. This should give you a clear idea of what this is about:
codepen-commander (cdpn) in action (recorded on v1.0.0; read on for everything added up through v1.4.0!).And that’s not all, as CodePen Commander can also serve and build CodePen files locally!
~
# Why?
If you read any of my posts that contain demos, you might have noticed that these demos are typically hosted on CodePen. To build them, I used to load up the CodePen editor (via pen.new) and start typing there, but nowadays I often find myself working on a local copy or inside a repository full of demos. In the end though, I still want to publish those local versions onto CodePen as well (either under my personal account or the web-dot-dev account). But keeping those local files and the online Pens in sync was quite a tedious job, as sometimes I ended up making changes online and sometimes in the local copy.
With CodePen 2.0 introducing the CodePen API v2 a while ago, all the building blocks were suddenly there to automate that entire workflow, as manually copy-pasting files back and forth is not a scalable solution. The result is a simple binary: cdpn, published to NPM as codepen-commander.
💁♂️ Why codepen-commander as the NPM package name while the binary is cdpn? The names codepen and codepen-cli were already taken, and cdpn / cdpn-cli tripped NPM’s similarity filter against existing packages. Plus, codepen-commander has a nice classic CLI ring to it (and doubles as a subtle nod to commander under the hood 🙂).
~
# Installation and Authentication
You can install codepen-commander globally through NPM (requires Node.js 20 or newer):
npm install -g codepen-commander
Once installed, you get the short cdpn command available. To get started, first provide it with a CodePen API v2 key key from codepen.io/settings/api):
cdpn auth login
Running cdpn auth login opens the CodePen API settings page in your browser, verifies your key, and saves named profiles inside ~/.cdpn with strict 0600 owner-only permissions. You can inspect or switch profiles anytime with cdpn auth status, cdpn auth list, and cdpn auth default.
When you run a command, cdpn automatically picks the right profile: it checks an explicit --profile <name> flag first, then the CODEPEN_API_KEY environment variable (handy in CI), then the profile saved in the current folder’s .cdpn.json, and even auto-matches the Pen’s owner from the URL when cloning.
Note that using the CodePen v2 API requires a CodePen Pro account. I can highly recommend getting one.
~
# Syncing Pens locally
If you have ever used Git, the day-to-day sync workflow will feel right at home. Clone an existing Pen, edit files locally in your editor of choice, check what changed, and push everything back up in a single saved version — or let cdpn sync figure out the direction for you:
# Clone an existing Pen into a local folder
cdpn clone https://codepen.io/bramus/pen/abcde my-pen
cd my-pen
# Check local file & metadata diffs against the online saved head
cdpn status
# Pull remote changes, push local edits, or sync bidirectionally
cdpn pull
cdpn push -m "Tweak layout and styles"
cdpn sync
💁♂️ When trying to clone a v1 Classic Pen, cdpn will offer to let you convert it to a 2.0 Pen first (or clone it unlinked). The CodePen API does not offer conversion out of the box, so this is a quick manual step in the browser while cdpn waits and polls until it’s ready.
When you push, cdpn uploads text edits, binary assets, deletions, and any metadata changes from .cdpn.json together as one atomic version, waits for CodePen’s build pipeline to settle, reports any diagnostics, and even writes compiler patches back to your local files. And if you already have a standalone demo folder on disk that isn’t on CodePen yet, just run cdpn push (or cdpn sync) inside it and it creates the Pen for you on the spot (after asking a few details such as title and privacy rules — or reusing what you already stored in .cdpn.json).
If you don’t want to think about whether your local folder or CodePen is ahead, cdpn sync handles bidirectional 3-way syncing in a single command: it publishes unlinked folders as new Pens, pushes when local is ahead, pulls when remote is ahead, and safely flags conflicts when both sides have diverged. You can also drop an optional .cdpnignore file into a Pen folder to exclude extra local files from syncing (.cdpn.json, .cdpnignore, .git, node_modules, and .DS_Store are always ignored automatically).
~
# Batch operations across multiple Pens
If you keep a whole collection of demos inside a single repository organized in nested folders, running cdpn status or cdpn push in each folder one by one gets old fast. As of 1.4.0, status, push, pull, sync, delete, and unlink all support both explicit directory targeting and batch tree-walking.
To make sure you never accidentally walk an entire directory tree, batch mode is explicitly gated behind the all keyword. Without it, commands stay strictly scoped to the current directory (or whatever single folder path you pass):
# Target a single Pen by path
cdpn pull my-demo
cdpn status css/grid-demo
# Check sync status across every discovered Pen in subdirectories
cdpn status all
# Preview a batch operation without changing anything
cdpn sync all --dry-run
cdpn push all --dry-run
# Bidirectionally sync every discovered Pen in one go
cdpn sync all
There are a few nice safety rails baked into batch mode too. Running cdpn status (or pull, push, sync, delete, unlink) interactively inside a non-Pen directory that contains subdirectories won’t waste time prescanning the tree — it simply asks whether you want to run cdpn <cmd> all instead (defaulting to No). If you happen to have a folder literally named all, cdpn catches the ambiguity and asks whether you meant ./all or walking all Pens (and passing ./all always targets the directory unambiguously).
Under the hood, tree walking enforces strict root containment, treats each Pen folder as a leaf, and skips symlinks, hidden folders like .git, node_modules, .cdpnignored paths, and static build outputs. For destructive batch commands like cdpn delete all and cdpn unlink all, cdpn lists every targeted Pen up front with a yes/No prompt, followed by a second “Are you really sure?” confirmation before touching anything (pass --yes in non-interactive scripts, or --dry-run to inspect first).
~
# The .cdpn.json file
For every demo tracked by CodePen Commander, there is a .cdpn.json file at its root that is key to keeping track of things:
{
"url": "https://codepen.io/username/pen/abcde",
"pen_id": "01a08738-73f0-7847-b6a8-5789d289c158",
"profile": "username",
"last_synced_version_id": "01a08738-73f0-7848-b8bf-e8e7e91b1ae2",
"last_synced_info_hash": "a1b2c3d4...",
"editor": "V2",
"info": {
"title": "My Awesome Pen",
"description": "A short description of the Pen",
"tags": ["css", "demo"],
"access": "Public",
"template": false
},
"files": {…}
}
The file contains the base data needed for syncing (the pen_id and profile), a map of synced files and their hashes, as well as editable Pen metadata inside the info field. Typically this file should not be edited by hand, except for the info field — editing title, description, tags, access, or template directly in .cdpn.json syncs straight to CodePen on your next cdpn push or cdpn sync (passwords for Protected Pens are never stored in .cdpn.json).
A .cdpn.json can also exist in an unlinked state containing only the info block — which is what cdpn init and cdpn unlink create. That single file is enough for cdpn serve, cdpn build, and batch commands to discover the folder as a CodePen demo, and when you eventually run cdpn push, all that saved info metadata is reused automatically without re-prompting you.
ℹ️ If you are versioning your code using Git, you should definitely commit that .cdpn.json file into your repo!
~
# Beyond syncing
Once I got the core sync loop working, it quickly became clear how nice it is to handle the rest of the CodePen lifecycle from the terminal too. The full list of commands is this:
Let’s dig into some details…
~
Initializing, scaffolding, and forking
Already have a local HTML/CSS/JS demo folder that you want to turn into a CodePen demo? Run cdpn init inside it (or accept the prompt when running cdpn status in a non-Pen folder). It interactively asks for a title, visibility, and CodePen blocks (multi-select, with validate and fingerprint required), writes an unlinked .cdpn.json and .codepen/pen.config.json (plus .codepen/classic.config.json when the classic block is picked), and optionally offers to push it straight to CodePen:
cdpn init # Interactive setup
cdpn init ./my-demo -t "Scroll Demo" --visibility Public --blocks packages
Need a fresh Pen from scratch instead? Run cdpn new my-demo to scaffold a brand-new 2.0 Pen from your own CodePen Templates (fetched interactively from your account, or passed via --template) or from CodePen’s default 2.0 starter. You can even pass --as-template to mark the new Pen as a reusable template right away. To prevent accidental overwrites, cdpn new refuses to run in a folder that already has files — steering you to cdpn init instead.
To fork one of your own Pens into a local folder, use cdpn fork <url>. This is limited to your Pens due to how the CodePen API works: you can’t fork other people’s Pens with it. To keep things smooth, cdpn offers to open the Pen in your browser so you can fork it on codepen.io itself and then paste the forked URL straight back to clone immediately.
~
# Local preview server and static builds
CodePen Commander can also be used as standalone local dev server and static site builder for your Pens — even completely offline:
# Serve a single Pen or a whole directory of Pens on http://127.0.0.1:3000
cdpn serve
cdpn serve my-demos --port 8080 --open
# Build a Pen or demo collection into a static deployable folder
cdpn build
cdpn build --out dist --yes --watch
Both cdpn serve and cdpn build auto-detect what you point them at. When run inside a single Pen folder (one containing .cdpn.json), they serve or build that Pen directly — and when building into a subfolder inside the Pen itself, cdpn build automatically adds the output directory to .cdpnignore and offers to update .gitignore so build artifacts never sneak into your CodePen pushes or Git commits.
When run inside a directory of Pens (no .cdpn.json at the root), cdpn recursively discovers every subdirectory containing a .cdpn.json and generates a live in-memory demos.json on serve (updating automatically as you add or edit demos) or a static demos.json on build. That manifest powers a built-in light/dark demo index shell with cards showing each Pen’s title, description, tags, an Open Demo button, and an Edit on CodePen link (and if you already have your own root index.html, cdpn preserves it).

cdpn build. The page lists all demos (currently 1) that are part of that repository.Even better: cdpn emulates CodePen 2.0’s classic block (assembling .pen.html and .codepen/classic.config.json) and packages block (generating esm.sh import maps from package.json) right on the fly during both serve and build. If a Pen uses a build block that isn’t emulated locally yet, the browser shows a friendly notice page explaining why instead of breaking silently. And for security, cdpn serve binds strictly to 127.0.0.1 and never exposes dotfiles like .cdpn.json or .env.
💁♂️ Subdirectories without a .cdpn.json file are intentionally skipped by cdpn serve and cdpn build. While serving locally, the built-in index shell shows a small hint reminding you to run cdpn init in any missing folder to register it as a CodePen demo (that hint is omitted from static cdpn build output).
~
Safer deletions, Trash recovery, and unlinking
Mistakes happen — especially when juggling dozens of Pens. In 1.4.0, cdpn delete moves the online Pen to CodePen’s Deleted Items (Trash, where it remains restorable for 3 days) while keeping both .cdpn.json and .codepen/ intact locally by default. If you do want local cleanup, pass --cleanup to remove .codepen/ while retaining an unlinked info-only .cdpn.json, or --full-cleanup to remove both (your actual source files are never deleted).
If a synced Pen has been deleted on CodePen — whether through cdpn delete or via the web UI — commands like cdpn status, pull, push, and info automatically check CodePen’s Trash and offer to restore the Pen, permanently delete it, or unlink your local copy. There are also dedicated commands for both:
cdpn restore # Restore the current folder’s Pen from Trash (or pick from Trash)
cdpn unlink # Disconnect locally (keeps the online Pen, .codepen/, and Pen info)
~
Deploying, custom domains, opening in the browser, and more …
Deploying a Pen live to CodePen Hosting is a single command:
cdpn deploy # Push local changes and deploy live
cdpn domains # Show the default *.codepen.app URL + custom domains & DNS records
cdpn domains add demo.example.com # Attach a custom domain
And you can manage custom domains or jump straight into the browser just as easily:
cdpn open # Open the Pen editor in your browser
cdpn open --preview # Open the preview
cdpn open --deploy # Open the deployed site (prompts if multiple domains exist)
You can also take a deployment down with cdpn undeploy or remove custom domains with cdpn domains delete (aliased to del and rm).
~
The --json flag
Every data and state command also accepts a --json flag (including cdpn auth --json status|list|default|logout — everything except interactive-only auth login, browser-opening open, and long-running serve). When set, cdpn runs non-interactively and outputs a predictable JSON envelope with HTTP-style status codes — making it easy to plug into shell scripts, CI pipelines, or AI coding agents:
{
"status": {
"code": 200,
"message": "Up to date with CodePen (3 file(s))."
},
"contents": {
"...": "raw command data"
}
}
~
# Source code
codepen-commander is open source under the MIT license. The full source code, command reference, and documentation are up on GitHub — bug reports, ideas, and pull requests are very welcome! 🙂
~
# Spread the word
Feel free to reshare one of the following posts on social media to help spread the word:
~
🔥 Like what you see? Want to stay in the loop? Here's how:
I can also be found on 𝕏 Twitter and 🐘 Mastodon but only post there sporadically.

