Referência da CLI

A CLI do EmDash fornece comandos para configuração do banco de dados, geração de tipos, criação e edição de conteúdo, gerenciamento de esquema, mídia, exportação e importação do site e desenvolvimento de plugins.

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 por brevidade.

Inicie seu site com o script do pacote, como pnpm dev. O script do pacote inicia o Astro; a integração EmDash gera emdash-env.d.ts, enquanto o runtime executa migrações pendentes na primeira solicitação e aplica o seed empacotado quando o banco está vazio e a configuração não foi concluída.

Autenticação

Comandos que se conectam a 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. Dev bypass — se a URL for localhost e nenhum token estiver disponível, autentica automaticamente via endpoint de dev bypass

Os comandos types, whoami, content, schema, media, search, taxonomy, menu e site conectam-se a uma instância em execução. Comandos de autenticação têm suas próprias opções de conexão. Ao mirar um servidor de desenvolvimento local, nenhum token é necessário.

Flags comuns

Flags de conexão variam por comando. Os comandos agrupados abaixo significam cada subcomando desse grupo.

Saída

Quando um comando escreve resultados em um terminal interativo, formata-os para leitura. Os comandos listados com --json acima escrevem JSON bruto quando a flag está definida ou a saída é piped. emdash migrate emite JSON somente com sua opção explícita --json.

Comandos

emdash init

Inicializa um banco SQLite local a partir dos metadados de template em package.json. O comando executa migrações principais e depois aplica o arquivo SQL opcional nomeado por emdash.schema. Execute emdash seed separadamente para dados seed JSON.

npx emdash init [options]

Sem --force, um banco inicializado permanece inalterado. Este comando abre um arquivo SQLite local diretamente; use emdash migrate para migrações D1, PostgreSQL, libSQL ou Hyperdrive gerenciadas pelo deployment.

emdash doctor

Verifica um banco SQLite local quanto a problemas de conexão, migração, collection, tabela e usuário. Se o projeto tiver configuração Wrangler, o comando também verifica se um Cron Trigger e um handler EmDash scheduled() estão configurados juntos.

npx emdash doctor [options]

O comando reporta cada verificação como aprovada, aviso ou falha e sai com código diferente de zero quando uma verificação falha.

emdash seed

Valida ou aplica um seed JSON a um banco SQLite local. O comando usa o caminho posicional quando fornecido, depois .emdash/seed.json, depois o caminho emdash.seed de package.json.

npx emdash seed [path] [options]

Aplicar um seed executa primeiro as migrações principais. Use --validate em integração contínua quando precisar verificar o arquivo sem abrir ou criar o banco.

emdash migrate

Verifica ou aplica o conjunto de migrações principais emitido por um build Astro.

npx emdash migrate [options]
npx emdash migrate --check [options]
npx emdash migrate --status --json [options]
npx emdash migrate --release-lock <id> [options]

Por padrão o comando descobre a raiz do projeto e lê .emdash/migrations.json. Valida o manifesto contra o pacote EmDash instalado do projeto, resolve o executor local ao projeto do adapter e imprime o alvo imutável antes de qualquer SQL.

Opções

Aplicação e liberação de lock legíveis e interativas pedem confirmação. Aplicação ou liberação de lock não interativa, e toda aplicação ou liberação de lock com --json, exigem a impressão digital exata impressa para o alvo. Não há down nem --dry-run; use --check para determinar se o trabalho é necessário.

Códigos de saída

Veja Manage Core Database Migrations para ordem de deployment, credenciais do alvo e o lock de migração D1.

emdash dev (obsoleto)

O comando legado inicializa e migra um banco SQLite local antes de iniciar o Astro. Esse comportamento não usa o adapter de banco configurado pelo site e é incompatível com o desenvolvimento Cloudflare D1. Invocações existentes agora imprimem um aviso de obsolescência antes de qualquer trabalho no banco.

emdash types

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

npx emdash types [options]

Opções

Exemplos

# 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

Comportamento

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

emdash login

Entra 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 for localhost e nenhuma autenticação estiver configurada, usa o dev bypass automaticamente
3. Caso contrário inicia OAuth Device Flow — exibe um código e abre o navegador. Após inserir o código, a página de administração lista as permissões que a CLI receberá e quaisquer permissões solicitadas que sua função não permite, antes de você aprovar.
4. Faz polling da autorização e salva as credenciais em ~/.config/emdash/auth.json

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

emdash logout

Sai e remove as credenciais armazenadas.

npx emdash logout [options]

