Ferramenta de linha de comando do Cordova (CLI) – Manual de referência

Este capítulo funciona como manual de referência. Não é necessário ler tudo, basta consultar quando precisar.

Sintaxe da CLI

cordova <command> [opções] -- [parâmetros específicos da plataforma]Code language: CSS (css)

Lista de comandos globais

Podem ser executados sem acessar a pasta do projeto Cordova

Comando	Descrição
create	Criar um novo projeto
help	Exibir a documentação de ajuda de um comando específico
config	Definir, consultar, remover, editar e listar as configurações globais do Cordova

Lista de comandos de projeto

Devem ser executados na pasta raiz de um projeto Cordova válido

Comando	Descrição
info	Exibir informações do ambiente do projeto
requirements	Verificar e listar todas as dependências necessárias para a plataforma
platform	Gerenciar plataformas do projeto (Android/iOS/Browser, etc.)
plugin	Gerenciar plugins do projeto
prepare	Copiar arquivos de recursos para as pastas de cada plataforma, preparando a compilação
compile	Compilar o projeto para a plataforma definida
build	Gerar o aplicativo (equivalente a prepare + compile)
clean	Remover arquivos temporários gerados durante a compilação da plataforma
run	Executar o aplicativo (executa internamente prepare + compile + implantação e inicialização)
serve	Iniciar um servidor web local para visualizar os recursos web (executa prepare internamente)

Opções gerais (suportadas por todos os comandos da CLI)

Parâmetro	Descrição
-d / –verbose	Exibir logs detalhados. Se você chamar o cordova-cli em código Node.js, é possível escutar os eventos log e warn para receber registros: cordova.on('log', ()=>{})
-v / –version	Mostrar a versão atual da CLI do Cordova
–nohooks	Bloquear a execução de scripts hook; aceita filtros por expressões regulares

Explicação dos parâmetros específicos de plataforma

Alguns comandos aceitam parâmetros customizados por plataforma (platformOpts).
Utilize -- como separador: tudo antes de -- é interpretado pela CLI do Cordova, todos os parâmetros após -- são encaminhados diretamente às ferramentas de build nativas da plataforma correspondente.

---

Exemplos de uso da CLI

Fluxo de trabalho completo de demonstração:

1. Criar o projeto
2. Instalar o plugin de câmera
3. Adicionar a plataforma Android
4. Compilar e executar para Android
5. Gerar pacote de lançamento com parâmetros de assinatura Android

# Criar projeto
cordova create myApp com.foxdevelop.myApp myApp
cd myApp

# Adicionar plugin de câmera
cordova plugin add cordova-plugin-camera

# Adicionar plataforma Android
cordova platform add android

# Verificar dependências do ambiente de compilação Android
cordova requirements android

# Compilar para Android (exibir logs detalhados)
cordova build android --verbose

# Executar o app em dispositivo ou emulador
cordova run android

# Gerar pacote Release e informar parâmetros de assinatura
cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykeyCode language: PHP (php)

---

Descrição detalhada de cada comando

cordova create

Cria a estrutura de pastas de um projeto Cordova.
Sintaxe:

cordova create path [id do pacote [nome do aplicativo]] [opções]Code language: JavaScript (javascript)

Parâmetros

Valor	Descrição
path	Pasta do projeto (não deve existir previamente, a CLI cria automaticamente)
id	Identificador do pacote, valor padrão: org.apache.cordova.hellocordova Formato de domínio invertido, corresponde ao widget id do config.xml; usado para gerar o nome de pacote Java, recomenda-se configurar corretamente
name	Nome visível do aplicativo, valor padrão: Hello Cordova Corresponde ao campo name do config.xml e se torna o nome da classe do projeto nativo

Opções

• --template: Criar projeto usando template personalizado local, hospedado no NPM ou GitHub

cordova create myapp com.mycompany.myteam.myapp MyAppCode language: CSS (css)

cordova platform

Gerenciar plataformas: adicionar, remover, atualizar e listar. Adicionar ou excluir plataformas altera a pasta platforms do projeto.

