Referência CLI

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

Instalação

A CLI está incluída no pacote emdash. Instale-a 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 se comunicam com uma instância EmDash em execução 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 armazenadas de ~/.config/emdash/auth.json (salvas por emdash login)
4. Bypass de desenvolvimento — se a URL for localhost e nenhum token estiver disponível, autentica automaticamente via endpoint de bypass de desenvolvimento

A maioria dos comandos aceita flags --url (padrão http://localhost:4321) e --token. Ao ter como alvo um servidor de desenvolvimento local, nenhum token é necessário.

Flags comuns

Estas flags estão disponíveis em todos os comandos remotos:

Saída

Quando stdout é um TTY, a CLI imprime resultados formatados com consola. Quando canalizado ou quando --json está definido, gera JSON bruto para 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 personalizada
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 estiver definido, gera tipos TypeScript de uma instância remota (URL de env EMDASH_URL ou emdash.url em package.json)
3. Inicia servidor de desenvolvimento Astro com EMDASH_DATABASE_URL definido

emdash types

Gera tipos TypeScript do esquema 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 personalizado
npx emdash types --output src/types/emdash.ts

Comportamento

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

emdash login

Faça login em uma instância EmDash usando OAuth Device Flow.

npx emdash login [options]

Opções

Comportamento

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

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

emdash logout

Faça logout e remova credenciais armazenadas.

npx emdash logout [options]

Opções

emdash whoami

Mostra o usuário atualmente autenticado.

npx emdash whoami [options]

Opções

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

emdash content

Gerencia 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 confirmar que você viu o estado atual antes de sobrescrevê-lo.

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 através de exatamente uma de --data, --file ou --stdin. Novos itens são publicados automaticamente, 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. Isso evita sobrescrever mudanças que você não viu. As seguintes etapas leem um item e depois o atualizam com esse token:

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

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

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

Exclui suavemente o item de conteúdo (move para 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

Gerencia 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 "Blog articles"

schema delete <collection>

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

Solicita confirmação, a menos que --force esteja definido.

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

Gerencia 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 "A sunset" --caption "Taken in Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

emdash search

Busca de texto completo em conteúdo.

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

emdash taxonomy

Gerencia 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

Gerencia menus de navegação.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Retorna o menu com todos os seus itens.

emdash export-seed

Exporta esquema de banco de dados e conteúdo como arquivo seed. Funciona diretamente em um arquivo SQLite local.

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

Opções

Formato de saída

O arquivo seed exportado inclui:

• Configurações: Título do site, slogan, 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 widgets: Áreas de widgets e widgets
• Conteúdo (se solicitado): Entradas com referências $media e sintaxe $ref: para portabilidade

emdash secrets generate

Gera uma EMDASH_ENCRYPTION_KEY para sua implantação. A chave é usada para criptografar segredos de plugins em repouso.

npx emdash secrets generate

Imprime a nova chave para stdout. Canalize-a para seu armazenamento de segredos ou escreva-a diretamente em um arquivo de desenvolvimento com --write. Os seguintes comandos escrevem a chave em .dev.vars ou .env:

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

--write recusa sobrescrever uma entrada existente sem --force. Substituir uma chave em uma implantação com dados criptografados existentes deixará esses segredos ilegíveis, portanto a proteção é intencional.

emdash secrets fingerprint <key>

Imprime a impressão digital de 8 caracteres (kid) de uma chave sem expor seu valor. Isso é útil em CI para verificar se a chave correta foi implantada. O seguinte comando imprime a impressão digital de uma chave:

npx emdash secrets fingerprint emdash_enc_v1_...

Arquivos gerados

.emdash/types.ts

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

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

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

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

Variáveis de ambiente

Scripts de package

Adicione os comandos CLI como scripts package.json para conveniência:

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

Códigos de saída