Use the EmDash CLI to inspect and manage an EmDash instance from the command line, including content, schema, media, taxonomies, menus, search, authentication, seeds, migrations, generated types, and whole-site export and import.
82%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
The EmDash CLI (emdash, with the short alias em) manages EmDash CMS instances. Commands fall into two categories:
init, doctor, seed, migrate, export-seed, and secrets.types, login, logout, whoami, content, schema, media, search, taxonomy, menu, site, and plugin.Run npx emdash --help and npx emdash <command> --help for the installed version's exact commands and flags. Resolve the current target with a read command before a destructive or bulk mutation; examples in this skill do not authorize changing an instance the user did not place in scope.
Remote commands resolve auth automatically:
--token flagEMDASH_TOKEN env varemdash loginFor a localhost development server with the development bypass enabled, the client can authenticate automatically. For a remote instance, run emdash login --url https://my-site.pages.dev or provide a scoped token.
Sites behind Cloudflare Access or other reverse proxies need auth headers on every request. The CLI supports this via --header flags and environment variables.
# Provide sensitive headers through the environment in CI.
export EMDASH_HEADERS="CF-Access-Client-Id: xxx
CF-Access-Client-Secret: yyy"
npx emdash whoami --url https://my-site.pages.devemdash login --header persists custom headers to ~/.config/emdash/auth.json for later commands. Prefer environment-provided headers in CI so a service secret is not written to the credential file or shell history.
If you don't have service tokens and cloudflared is installed, the CLI will automatically:
cloudflared access tokencloudflared access login for browser-based authThis works for interactive use but isn't suitable for CI. Use service tokens for automation.
The --header flag works with any auth scheme:
# Basic auth
npx emdash login --url https://example.com -H "Authorization: Basic dXNlcjpwYXNz"
# Custom auth header
npx emdash login --url https://example.com -H "X-API-Key: secret123"For normal site startup, use the project's package script. The first request runs pending migrations and applies the bundled seed when the database is empty and setup has not been completed. The Astro integration generates emdash-env.d.ts when the server starts.
# Start the site with its package script
pnpm dev
# Export an existing database as a seed file
# (the runtime auto-discovers .emdash/seed.json on first boot;
# `mkdir -p` because the directory may not exist yet)
mkdir -p .emdash
npx emdash export-seed > .emdash/seed.json
npx emdash export-seed --with-content=all > .emdash/seed.json# Generate types from local dev server
npx emdash types
# Generate from remote
npx emdash types --url https://my-site.pages.dev
# Custom output path
npx emdash types --output src/types/cms.tsWrites .emdash/types.ts (TypeScript interfaces) and .emdash/schema.json.
# Login (OAuth Device Flow)
npx emdash login --url https://my-site.pages.dev
# Check current user
npx emdash whoami
# Logout
npx emdash logout
# Generate an encryption key for deployment
npx emdash secrets generateThe CLI is designed for agents. Create and update auto-publish by default so agents get read-after-write consistency without managing drafts.
# List content
npx emdash content list posts
npx emdash content list posts --status published --limit 10
# Get a single item (Portable Text fields converted to markdown)
# Returns draft data if a pending draft exists
npx emdash content get posts 01ABC123
npx emdash content get posts 01ABC123 --raw # skip PT->markdown conversion
npx emdash content get posts 01ABC123 --published # ignore pending drafts
# Create content (auto-publishes by default)
npx emdash content create posts --data '{"title": "Hello", "body": "# World"}'
npx emdash content create posts --file post.json --slug hello-world
npx emdash content create posts --draft --data '...' # keep as draft
cat post.json | npx emdash content create posts --stdin
# Update (requires --rev from a prior get, auto-publishes by default)
npx emdash content update posts 01ABC123 --rev MToyMDI2... --data '{"title": "Updated"}'
npx emdash content update posts 01ABC123 --rev MToyMDI2... --draft --data '...' # keep as draft
# Delete (soft delete)
npx emdash content delete posts 01ABC123
# Lifecycle
npx emdash content publish posts 01ABC123
npx emdash content unpublish posts 01ABC123
npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z
npx emdash content restore posts 01ABC123# List collections
npx emdash schema list
# Get collection with fields
npx emdash schema get posts
# Create collection
npx emdash schema create articles --label Articles --description "Blog articles"
# Delete a collection after inspecting it and confirming the target
npx emdash schema get articles
npx emdash schema delete articles
# Add field
npx emdash schema add-field posts body --type portableText --label "Body Content"
npx emdash schema add-field posts featured --type boolean --required
# Remove field
npx emdash schema remove-field posts featuredschema add-field supports the field types printed by npx emdash schema add-field --help. The full product schema supports additional field types that are not necessarily creatable through this command.
# List media
npx emdash media list
npx emdash media list --mime image/png
# Upload
npx emdash media upload ./photo.jpg --alt "A sunset" --caption "Bristol, 2026"
# Get / delete
npx emdash media get 01MEDIA123
npx emdash media delete 01MEDIA123npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5npx emdash taxonomy list
npx emdash taxonomy terms categories
npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123npx emdash menu list
npx emdash menu get primaryemdash site copies a whole site (content model, content, history, settings, and media, but no users or secrets) into a .emdash site package, and imports a package into an empty site. The token needs admin, which the emdash login token has, or the transfer:export, transfer:analyze, and transfer:execute scopes. An INSUFFICIENT_SCOPE error means the token has neither. A package holds every entry and the email addresses of authors and commenters: treat it like a database backup.
# Export (re-run the same command to resume after an interruption)
npx emdash site export --url https://old.example.com --output site.emdash
npx emdash site export --url https://old.example.com --output site.emdash --no-comments
# Import, step 1: upload and analyze; prints the plan and its digest
npx emdash site import site.emdash --url https://new.example.com --analyze
npx emdash site import site.emdash --url https://new.example.com --analyze \
--map-principal editor@example.com=editor@example.com --use-target-title
# Import, step 2: execute exactly the reviewed plan
npx emdash site import site.emdash --url https://new.example.com --plan sha256:<hex> --confirm
# Follow up on an import by operation id
npx emdash site import status <operation-id> --url https://new.example.com
npx emdash site import resume <operation-id> [site.emdash] --url https://new.example.com
npx emdash site import receipt <operation-id> --url https://new.example.com
# Stop an import, or lift the write block a failed or cancelled import leaves
# (neither deletes what the import wrote; --yes skips the prompt)
npx emdash site import cancel <operation-id> --url https://new.example.com
npx emdash site import abandon <operation-id> --url https://new.example.comShow the user the plan (differences from the source site, warnings, blockers, principal mappings) and get their confirmation before running --confirm; it writes to the target site and blocks other writes there until it finishes. site import exits 2 when the plan has blockers, and site import status exits 1 for an import that failed, was cancelled or abandoned, or expired. Only cancel or abandon an import when the user asks: abandoning leaves partial data on the site, which then has to be reset before another import. --map-principal takes <principal id or email>=<user id, email, or none> and is repeatable; decision flags only work with --analyze, and each change produces a new plan digest. The public site is not hidden during an import, so the target should stay private until the command prints a receipt with receiptDigestValid: true.
The CLI auto-publishes on create and update by default. This means:
create creates the item and immediately publishes itupdate updates the item and publishes if a draft revision was createdget returns draft data if a pending draft exists (e.g. from the admin UI)Use --draft on create/update to skip auto-publishing. Use --published on get to ignore pending drafts.
Collections that support revisions store edits as draft revisions. The CLI handles this transparently — agents don't need to know whether a collection uses revisions or not.
All remote commands support --json for machine-readable output. It's auto-enabled when stdout is piped. emdash site always writes progress to stderr, so stdout holds only the JSON result; errors are { "error": { "code", "message" } }.
# Pipe to jq
npx emdash content list posts --json | jq '.items[].slug'
# Use in scripts
ID=$(npx emdash content create posts --data '{"title":"Hello"}' --json | jq -r '.id')For details on how content editing works — Portable Text/markdown conversion, _rev tokens, and raw mode — see EDITING-FLOW.md.
emdash-cms/emdash
8852f3f
Also appears in
since Oct 23, 2026
since Oct 17, 2026
since Oct 11, 2026
since Oct 11, 2026
since Oct 5, 2026
since Sep 28, 2026
since Sep 28, 2026
since Sep 28, 2026
on Nov 7, 2026
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.