Referência da CLI

A CLI do EmDash oferece 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 e exportação e importação de sites.

Instalação

A CLI está incluída no pacote emdash. Instale-a com o seguinte comando:

npm install emdash

Execute os 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 de pacote dele, como pnpm dev. O script de pacote inicia o Astro; a integração do EmDash gera emdash-env.d.ts, enquanto o runtime executa as migrações pendentes na primeira requisição e, antes de a configuração ser concluída, aplica uma única vez o esquema e a estrutura do seed incluído. O conteúdo de exemplo do seed só é aplicado quando um administrador o escolhe no assistente de configuração.

Autenticação

Os comandos que se conectam a uma instância do 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 em ~/.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 pelo endpoint de bypass de desenvolvimento

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

Flags comuns

As flags de conexão variam conforme o comando. Os comandos agrupados abaixo significam todos os subcomandos desse grupo.

Saída

Quando um comando grava resultados em um terminal interativo, ele os formata para leitura. Os comandos listados acima com --json gravam JSON bruto quando a flag é definida ou quando a saída é redirecionada por pipe. O emdash migrate emite JSON apenas com a opção explícita --json.

Comandos

emdash init

Inicializa um banco de dados SQLite local a partir dos metadados do template em package.json. O comando executa as migrações do núcleo e, em seguida, aplica o arquivo SQL opcional indicado por emdash.schema. Execute emdash seed separadamente para os dados de seed em JSON.

npx emdash init [options]

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

emdash doctor

Verifica um banco de dados SQLite local em busca de problemas de conexão, migração, coleções, tabelas e usuários. Se o projeto tiver uma configuração do Wrangler, o comando também verifica se um Cron Trigger e um manipulador scheduled() do EmDash estão configurados juntos.

npx emdash doctor [options]

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

emdash seed

Valida ou aplica um seed em JSON a um banco de dados SQLite local. O comando usa o caminho posicional quando informado; caso contrário, .emdash/seed.json e, por fim, o caminho emdash.seed do package.json.

npx emdash seed [path] [options]

A aplicação de um seed executa primeiro as migrações do núcleo. Use --validate na integração contínua quando precisar verificar o arquivo sem abrir nem criar o banco de dados.

emdash migrate

Verifica ou aplica o conjunto de migrações do núcleo emitido por uma build do 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. Ele valida o manifesto em relação ao pacote EmDash instalado no projeto, resolve o executor local do projeto para o adaptador e imprime o destino imutável antes de qualquer SQL.

Opções

A aplicação e a liberação de bloqueio interativas e legíveis por pessoas pedem confirmação. A aplicação ou liberação de bloqueio não interativas, e toda aplicação ou liberação com --json, exigem a impressão digital exata exibida para o destino. Não existem down nem --dry-run; use --check para determinar se há trabalho a fazer.

Códigos de saída

Consulte Gerenciar as migrações do banco de dados do núcleo para ver a ordem do deploy, as credenciais do destino e o bloqueio de migração do D1.

emdash types

Gera tipos TypeScript a partir do esquema de uma instância do 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://example.com

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

Comportamento

1. Obtém o esquema da instância
2. Gera as definições de tipos TypeScript
3. Grava os tipos no arquivo de saída
4. Grava schema.json ao lado, para referência

emdash login

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

npx emdash login [options]

Opções

Comportamento

1. Descobre os endpoints de autenticação da instância
2. Se for localhost e não houver autenticação configurada, usa o bypass de desenvolvimento automaticamente
3. Caso contrário, inicia o OAuth Device Flow — exibe um código e abre o navegador. Depois que você insere o código, a página de administração lista as permissões que a CLI receberá e as permissões solicitadas que o seu papel não permite, antes de você aprovar.
4. Consulta a autorização e, em seguida, salva as credenciais em ~/.config/emdash/auth.json

As credenciais salvas são usadas automaticamente por todos os comandos seguintes que apontam para a mesma instância.

emdash logout

Faz logout e remove as credenciais armazenadas.

npx emdash logout [options]