cordova {platform | platforms} [
    add <especificação da plataforma> [...] {--save | link=<caminho> } |
    {remove | rm}  plataforma [...] {--save}|
    {list | ls}  |
    update ]Code language: HTML, XML (xml)

Subcomandos e parâmetros

Subcomando	Parâmetro	Descrição
add <especificação da plataforma>		Adicionar plataforma
	–nosave	Não gravar as informações da plataforma no config.xml / package.json após instalação
	–link=	Criar link simbólico em vez de copiar arquivos ao usar código fonte local da plataforma (para desenvolvimento e depuração)
remove <plataforma>		Remover plataforma
	–nosave	Excluir a plataforma, mas não apagar o registro dentro do config.xml / package.json
update <plataforma>		Atualizar versão da plataforma
	–save	Atualizar a versão registrada da plataforma no config.xml
list / ls		Listar todas as plataformas instaladas e disponíveis

Formato de especificação da plataforma <platform-spec>

plataforma[@número-da-versão] | caminho local | endereço Git[#branch/tag/commit]Code language: PHP (php)

• platform: nome da plataforma android / ios / browser / electron
• version: versão semântica semver, exemplo ^13.0.0
• path: pasta local com código fonte da plataforma ou arquivo tar compactado
• url: endereço do repositório Git
• commit-ish: definir branch, tag ou hash do commit; se omitido, usa master por padrão

Plataformas suportadas

android、browser、electron、ios

# Adicionar Android + iOS e salvar nos arquivos de configuração
cordova platform add android ios

# Adicionar plataforma Android com versão definida
cordova platform add android@^13.0.0

# Instalar plataforma do repositório Git com uma tag específica
cordova platform add https://github.com/myfork/cordova-android.git#13.0.0

# Instalar plataforma a partir de pasta local
cordova platform add ../android

# Remover plataforma Android
cordova platform rm android

# Listar todas as plataformas
cordova platform lsCode language: PHP (php)

cordova plugin

Gerenciar os plugins do projeto

cordova {plugin | plugins} [
    add <especificação do plugin> [..] {--searchpath=<pasta> | --noregistry | --link | --save | --force} |
    {remove | rm} {<id-do-plugin> | <nome>} --save |
    {list | ls}
]Code language: HTML, XML (xml)

Parâmetros dos subcomandos

Subcomando	Parâmetro	Descrição
add <especificação do plugin>		Adicionar plugin
	–searchpath <pasta>	Buscar plugins prioritariamente nesta pasta; separador de múltiplos caminhos: ; no Windows, : no Linux/Mac
	–noregistry	Não baixar plugins do repositório oficial npm
	–link	Criar link simbólico ao instalar de uma pasta local de plugin (desenvolvimento e depuração de plugins)
	–nosave	Não gravar entradas no config.xml / package.json
	–force	Forçar sobrescrita de arquivos em conflito (incluído na versão 6.1)
remove		Remover plugin
	–nosave	Excluir o plugin mas manter o registro nos arquivos de configuração
list / ls		Listar plugins instalados

Formato de especificação do plugin <plugin-spec>

[@scope/]id-do-plugin[@versão] | pasta local | endereço Git[#commit][:subpasta]Code language: PHP (php)

Ordem de prioridade para resolução de plugins (maior para menor)

1. Plugin e versão informados explicitamente na linha de comando
2. Dados de plugin salvos em config.xml / package.json
3. A última versão compatível com o projeto disponível no npm (o package.json do plugin declara dependência do Cordova)
4. Última versão publicada do plugin no npm

# Instalar plugins de câmera e arquivos, buscando primeiro em ../plugins
cordova plugin add cordova-plugin-camera cordova-plugin-file --searchpath ../plugins

# Instalar com versão específica
cordova plugin add cordova-plugin-camera@^2.0.0

# Instalar plugin a partir de pasta local
cordova plugin add ../cordova-plugin-camera

# Remover plugin
cordova plugin rm cordova-plugin-camera

# Listar plugins
cordova plugin lsCode language: PHP (php)

Informações sobre conflitos de plugins

Alguns plugins alteram arquivos de configuração nativos usando a tag edit-config do plugin.xml.
Quando vários plugins tentam modificar o mesmo nó XML, ocorre um conflito; a CLI bloqueia a instalação por padrão.
Formas de resolver:

1. Modificar o plugin.xml dos plugins para evitar alterar o mesmo nó (recomendado)
2. Forçar instalação com --force (⚠️ Risco: sobrescreve alterações de outros plugins e pode causar mau funcionamento)

cordova prepare

Sincroniza as configurações do config.xml com os arquivos manifest nativos de cada plataforma; copia ícones, telas de abertura e recursos dos plugins, para que o projeto atenda aos requisitos de compilação do SDK nativo.

cordova prepare [nomes-de-plataformas...]Code language: CSS (css)

Se nenhuma plataforma for definida, todas serão processadas.

cordova compile

Executa apenas a compilação, não executa o prepare. Normalmente se usa diretamente o comando build, este comando é empregado principalmente em cenários de extensão via hooks.

cordova compile [plataformas...]
    [--debug | --release]
    [--device | --emulator | --target=<nome>]
    [--buildConfig=<arquivo>]
    [-- parâmetros-da-plataforma]Code language: CSS (css)

cordova build

Equivale a prepare + compile e gera o pacote do aplicativo.

cordova build [plataformas...]
    [--debug | --release]
    [--device | --emulator]
    [--buildConfig=<arquivo-de-configuração>]
    [-- parâmetros-da-plataforma]Code language: CSS (css)

Parâmetro	Descrição
–debug	Pacote de depuração
–release	Pacote de lançamento oficial
–device	Compilar pacote para dispositivo físico
–emulator	Compilar pacote para arquiteturas de emulador
–buildConfig	Definir arquivo de configuração de build, por padrão build.json na raiz do projeto, frequentemente usado para configurações de assinatura

cordova build android --release --buildConfig=build.json
cordova build android --release -- --keystore="app.keystore" --alias=key0Code language: JavaScript (javascript)

cordova run

Executa prepare → build, implanta o aplicativo em dispositivo físico ou emulador e o inicializa.

cordova run [plataformas...]
    [--list | --debug | --release]
    [--noprepare]
    [--nobuild]
    [--device | --emulator | --target=<nome>]
    [--buildConfig=<arquivo>]
    [-- parâmetros-da-plataforma]Code language: CSS (css)

Parâmetro	Descrição
–list	Listar todos os dispositivos físicos e emuladores disponíveis
–noprepare	Ignorar o passo prepare (versão 6.2 ou superior)
–nobuild	Ignorar compilação e implantar diretamente o pacote existente
–target	Definir nome do emulador ou dispositivo; consulte os nomes com o parâmetro --list

Exemplos:

# Listar dispositivos
cordova run android --list
# Executar em um emulador específico
cordova run android --target=Nexus_5_API_23_x86
# Executar sem recompilar
cordova run android --nobuildCode language: PHP (php)

cordova emulate

Alias de cordova run --emulator, inicializa o aplicativo apenas em um emulador.

cordova clean

Remove todos os arquivos temporários gerados na compilação de cada plataforma

cordova clean android

cordova requirements

Verifica todas as dependências de ambiente necessárias para a plataforma (JDK, Android SDK, Xcode, etc.)

cordova requirements android

Retorna código de saída 0 se todas as dependências estiverem presentes, valor diferente caso faltem itens. Comumente usado para validação de ambiente em builds automáticos.

cordova info

Exibe todas as informações de ambiente, plataformas e plugins; indispensável ao enviar relatórios de bugs.

cordova info

cordova serve

Inicia um servidor web local para visualizar os recursos da pasta www, porta padrão 8000

cordova serve 8080
# Endereço de acesso: http://127.0.0.1:8080/android/wwwCode language: PHP (php)

cordova help

Consultar ajuda de um comando

cordova help build
cordova build -h

cordova config

Gerenciar configurações globais do Cordova

cordova config ls                # Listar todas as configurações
cordova config set save-exact true
cordova config get save-exact
cordova config delete save-exact
cordova config editCode language: PHP (php)

Ferramenta de linha de comando do Cordova (CLI) – Manual de referência