Opções

emdash whoami

Mostra o usuário autenticado atual.

npx emdash whoami [options]

Opções

Exibe e-mail, 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 via exatamente um 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 alterações que você não viu. Os passos a seguir leem um item e depois o atualizam com esse token:

# 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"}'

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

Se alguém tiver a entrada aberta no admin, o servidor retorna 409 com código ENTRY_LOCKED e uma mensagem que nomeia o titular. Espere que termine, ou passe --override-lock. A mesma flag está disponível em content delete, content publish, content unpublish e content schedule.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Exclui soft o item de conteúdo (move para a lixeira).

Passe --override-lock para excluir uma entrada que outro editor tem aberta.

content publish <collection> <id>

npx emdash content publish posts 01ABC123

Passe --override-lock para publicar uma entrada que outro editor tem aberta.

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

Passe --override-lock para despublicar uma entrada que outro editor tem aberta.

content schedule <collection> <id>

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

Passe --override-lock para agendar uma entrada que outro editor tem aberta.

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Restaura um item de conteúdo da lixeira.

content translations <collection> <id>

Lista cada tradução no grupo de tradução da entrada:

npx emdash content translations posts 01ABC123

O resultado inclui ID, locale, slug, status de cada tradução e se é a entrada solicitada.

emdash schema

Gerencia collections e campos.

schema list

npx emdash schema list

Lista todas as collections.

schema get <collection>

npx emdash schema get posts

Mostra uma collection 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

Pede 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

media repair-usage

Repara índices de uso de mídia de conteúdo para uma collection ou para cada collection de conteúdo. Use após importações ou escritas diretas no banco quando a cobertura de uso estiver obsoleta ou não confiável.

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

Passe exatamente um de --collection ou --all. Reparação remota requer um usuário Admin e um token de autenticação com o escopo admin.

A reparação de todo o conteúdo é executada de forma síncrona e pode ser lenta ou cara em sites grandes. Prefira --collection quando precisar reparar apenas uma collection.

Resultados estruturados complete, partial e stale saem com 0; resultados estruturados failed saem com 1. Automação e jobs cron devem usar --json e analisar status, failedSourceCount, skippedSourceCount e resumos por collection em vez de tratar a saída 0 como cobertura completa.

emdash search

Busca de texto completo no 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 site

Exporta um site inteiro para um pacote de site .emdash e importa um pacote para um site vazio. O guia de transferência de site explica o que um pacote contém, o que o site de destino precisa e como ler um plano de importação.

O token precisa do escopo admin, que o token de emdash login tem, ou dos escopos de transferência correspondentes: transfer:export para exportar, e transfer:analyze e transfer:execute para importar. Um token sem eles falha com INSUFFICIENT_SCOPE.

Mensagens de progresso sempre vão para stderr, e o resultado para stdout. Com --json, ou quando stdout não é um terminal, stdout contém somente o resultado JSON. Um erro é escrito como { "error": { "code": "…", "message": "…" } }. Os códigos são os códigos de erro do servidor, mais INVALID_ARGUMENT para flags inválidas, PACKAGE_FILE_REQUIRED quando uma importação retomada ainda precisa do arquivo do pacote, e UNKNOWN_ERROR.

Os comandos repetem falhas de rede e respostas 408, 429 e 5xx com backoff.

site export

Exporta o site e o escreve em um arquivo de pacote:

npx emdash site export --output site.emdash

O comando inicia uma exportação, a avança até concluir e baixa o arquivo de pacote arquivo a arquivo. Verifica se o manifesto baixado corresponde ao digest do pacote da exportação e falha com TRANSFER_PACKAGE_DIGEST_MISMATCH antes de escrever qualquer coisa se não corresponder. Verifica o tamanho e o digest SHA-256 de cada arquivo antes de escrevê-lo. O pacote é escrito em <output>.partial e renomeado para o caminho de saída quando está completo.

O comando mantém o progresso em <output>.partial.json e os arquivos baixados no diretório <output>.parts/. Execute o mesmo comando novamente após uma interrupção para retomar a mesma exportação; arquivos já baixados são verificados e reutilizados, e o comando reporta quantos reutilizou. Ambos são excluídos quando o pacote é escrito. O arquivo de progresso é ignorado quando foi escrito para outra URL ou outra configuração de comentários, ou quando sua exportação falhou ou expirou; o comando então inicia uma nova exportação.

O resultado JSON contém operationId, output, packageDigest, files, bytes e resumed.

site import <file>

