emdash-cli

# EmDash CLI The EmDash CLI (`emdash`, with the short alias `em`) manages EmDash CMS instances. Commands fall into two categories: - **Local commands** work with project files or a configured database: `init`, `doctor`, `seed`, `migrate`, `export-seed`, and `secrets`. - **Remote commands** talk to a running EmDash instance: `types`, `login`, `logout`, `whoami`, `content`, `schema`, `media`, `search`, `taxonomy`, `menu`, and `site`. 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. ## Authentication Remote commands resolve auth automatically: 1. `--token` flag 2. `EMDASH_TOKEN` env var 3. Stored credentials from `emdash login` 4. Dev bypass (localhost only — no token needed) For a localhost development server with the development bypass enabled, the client can authenticate automatically. For a remote instance, run `emdash login --url https://example.com` or provide a scoped token. ## Custom Headers & Reverse Proxies Sites behind Cloudflare Access or other reverse proxies need auth headers on every request. The CLI supports this via `--header` flags and environment variables. ### Service tokens for automation ```bash # 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://example.com ``` `emdash 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. ### Cloudflare Access Browser Flow If you don't have service tokens and `cloudflared` is installed, the CLI will automatically: 1. Detect when Access blocks the request 2. Try to get a cached JWT via `cloudflared access token` 3. Fall back to `cloudflared access login` for browser-based auth This works for interactive use but isn't suitable for CI. Use service tokens for automation. ### Generic Reverse Proxy Auth The `--header` flag works with any auth scheme: ```bash # 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" ``` ## Quick Reference ### Database Setup For normal site startup, use the project's package script. The first request runs pending migrations and, before setup is completed, applies the bundled seed's schema and structure once; sample content comes from the setup wizard, `/_emdash/api/setup/dev-bypass`, or `emdash seed`. The Astro integration generates `emdash-env.d.ts` when the server starts. ```bash # 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 ``` ### Type Generation ```bash # Generate types from local dev server npx emdash types # Generate from remote npx emdash types --url https://example.com # Custom output path npx emdash types --output src/types/cms.ts ``` Writes `.emdash/types.ts` (TypeScript interfaces) and `.emdash/schema.json`. ### Authentication ```bash # Login (OAuth Device Flow) npx emdash login --url https://example.com # Check current user npx emdash whoami # Logout npx emdash logout # Generate an encryption key for deployment npx emdash secrets generate ``` ### Content CRUD The CLI is designed for agents. Create and update auto-publish by default so agents get read-after-write consistency without managing drafts. ```bash # 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 ``` ### Schema Management ```bash # 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 featured ``` `schema 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. ### Media ```bash # 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 01MEDIA123 ``` ### Search ```bash npx emdash search "hello world" npx emdash search "hello" --collection posts --limit 5 ``` ### Taxonomies ```bash npx 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 01PARENT123 ``` ### Menus ```bash npx emdash menu list npx emdash menu get primary ``` ### Site Export and Import `emdash 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. ```bash # 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.com ``` Show 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`. ## Drafts and Publishing The CLI auto-publishes on `create` and `update` by default. This means: - **`create`** creates the item and immediately publishes it - **`update`** updates the item and publishes if a draft revision was created - **`get`** 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. ## JSON Output 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" } }`. ```bash # 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') ``` ## Editing Flow For details on how content editing works — Portable Text/markdown conversion, `_rev` tokens, and raw mode — see **[EDITING-FLOW.md](./EDITING-FLOW.md)**.