Referência CLI

O CLI do EmDash fornece comandos para gerenciar uma instância EmDash CMS — configuração de banco de dados, geração de tipos, CRUD de conteúdo, gerenciamento de schema, mídia e mais.

Instalação

O CLI está incluído no pacote emdash. Instale com o seguinte comando:

npm install emdash

Execute comandos com npx emdash ou adicione scripts ao package.json. O binário também está disponível como em para brevidade.

Autenticação

Comandos que usam o cliente remoto compartilhado resolvem a autenticação nesta ordem:

1. Flag --token — token explícito na linha de comando
2. Variável de ambiente EMDASH_TOKEN
3. Credenciais salvas de ~/.config/emdash/auth.json (salvas por emdash login)
4. Bypass de desenvolvimento — se a URL é localhost e nenhum token está disponível, autentica automaticamente via endpoint de bypass dev

Esses comandos aceitam os flags --url (de EMDASH_URL, com fallback para http://localhost:4321) e --token. Os comandos de autenticação têm suas próprias opções de conexão. Ao apontar para um servidor de desenvolvimento local, nenhum token é necessário.

Flags comuns

Esses flags estão disponíveis em comandos que usam o cliente remoto compartilhado:

Saída

Quando stdout é um TTY, o CLI imprime resultados formatados com consola. Quando em pipe ou quando --json está definido, produz JSON bruto em stdout — adequado para jq ou outras ferramentas.

Comandos

emdash dev

Inicia o servidor de desenvolvimento com configuração automática do banco de dados.

npx emdash dev [options]

Opções

Exemplos

# Iniciar servidor de desenvolvimento
npx emdash dev

# Porta customizada
npx emdash dev --port 3000

# Gerar tipos do remoto antes de iniciar
npx emdash dev --types

Comportamento

1. Verifica e executa migrações de banco de dados pendentes
2. Se --types está definido, gera tipos TypeScript de uma instância remota (URL da variável EMDASH_URL ou emdash.url no package.json)
3. Inicia o servidor de desenvolvimento Astro com EMDASH_DATABASE_URL definido

emdash types

Gera tipos TypeScript do schema de uma instância EmDash em execução.

npx emdash types [options]

Opções

Exemplos

# Gerar tipos do servidor de desenvolvimento local
npx emdash types

# Gerar de instância remota
npx emdash types --url https://my-site.pages.dev

# Caminho de saída customizado
npx emdash types --output src/types/emdash.ts

Comportamento

1. Busca o schema da instância
2. Gera as definições de tipos TypeScript
3. Escreve os tipos no arquivo de saída
4. Escreve um schema.json ao lado para referência

emdash login

Faz login em uma instância EmDash usando OAuth Device Flow.

npx emdash login [options]

Opções

Comportamento

1. Descobre os endpoints de autenticação da instância
2. Se localhost e nenhuma auth configurada, usa automaticamente o bypass de desenvolvimento
3. Caso contrário, inicia OAuth Device Flow — mostra um código e abre o navegador
4. Pesquisa a autorização, depois salva credenciais em ~/.config/emdash/auth.json

Credenciais salvas são usadas automaticamente por todos os comandos subsequentes direcionados à mesma instância.

emdash logout

Faz logout e remove as credenciais salvas.

npx emdash logout [options]

emdash whoami

Mostra o usuário autenticado atual.

npx emdash whoami [options]

Mostra email, nome, papel, método de autenticação e URL da instância.

emdash content

Gerenciar itens de conteúdo. Todos os subcomandos usam a API remota via EmDashClient.

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

A resposta inclui um token _rev. Passe-o para content update para provar que viu o estado atual antes de sobrescrever.

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

Forneça dados via exatamente uma das opções --data, --file ou --stdin. Novos itens são auto-publicados a menos que --draft esteja definido.

content update <collection> <id>

Você deve fornecer o token _rev de um get anterior para provar que viu o estado atual:

# 1. Ler o item, anotar o _rev
npx emdash content get posts 01ABC123

# 2. Atualizar com o _rev do passo 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Atualizado"}'

Se o item mudou desde seu get, o servidor retorna 409 Conflict — releia e tente novamente.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Exclusão suave do item de conteúdo (movido para a lixeira).

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

Restaura um item de conteúdo excluído.

emdash schema

Gerenciar coleções e campos.

schema list

npx emdash schema list

Lista todas as coleções.

schema get <collection>

npx emdash schema get posts

Mostra uma coleção com todos os seus campos.

schema create <collection>

npx emdash schema create articles --label Articles
npx emdash schema create articles --label Articles --label-singular Article --description "Artigos do blog"

schema delete <collection>

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

schema add-field <collection> <field>

npx emdash schema add-field posts body --type portableText --label "Conteúdo do corpo"
npx emdash schema add-field posts featured --type boolean --required

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

Gerenciar itens de mídia.

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 "Um pôr do sol" --caption "Tirada em Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

media repair-usage

Repara os índices de uso de mídia do conteúdo para uma coleção ou todas as coleções de conteúdo.

npx emdash media repair-usage --collection posts
npx emdash media repair-usage --all
npx emdash media repair-usage --all --json

emdash search

Pesquisa de texto completo em todo o conteúdo.

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

emdash taxonomy

Gerenciar taxonomias e termos.

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

Gerenciar menus de navegação.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

emdash export-seed

Exportar schema do banco de dados e conteúdo como arquivo seed.

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

Opções

Formato de saída

O arquivo seed exportado inclui:

• Configurações: Título do site, tagline, links sociais
• Coleções: Todas as definições de coleção com campos
• Taxonomias: Definições de taxonomia e termos
• Menus: Menus de navegação com itens
• Áreas de widget: Áreas de widget e widgets
• Conteúdo (se solicitado): Entradas com referências $media e sintaxe $ref:

emdash secrets generate

Gera um EMDASH_ENCRYPTION_KEY para seu deployment. A chave é usada para criptografar segredos de plugins em repouso.

npx emdash secrets generate

Imprime a nova chave em stdout. Redirecione para seu armazenamento de segredos ou escreva diretamente no seu arquivo .env local com --write:

npx emdash secrets generate --write .env

emdash secrets fingerprint <key>

Imprime a impressão digital de 8 caracteres (kid) de uma chave sem expor seu valor:

npx emdash secrets fingerprint emdash_enc_v1_...

Arquivos gerados

.emdash/types.ts

O comando emdash types gera interfaces TypeScript para cada coleção:

// Gerado pelo CLI EmDash
// Não edite manualmente - execute `emdash types` para regenerar

import type { PortableTextBlock } from "emdash";

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

.emdash/schema.json

O comando também escreve uma exportação de schema bruto para ferramentas:

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

Variáveis de ambiente

Scripts do pacote

Adicione comandos do CLI como scripts do package.json:

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

Códigos de saída