Importa um pacote em duas etapas. Analise-o primeiro e depois confirme o digest do plano que a análise imprimiu:

npx emdash site import site.emdash --analyze
npx emdash site import site.emdash --plan sha256:3f1c… --confirm

--analyze verifica o arquivo do pacote inteiro localmente, depois encontra a importação existente do mesmo pacote no site ou cria uma. Envia os arquivos que o site ainda não tem, executa a análise e imprime o plano: digests do pacote e do plano, contagens de registros, tamanhos, escolha de título e slogan, cada principal e seu mapeamento, as transformações em «Differences from the source site», os avisos e os bloqueadores. Se uma importação anterior do mesmo pacote falhou, foi cancelada ou abandonada, ou expirou, o comando avisa e inicia uma nova importação.

Decisões são armazenadas com a importação, de modo que uma execução posterior de --analyze sem flags de decisão as mantém. Cada mudança de decisões produz um novo digest do plano. Decisões não podem ser combinadas com --plan, e --plan não pode ser combinado com --analyze.

--plan <digest> --confirm executa a importação somente quando o digest corresponde ao plano atual, depois a avança até concluir e imprime o recibo. Se o plano mudou desde que você o revisou, o comando falha com TRANSFER_PLAN_DIGEST_MISMATCH; analise novamente e confirme o novo digest.

O resultado JSON de --analyze contém operationId, state, packageDigest, planDigest, executable e o plan completo. O resultado JSON de --confirm contém operationId, state (complete), receipt e receiptDigestValid, que reporta se o receiptDigest do recibo corresponde ao seu conteúdo.

Estas formas operam em uma importação pelo seu ID de operação:

cancel e abandon pedem confirmação. Passe --yes para pular o prompt; o prompt também é pulado com --json ou quando stdout não é um terminal. Quando stdin não é um terminal e nenhum dos dois se aplica, o comando falha com INVALID_ARGUMENT. Recusar o prompt não muda nada e sai com código 1. O resultado JSON de ambos é { operationId, state, operation }.

Os comandos de importação saem com estes códigos:

emdash plugin

Cria, valida, empacota e publica plugins EmDash. O login no marketplace é separado do login em uma instância CMS.

plugin init

Cria o scaffold de um plugin sandboxed ou nativo:

npx emdash plugin init --dir ./my-plugin --name my-plugin --format sandboxed

plugin bundle

Valida um plugin e cria seu tarball do marketplace:

npx emdash plugin bundle --dir ./my-plugin --outDir ./artifacts

plugin validate

Executa a mesma validação de plugin bundle sem criar um tarball:

npx emdash plugin validate --dir ./my-plugin

O --dir opcional seleciona o diretório do plugin e tem como padrão o diretório atual.

plugin publish

Envia um bundle ao marketplace e, por padrão, espera o resultado do processamento:

npx emdash plugin publish --tarball ./dist/my-plugin-1.0.0.tar.gz

Forneça --tarball, ou passe --build para compilar de --dir primeiro.

plugin login

Autentica no marketplace via GitHub device flow. --registry seleciona um marketplace diferente e tem como padrão https://marketplace.emdashcms.com.

npx emdash plugin login

plugin logout

Remove a credencial do marketplace salva. O --registry opcional deve identificar o mesmo marketplace usado no login.

npx emdash plugin logout

emdash export-seed

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

O banco deve ter cada migração conhecida pela versão EmDash instalada. Se o comando reportar migrações pendentes, execute npx emdash migrate e exporte novamente. Se o banco foi migrado por uma versão EmDash mais recente, atualize a versão instalada antes de exportar. A exportação abre o banco somente leitura e nunca aplica migrações por si mesma.

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

Opções

Formato de saída

O arquivo seed exportado inclui:

• Settings: Título do site, slogan, links sociais
• Collections: Todas as definições de collection com campos
• Block types: Cada versão retida e o ponteiro de versão ativa de cada tipo
• Taxonomies: Definições de taxonomia e termos
• Menus: Menus de navegação com itens
• Redirects: Regras de redirecionamento com status 301, 302, 307 ou 308
• Widget Areas: Áreas de widgets e widgets
• Sections: Blocos de conteúdo reutilizáveis
• Content (se solicitado): Entradas com referências $media e sintaxe $ref: para portabilidade

Entradas agendadas são exportadas como rascunhos, porque um seed não tem campo para horário de publicação. A exportação omite, com um aviso em stderr, tudo que emdash seed rejeitaria: regras de redirecionamento com status 410 ou 451, regras extras que compartilham uma origem (possível em bancos mais antigos) e sections cujo slug contém caracteres diferentes de letras minúsculas, dígitos e hífens.

