import { Aside } from "@astrojs/starlight/components";

The EmDash CLI provides commands for managing an EmDash CMS instance — database setup, type generation, content CRUD, schema management, media, and more.

The CLI is included with the emdash package:

npm install emdash

Run commands with npx emdash or add scripts to package.json. The binary is also available as em for brevity.

Commands that talk to a running EmDash instance (everything except init, seed, export-seed, and auth secret) resolve authentication in this order:

1. --token flag — explicit token on the command line
2. EMDASH_TOKEN env var
3. Stored credentials from ~/.config/emdash/auth.json (saved by emdash login)
4. Dev bypass — if the URL is localhost and no token is available, automatically authenticates via the dev bypass endpoint

Most commands accept --url (default http://localhost:4321) and --token flags. When targeting a local dev server, no token is needed.

These flags are available on all remote commands:

When stdout is a TTY, the CLI pretty-prints results with consola. When piped or when --json is set, it outputs raw JSON to stdout — suitable for jq or other tools.

Initialize the database with core schema and optional template data.

npx emdash init [options]

1. Reads emdash config from package.json
2. Creates the database file if needed
3. Runs core migrations (creates system tables)
4. Runs template schema.sql if configured
5. Runs template seed.sql if configured

Start the development server with automatic database setup.

npx emdash dev [options]

# Start dev server
npx emdash dev

# Custom port
npx emdash dev --port 3000

# Generate types from remote before starting
npx emdash dev --types

1. Checks for and runs pending database migrations
2. If --types is set, generates TypeScript types from a remote instance (URL from EMDASH_URL env or emdash.url in package.json)
3. Starts Astro dev server with EMDASH_DATABASE_URL set

Generate TypeScript types from a running EmDash instance's schema.

npx emdash types [options]

# Generate types from local dev server
npx emdash types

# Generate from remote instance
npx emdash types --url https://my-site.pages.dev

# Custom output path
npx emdash types --output src/types/emdash.ts

1. Fetches the schema from the instance
2. Generates TypeScript type definitions
3. Writes types to the output file
4. Writes schema.json alongside for reference

Log in to an EmDash instance using OAuth Device Flow.

npx emdash login [options]

1. Discovers auth endpoints from the instance
2. If localhost and no auth configured, uses dev bypass automatically
3. Otherwise initiates OAuth Device Flow — displays a code and opens your browser
4. Polls for authorization, then saves credentials to ~/.config/emdash/auth.json

Saved credentials are used automatically by all subsequent commands targeting the same instance.

Log out and remove stored credentials.

npx emdash logout [options]

Show the current authenticated user.

npx emdash whoami [options]

Displays email, name, role, auth method, and instance URL.

Manage content items. All subcommands use the remote API via EmDashClient.

npx emdash content list posts
npx emdash content list posts --status published --limit 10

npx emdash content get posts 01ABC123
npx emdash content get posts 01ABC123 --raw

The response includes a _rev token — pass it to content update to prove you've seen what you're overwriting.

npx emdash content create posts --data '{"title": "Hello"}'
npx emdash content create posts --file post.json --slug hello-world
cat post.json | npx emdash content create posts --stdin

Provide data via exactly one of --data, --file, or --stdin.

Like a file editor that requires you to read before you write — you must provide the _rev token from a prior get to prove you've seen the current state. This prevents accidentally overwriting changes you haven't seen.

# 1. Read the item, note the _rev
npx emdash content get posts 01ABC123

# 2. Update with the _rev from step 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Updated"}'

If the item has changed since your get, the server returns 409 Conflict — re-read and try again.

npx emdash content delete posts 01ABC123

Soft-deletes the content item (moves to trash).

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

Restores a trashed content item.

Manage collections and fields.

npx emdash schema list

Lists all collections.

npx emdash schema get posts

Shows a collection with all its fields.

npx emdash schema create articles --label Articles
npx emdash schema create articles --label Articles --label-singular Article --description "Blog articles"

npx emdash schema delete articles
npx emdash schema delete articles --force

Prompts for confirmation unless --force is set.

npx emdash schema add-field posts body --type portableText --label "Body Content"
npx emdash schema add-field posts featured --type boolean --required

npx emdash schema remove-field posts featured

Manage media items.

npx emdash media list
npx emdash media list --mime image/png --limit 20

npx emdash media upload ./photo.jpg
npx emdash media upload ./photo.jpg --alt "A sunset" --caption "Taken in Bristol"

npx emdash media get 01MEDIA123

npx emdash media delete 01MEDIA123

Full-text search across content.

npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5

Manage taxonomies and terms.

npx emdash taxonomy list

npx emdash taxonomy terms categories
npx emdash taxonomy terms tags --limit 50

npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123

Manage navigation menus.

npx emdash menu list

npx emdash menu get primary

Returns the menu with all its items.

Apply a seed file to the database. This command works directly on a local SQLite file (no running server needed).

npx emdash seed [path] [options]

The command looks for seed files in this order:

1. Positional argument (if provided)
2. .emdash/seed.json (convention)
3. Path from package.json emdash.seed field

Export database schema and content as a seed file. Works directly on a local SQLite file.

npx emdash export-seed [options] > seed.json

The exported seed file includes:

• Settings: Site title, tagline, social links
• Collections: All collection definitions with fields
• Taxonomies: Taxonomy definitions and terms
• Menus: Navigation menus with items
• Widget Areas: Widget areas and widgets
• Content (if requested): Entries with $media references and $ref: syntax for portability

Generate a secure authentication secret for your deployment.

npx emdash auth secret

Outputs a random secret suitable for EMDASH_AUTH_SECRET.

TypeScript interfaces generated by emdash types:

// Generated by EmDash CLI
// Do not edit manually - run `emdash types` to regenerate

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	title: string;
	content: PortableTextBlock[];
	publishedAt: Date | null;
}

Raw schema export for tooling:

{
  "version": "a1b2c3d4",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "fields": [...]
    }
  ]
}

{
	"scripts": {
		"dev": "emdash dev",
		"init": "emdash init",
		"types": "emdash types",
		"seed": "emdash seed",
		"export-seed": "emdash export-seed",
		"db:reset": "rm -f data.db && emdash init"
	}
}