Referência da CLI

A CLI do EmDash oferece comandos para gerir uma instância do EmDash CMS — configuração da base de dados, geração de tipos, CRUD de conteúdo, gestão de esquema, media e muito mais.

Instalação

A CLI está incluída no pacote emdash:

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.

Autenticação

Os comandos que comunicam com uma instância EmDash em execução (tudo exceto init, seed, export-seed e auth secret) resolvem a autenticação nesta ordem:

1. Sinalizador --token — token explícito na linha de comando
2. Variável de ambiente EMDASH_TOKEN
3. Credenciais guardadas em ~/.config/emdash/auth.json (gravadas por emdash login)
4. Bypass de desenvolvimento — se o URL for localhost e não houver token, autentica automaticamente via o endpoint de bypass de desenvolvimento

A maioria dos comandos aceita os sinalizadores --url (predefinição http://localhost:4321) e --token. Ao apontar para um servidor de desenvolvimento local, não é necessário token.

Sinalizadores comuns

Estes sinalizadores estão disponíveis em todos os comandos remotos:

Saída

Quando o stdout é um TTY, a CLI formata os resultados com consola. Quando é redirecionado por pipe ou quando --json está definido, emite JSON bruto no stdout — adequado para jq ou outras ferramentas.

Comandos

emdash init

Inicializa a base de dados com o esquema principal e dados de modelo opcionais.

npx emdash init [options]

Opções

Comportamento

1. Lê a configuração emdash do package.json
2. Cria o ficheiro da base de dados se necessário
3. Executa migrações principais (cria tabelas de sistema)
4. Executa schema.sql do modelo se estiver configurado
5. Executa seed.sql do modelo se estiver configurado

emdash dev

Inicia o servidor de desenvolvimento com configuração automática da base de dados.

npx emdash dev [options]

Opções

Exemplos

# Start dev server
npx emdash dev

# Custom port
npx emdash dev --port 3000

# Generate types from remote before starting
npx emdash dev --types

Comportamento

1. Verifica e executa migrações pendentes da base de dados
2. Se --types estiver definido, gera tipos TypeScript a partir 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 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. Obtém o esquema da instância
2. Gera definições de tipos TypeScript
3. Escreve os tipos no ficheiro de saída
4. Escreve schema.json ao lado para referência

emdash login

Inicia sessão numa instância EmDash com OAuth Device Flow.

npx emdash login [options]

Opções

Comportamento

1. Descobre os endpoints de autenticação na 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 — mostra um código e abre o browser
4. Aguarda a autorização por polling e guarda as credenciais em ~/.config/emdash/auth.json

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

emdash logout

Termina a sessão e remove as credenciais guardadas.

npx emdash logout [options]

Opções

emdash whoami

Mostra o utilizador autenticado atual.

npx emdash whoami [options]

Opções

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

emdash content

Gestão de 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 a content update para provar que viu o que está a 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 os dados com exatamente uma de --data, --file ou --stdin.

content update <collection> <id>

Como um editor de ficheiros que exige ler antes de escrever — tem de fornecer o token _rev de um get anterior para provar que viu o estado atual. Isto evita sobrescrever acidentalmente alterações que ainda não viu.

# 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 tiver mudado desde o seu get, o servidor devolve 409 Conflict — volte a ler e tente de novo.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

Elimina em soft o item de conteúdo (move para o lixo).

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 do lixo.

emdash schema

Gestão de 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 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

Gestão de itens de 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

Pesquisa de texto completo no conteúdo.

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

emdash taxonomy

Gestão de 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

Gestão de menus de navegação.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

Devolve o menu com todos os seus itens.

emdash seed

Aplica um ficheiro seed à base de dados. Este comando trabalha diretamente num ficheiro SQLite local (não precisa de servidor em execução).

npx emdash seed [path] [options]

Argumentos

Opções

Resolução do ficheiro seed

O comando procura ficheiros seed nesta ordem:

1. Argumento posicional (se fornecido)
2. .emdash/seed.json (convenção)
3. Caminho do campo emdash.seed no package.json

emdash export-seed

Exporta o esquema e o conteúdo da base de dados como ficheiro seed. Trabalha diretamente num ficheiro SQLite local.

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

Opções

Formato de saída

O ficheiro seed exportado inclui:

• Definições: título do site, slogan, ligações 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 pedido): entradas com referências $media e sintaxe $ref: para portabilidade

emdash auth secret

Gera um segredo de autenticação seguro para o seu deployment.

npx emdash auth secret

Emite um segredo aleatório adequado para EMDASH_AUTH_SECRET.

Ficheiros gerados

.emdash/types.ts

Interfaces TypeScript geradas por emdash types:

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

Exportação bruta do esquema para ferramentas:

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

Variáveis de ambiente

Scripts no package.json

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

Códigos de saída