URLs de mídia

emdash seed baixa cada URL $media e envia o arquivo para o armazenamento do site de destino, portanto precisa de uma URL http ou https absoluta que possa alcançar. Passe a URL pública do site de origem para escrever URLs absolutas:

npx emdash export-seed --with-content=all --media-base-url=https://example.com > seed.json

O site deve servir sua mídia de /_emdash/api/media/file/ sob essa URL enquanto o seed é aplicado, e a URL não deve apontar para localhost nem para um endereço de rede privada, dos quais emdash seed se recusa a baixar. Sem --media-base-url, as URLs $media são caminhos relativos ao site que emdash seed pula, deixando os campos vazios, e a exportação imprime um aviso em stderr.

Campos de imagem e arquivo, e subcampos de imagem de repeaters, são exportados como referências $media. Imagens dentro de campos Portable Text mantêm o ID de mídia e a URL armazenados, que não se resolvem em um site diferente.

emdash secrets

Gera e inspeciona a chave usada para criptografar segredos de plugins.

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. Encaminhe-a por pipe para seu armazenamento de segredos, ou escreva-a direto no arquivo .env local com --write. Wrangler e o plugin Vite Cloudflare leem esse arquivo no desenvolvimento local. Um servidor Node independente não carrega .env automaticamente; carregue-o pelo gerenciador de processos ou forneça a chave pelo ambiente de processo do servidor. O guia de deployment Node.js mostra o comando local.

npx emdash secrets generate --write .env

--write se recusa a sobrescrever uma entrada existente sem --force. Para rotacionar um deployment com dados criptografados existentes, anteponha a chave gerada ao valor existente e separe as chaves com vírgula. EmDash criptografa novos valores com a primeira chave e usa entradas mais antigas para descriptografia por kid. Salve novamente cada segredo de plugin antes de remover uma chave antiga. EmDash atualmente não lista os IDs de chave ainda usados por configurações armazenadas, então mantenha um inventário das credenciais que você regrava e verifique cada integração antes de remover sua chave antiga.

secrets fingerprint <key>

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

npx emdash secrets fingerprint emdash_enc_v1_...

emdash auth (obsoleto)

auth secret

Gera um valor legado EMDASH_AUTH_SECRET:

npx emdash auth secret

Instalações existentes podem manter esta variável para preservar hashes estáveis de IP de comentadores. Ela não criptografa segredos de plugins.

Arquivos gerados

emdash-env.d.ts

A integração Astro gera emdash-env.d.ts na raiz do projeto quando o servidor de desenvolvimento local inicia. Atualiza o arquivo após alterações de esquema feitas pelo site de desenvolvimento em execução. As declarações aumentam EmDashCollections, de modo que chamadas como getEmDashCollection("posts") inferem os campos definidos no banco local.

Este arquivo é automático e pertence ao fluxo de desenvolvimento Astro local. Você não precisa executar emdash types para criá-lo.

.emdash/types.ts

O comando emdash types busca o esquema de uma instância em execução e escreve interfaces TypeScript independentes. Use-o quando o esquema estiver em uma instância EmDash remota, quando ferramentas precisarem de um arquivo em um caminho personalizado, ou quando o servidor de desenvolvimento Astro local não estiver em execução:

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

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	slug: string | null;
	status: string;
	title: string;
	content?: PortableTextBlock[];
	createdAt: Date;
	updatedAt: Date;
	publishedAt: Date | null;
	bylines?: ContentBylineCredit[];
	terms?: Record<string, TaxonomyTerm[]>;
}

A saída remota contém interfaces de collection independentes e não aumenta EmDashCollections. Só muda quando você executa emdash types; emdash-env.d.ts usa augmentation de módulos e atualiza como parte do desenvolvimento local.

.emdash/schema.json

O comando também escreve uma exportação bruta de esquema chamada schema.json ao lado da saída TypeScript selecionada. Com o caminho de saída padrão, o arquivo é .emdash/schema.json:

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

Variáveis de ambiente

Scripts do pacote

Adicione comandos comuns como scripts do package.json por conveniência:

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

Códigos de saída gerais

A maioria dos comandos usa 0 para sucesso e 1 para erro. emdash migrate também usa os códigos 2, 3, 4 e 130 para os resultados específicos listados em sua tabela de códigos de saída. emdash site import usa 2 quando o plano de importação tem bloqueadores.