CLI 참조

EmDash CLI는 EmDash CMS 인스턴스 관리를 위한 명령을 제공합니다 — 데이터베이스 설정, 타입 생성, 콘텐츠 CRUD, 스키마 관리, 미디어 등.

설치

CLI는 emdash 패키지에 포함되어 있습니다. 다음 명령으로 설치하세요:

npm install emdash

npx emdash로 명령을 실행하거나 package.json에 스크립트를 추가하세요. 바이너리는 간결함을 위해 em으로도 사용 가능합니다.

인증

실행 중인 EmDash 인스턴스와 통신하는 명령은 다음 순서로 인증을 해결합니다:

1. --token 플래그 — 커맨드라인의 명시적 토큰
2. EMDASH_TOKEN 환경 변수
3. 저장된 자격 증명 ~/.config/emdash/auth.json에서 (emdash login으로 저장됨)
4. 개발 바이패스 — URL이 localhost이고 토큰이 없는 경우 개발 바이패스 엔드포인트를 통해 자동 인증

대부분의 명령은 --url (기본값 http://localhost:4321)과 --token 플래그를 허용합니다. 로컬 개발 서버를 대상으로 할 때는 토큰이 필요하지 않습니다.

공통 플래그

이 플래그들은 모든 원격 명령에서 사용 가능합니다:

출력

stdout이 TTY인 경우 CLI는 consola로 결과를 예쁘게 출력합니다. 파이프되거나 --json이 설정된 경우 stdout으로 원시 JSON을 출력합니다 — jq나 다른 도구에 적합합니다.

명령

emdash dev

자동 데이터베이스 설정으로 개발 서버를 시작합니다.

npx emdash dev [options]

옵션

예시

# 개발 서버 시작
npx emdash dev

# 커스텀 포트
npx emdash dev --port 3000

# 시작 전 원격에서 타입 생성
npx emdash dev --types

동작

1. 대기 중인 데이터베이스 마이그레이션을 확인하고 실행
2. --types가 설정된 경우 원격 인스턴스에서 TypeScript 타입 생성 (EMDASH_URL env 또는 package.json의 emdash.url에서 URL)
3. EMDASH_DATABASE_URL 설정으로 Astro 개발 서버 시작

emdash types

실행 중인 EmDash 인스턴스의 스키마에서 TypeScript 타입을 생성합니다.

npx emdash types [options]

옵션

예시

# 로컬 개발 서버에서 타입 생성
npx emdash types

# 원격 인스턴스에서 생성
npx emdash types --url https://my-site.pages.dev

# 커스텀 출력 경로
npx emdash types --output src/types/emdash.ts

동작

1. 인스턴스에서 스키마 가져오기
2. TypeScript 타입 정의 생성
3. 출력 파일에 타입 작성
4. 참조용으로 옆에 schema.json 작성

emdash login

OAuth Device Flow를 사용하여 EmDash 인스턴스에 로그인합니다.

npx emdash login [options]

옵션

동작

1. 인스턴스에서 인증 엔드포인트 검색
2. localhost이고 인증이 구성되지 않은 경우 자동으로 개발 바이패스 사용
3. 그렇지 않으면 OAuth Device Flow 시작 — 코드를 표시하고 브라우저 열기
4. 인증을 폴링한 후 ~/.config/emdash/auth.json에 자격 증명 저장

저장된 자격 증명은 같은 인스턴스를 대상으로 하는 모든 후속 명령에서 자동으로 사용됩니다.

emdash logout

로그아웃하고 저장된 자격 증명을 제거합니다.

npx emdash logout [options]

옵션

emdash whoami

현재 인증된 사용자를 표시합니다.

npx emdash whoami [options]

옵션

이메일, 이름, 역할, 인증 방법, 인스턴스 URL을 표시합니다.

emdash content

콘텐츠 항목을 관리합니다. 모든 하위 명령은 EmDashClient를 통해 원격 API를 사용합니다.

content list <collection>

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

content get <collection> <id>

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

응답에는 _rev 토큰이 포함됩니다. 덮어쓰기 전에 현재 상태를 확인했음을 증명하기 위해 content update에 전달하세요.

content create <collection>

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

--data, --file, --stdin 중 정확히 하나를 통해 데이터를 제공하세요. --draft가 설정되지 않은 한 새 항목은 자동으로 게시됩니다.

content update <collection> <id>

현재 상태를 확인했음을 증명하기 위해 이전 get의 _rev 토큰을 제공해야 합니다. 이는 보지 못한 변경 사항을 덮어쓰는 것을 방지합니다. 다음 단계는 항목을 읽은 다음 해당 토큰으로 업데이트합니다:

# 1. 항목 읽기, _rev 기록
npx emdash content get posts 01ABC123

# 2. 1단계의 _rev로 업데이트
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Updated"}'

get 이후 항목이 변경된 경우 서버는 409 Conflict를 반환합니다 — 다시 읽고 재시도하세요.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

콘텐츠 항목을 소프트 삭제합니다 (휴지통으로 이동).

content publish <collection> <id>

npx emdash content publish posts 01ABC123

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

content schedule <collection> <id>

npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z

content restore <collection> <id>

npx emdash content restore posts 01ABC123

휴지통에 있는 콘텐츠 항목을 복원합니다.

emdash schema

컬렉션과 필드를 관리합니다.

schema list

npx emdash schema list

모든 컬렉션을 나열합니다.

schema get <collection>

npx emdash schema get posts

모든 필드가 포함된 컬렉션을 표시합니다.

schema create <collection>

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

schema delete <collection>

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

--force가 설정되지 않은 한 확인을 요청합니다.

schema add-field <collection> <field>

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

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

미디어 항목을 관리합니다.

media list

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

media upload <file>

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

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

emdash search

콘텐츠 전체의 전체 텍스트 검색.

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

emdash taxonomy

분류체계와 용어를 관리합니다.

taxonomy list

npx emdash taxonomy list

taxonomy terms <name>

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

taxonomy add-term <taxonomy>

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

emdash menu

내비게이션 메뉴를 관리합니다.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

모든 항목이 포함된 메뉴를 반환합니다.

emdash export-seed

데이터베이스 스키마와 콘텐츠를 시드 파일로 내보냅니다. 로컬 SQLite 파일에서 직접 작동합니다.

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

옵션

출력 형식

내보낸 시드 파일에는 다음이 포함됩니다:

• 설정: 사이트 제목, 태그라인, 소셜 링크
• 컬렉션: 필드가 포함된 모든 컬렉션 정의
• 분류체계: 분류체계 정의 및 용어
• 메뉴: 항목이 포함된 내비게이션 메뉴
• 위젯 영역: 위젯 영역 및 위젯
• 콘텐츠 (요청된 경우): 이식성을 위한 $media 참조 및 $ref: 구문이 포함된 항목

emdash secrets generate

배포를 위한 EMDASH_ENCRYPTION_KEY를 생성합니다. 이 키는 플러그인 시크릿을 저장 시 암호화하는 데 사용됩니다.

npx emdash secrets generate

새 키를 stdout으로 출력합니다. 시크릿 저장소로 파이프하거나 --write로 개발 파일에 직접 작성하세요. 다음 명령은 키를 .dev.vars 또는 .env에 작성합니다:

npx emdash secrets generate --write .dev.vars
npx emdash secrets generate --write .env

--write는 --force 없이 기존 항목을 덮어쓰는 것을 거부합니다. 기존 암호화된 데이터가 있는 배포에서 키를 교체하면 해당 시크릿을 읽을 수 없게 되므로 이 보호는 의도적입니다.

emdash secrets fingerprint <key>

값을 노출하지 않고 키의 8자 지문(kid)을 출력합니다. 이는 CI에서 올바른 키가 배포되었는지 확인하는 데 유용합니다. 다음 명령은 키의 지문을 출력합니다:

npx emdash secrets fingerprint emdash_enc_v1_...

생성된 파일

.emdash/types.ts

emdash types 명령은 각 컬렉션에 대한 TypeScript 인터페이스를 생성합니다:

// 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;
}

.emdash/schema.json

명령은 도구용으로 원시 스키마 내보내기도 작성합니다:

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

환경 변수

패키지 스크립트

편의를 위해 package.json 스크립트로 CLI 명령을 추가하세요:

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

종료 코드