Opções

emdash whoami

Mostra o usuário autenticado no momento.

npx emdash whoami [options]

Opções

Exibe e-mail, nome, papel, método de autenticação e URL da instância.

emdash content

Gerencia itens de conteúdo. Todos os subcomandos usam a API remota por meio do 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 os dados por exatamente uma das opções --data, --file ou --stdin. Novos itens são publicados automaticamente, a menos que --draft seja definido.

content update <collection> <id>

Você deve fornecer o token _rev de um get anterior para provar que viu o estado atual. Isso impede que você sobrescreva alterações que não viu. As etapas 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 estiver com a entrada aberta na administração, o servidor retorna 409 com o código ENTRY_LOCKED e uma mensagem que nomeia quem detém o bloqueio. Aguarde a pessoa terminar 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 logicamente o item de conteúdo (move para a lixeira).

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

content publish <collection> <id>

npx emdash content publish posts 01ABC123

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

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

Passe --override-lock para cancelar a publicação de uma entrada que outro editor deixou 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 deixou aberta.

content restore <collection> <id>

npx emdash content restore posts 01ABC123

Restaura um item de conteúdo que está na lixeira.

content translations <collection> <id>

Lista todas as traduções do grupo de tradução da entrada:

npx emdash content translations posts 01ABC123

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

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

Pede confirmação, a menos que --force seja 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 os índices de uso de mídia do conteúdo para uma coleção ou para todas as coleções de conteúdo. Use após importações ou gravações diretas no banco de dados, quando a cobertura de uso estiver desatualizada ou não for confiável.

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

Passe exatamente uma das opções --collection ou --all. O reparo remoto exige um usuário Admin e um token de autenticação com o escopo admin.

O reparo de todo o conteúdo é executado de forma síncrona e pode ser lento ou caro em sites grandes. Prefira --collection quando precisar reparar apenas uma coleção.

Os resultados estruturados de reparo complete, partial e stale encerram com 0; os resultados estruturados failed encerram com 1. Automações e tarefas cron devem usar --json e analisar status, failedSourceCount, skippedSourceCount e os resumos por coleção, em vez de tratar o código de saída 0 como cobertura completa.

emdash search

Pesquisa 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, do 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 possui, 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.

As mensagens de progresso sempre vão para o stderr, e o resultado vai para o stdout. Com --json, ou quando o stdout não é um terminal, o stdout contém apenas o resultado em JSON. Um erro é gravado 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 grava em um arquivo de pacote:

npx emdash site export --output site.emdash

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

O comando mantém seu 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; os arquivos já baixados são verificados e reutilizados, e o comando informa quantos reaproveitou. Ambos são excluídos quando o pacote é gravado. O arquivo de progresso é ignorado quando foi gravado para outra URL ou outra configuração de comentários, ou quando a exportação dele falhou ou expirou; o comando então inicia uma nova exportação.

O resultado em 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 localmente todo o arquivo do pacote e depois encontra a importação existente do mesmo pacote no site ou cria uma. Ele envia os arquivos que o site ainda não tem, executa a análise e imprime o plano: os digests do pacote e do plano, a contagem de registros, os tamanhos, a escolha de título e slogan, cada principal e seu mapeamento, as transformações em «Differences from the source site», os avisos e os bloqueios. Se uma importação anterior do mesmo pacote falhou, foi cancelada ou abandonada, ou expirou, o comando avisa e inicia uma nova importação.

As decisões são armazenadas com a importação, portanto uma execução posterior de --analyze sem flags de decisão as mantém. Cada alteração de decisões produz um novo digest de plano. As 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é a conclusão 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 em JSON de --analyze contém operationId, state, packageDigest, planDigest, executable e o plan completo. O resultado em JSON de --confirm contém operationId, state (complete), receipt e receiptDigestValid, que informa se o receiptDigest do recibo corresponde ao seu conteúdo.

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

cancel e abandon pedem confirmação. Passe --yes para ignorar a solicitação; ela também é ignorada com --json ou quando o stdout não é um terminal. Quando o stdin não é um terminal e nenhum dos dois casos se aplica, o comando falha com INVALID_ARGUMENT. Recusar a solicitação não altera nada e encerra com o código 1. O resultado em JSON de ambos é { operationId, state, operation }.

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

emdash export-seed

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

O banco de dados deve ter todas as migrações conhecidas pela versão instalada do EmDash. Se o comando informar migrações pendentes, execute npx emdash migrate e exporte novamente. Se o banco de dados foi migrado por uma versão mais recente do EmDash, atualize a versão instalada antes de exportar. A exportação abre o banco de dados somente para leitura e nunca aplica migrações por conta própria.

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

Opções

Formato de saída

O arquivo de seed exportado inclui:

• Configurações: título do site, slogan, links sociais
• Coleções: todas as definições de coleções com campos
• Tipos de bloco: cada versão mantida e o ponteiro da versão ativa de cada tipo
• Taxonomias: definições de taxonomias e termos
• Menus: menus de navegação com itens
• Redirecionamentos: regras de redirecionamento com status 301, 302, 307 ou 308
• Áreas de widgets: áreas de widgets e widgets
• Seções: blocos de conteúdo reutilizáveis
• Conteúdo (se solicitado): entradas com referências $media e a sintaxe $ref: para portabilidade

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

URLs de mídia

O 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 consiga acessar. Passe a URL pública do site de origem para gravar URLs absolutas:

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

O site deve servir sua mídia a partir 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 o emdash seed se recusa a baixar. Sem --media-base-url, as URLs $media são caminhos relativos ao site que o emdash seed ignora, deixando os campos vazios, e a exportação imprime um aviso no stderr.

Os campos de imagem e de arquivo, e os subcampos de imagem dos repeaters, são exportados como referências $media. As imagens dentro dos campos Portable Text mantêm o ID de mídia e a URL armazenados, que não são resolvidos em outro site.

emdash secrets

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

secrets generate

Gera uma EMDASH_ENCRYPTION_KEY para o seu deploy. A chave é usada para criptografar os segredos de plugins em repouso.

npx emdash secrets generate

Imprime a nova chave no stdout. Redirecione-a para o seu armazenamento de segredos ou grave-a diretamente no seu arquivo .env local com --write. O Wrangler e o plugin Vite da Cloudflare leem esse arquivo no desenvolvimento local. Um servidor Node independente não carrega o .env automaticamente; carregue-o pelo gerenciador de processos ou forneça a chave pelo ambiente do processo do servidor. O guia de deploy em 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 deploy com dados criptografados existentes, coloque a chave gerada antes do valor existente e separe as chaves com vírgula. O EmDash criptografa os novos valores com a primeira chave e usa as entradas mais antigas para descriptografar de acordo com o kid. Salve novamente cada segredo de plugin antes de remover uma chave antiga. Atualmente o EmDash não lista os IDs de chave ainda usados pelas configurações armazenadas, então mantenha um inventário das credenciais que você salvar novamente e verifique cada integração antes de remover a chave antiga dela.

secrets fingerprint <key>

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

npx emdash secrets fingerprint emdash_enc_v1_...

Arquivos gerados

emdash-env.d.ts

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

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

.emdash/types.ts

O comando emdash types obtém o esquema de uma instância em execução e grava interfaces TypeScript independentes. Use-o quando o esquema estiver em uma instância remota do EmDash, quando uma ferramenta precisar de um arquivo em um caminho personalizado ou quando o servidor de desenvolvimento local do Astro 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 coleção independentes e não amplia EmDashCollections. Ela só muda quando você executa emdash types; o emdash-env.d.ts usa aumento de módulo e é atualizado como parte do desenvolvimento local.

.emdash/schema.json

O comando também grava uma exportação bruta do 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 de pacote

Adicione os comandos mais usados 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. O emdash migrate também usa os códigos 2, 3, 4 e 130 para os resultados específicos listados na sua tabela de códigos de saída. O emdash site import usa 2 quando o plano de importação tem bloqueios.