Tutoriais · Plugins

Instalar plugins pela linha de comando

Os comandos npx jarvis-ade plugins: add, search, info, init e validate.

Nesta página

Requisitos

Node.js 20 ou mais novo (o CLI não tem nenhuma dependência de runtime). O npx -y baixa e roda o CLI na hora, sem instalá-lo globalmente.
Para plugins add: o app Jarvis ADE precisa estar aberto. O CLI não escreve nas pastas de plugins: ele resolve o plugin e entrega a instalação ao app, que é quem guarda o estado dos plugins. Sem o app aberto, o comando termina com código 3 e mostra o caminho manual (veja abaixo).
Os demais comandos (search, info, init, validate) não precisam do app.

plugins add — instalar um plugin do Marketplace

Cada plugin aprovado mostra, na sua página, o comando de instalação. O formato é handle/slug — o handle do publicador e o identificador do plugin — com uma versão opcional depois de @:

terminal

npx -y jarvis-ade plugins add <handle>/<slug>
npx -y jarvis-ade plugins add meu-estudio/meu-plugin
npx -y jarvis-ade plugins add meu-estudio/meu-plugin@1.2.0 --yes   # só se 1.2.0 ainda for a última versão; sem perguntar
npx -y jarvis-ade plugins add meu-estudio/meu-plugin --dry-run     # só mostra, não instala

O que o comando faz, em ordem:

Resolve handle/slug no Marketplace e mostra o nome, a versão e a origem (pacote npm ou git). O Marketplace serve somente a última versão aprovada de cada plugin: o @versão não escolhe uma versão antiga, apenas confere. Se a última versão for outra, o CLI recusa em vez de instalar uma diferente — rode sem @versão para instalar a última. O handle e o slug são minúsculos, de 3 a 39 caracteres (letras, números e hífens internos).
Lê o ade.plugin.json do pacote sem instalar nada e lista o que o plugin adiciona, as configurações que ele vai pedir (marcando as obrigatórias e as guardadas como segredo) e se ele roda um processo em segundo plano.
Pergunta se você quer instalar (a não ser com --yes) e entrega a instalação ao app aberto. No fim, avisa o Marketplace para contar a instalação; se isso falhar, o comando não falha.

Opções de plugins add
Opção	O que faz
`--yes, -y`	Não pergunta a confirmação.
`--dry-run`	Resolve e mostra o que seria instalado, sem mudar nada (não precisa do app aberto).
`--json`	Resultado em JSON na saída padrão. Exige `--yes` ou `--dry-run`, porque uma execução em JSON não pode perguntar.
`--registry <url>`	Outro endereço do Marketplace (padrão: `https://jarvis-license.vidiio.net` ou a variável `JARVIS_MARKETPLACE_URL`). A opção tem prioridade sobre a variável.

Sem terminal interativo (um script, por exemplo) e sem --yes, o CLI não consegue perguntar e termina com erro de uso; passe --yes.

plugins search e plugins info

terminal

npx -y jarvis-ade plugins search clickup
npx -y jarvis-ade plugins search --category integrations --sort top-rated
npx -y jarvis-ade plugins info meu-estudio/meu-plugin

search [consulta] lista o Marketplace numa tabela (ID, nome, versão, nota, instalações e resumo). A coluna ID já é handle/slug: cole direto no plugins add. Sem consulta, lista os plugins do Marketplace. info <handle>/<slug> mostra os detalhes de um plugin (versão, nota, instalações, categoria, licença, repositório e site) e o comando de instalação.

Opções de search e info
Comando	Opção	O que faz
`search`	`--category <nome>`	Só esta categoria: `integrations`, `productivity`, `agents`, `devtools`, `data`, `themes`, `other`.
`search`	`--sort <ordem>`	Ordem da lista (padrão: `popular`): `popular`, `top-rated`, `recent`, `trending`.
`search, info`	`--json`	Imprime a resposta do Marketplace como JSON.
`search, info`	`--registry <url>`	Outro endereço do Marketplace (igual ao do add).

plugins init — criar um plugin novo

terminal

npx -y jarvis-ade plugins init meu-plugin --name "Meu Plugin"
cd meu-plugin && npx -y jarvis-ade plugins validate .

init [dir] cria um plugin sem dependências na pasta indicada (padrão: a pasta atual; é criada se não existir): ade.plugin.json, um sidecar (JSON Lines por stdin/stdout, como no protocolo), package.json, README, LICENSE e um workflow do GitHub Actions que publica no npm quando você cria uma tag v* (veja publicar no GitHub e no npm). Ao terminar, mostra os próximos passos: trocar OWNER/REPO no package.json e no ade.plugin.json, subir para o GitHub, criar o segredo NPM_TOKEN e enviar a tag.

Opções de plugins init
Opção	O que faz
`--name <nome>`	Nome de exibição (padrão: derivado do nome da pasta).
`--id <id>`	Id do plugin, em kebab-case (padrão: derivado do nome). Se não der para derivar um id válido, o comando pede o --id.
`--force`	Sobrescreve arquivos que já existem. Sem ela, o init se recusa a sobrescrever e lista os arquivos em conflito.

plugins validate — conferir antes de publicar

terminal

npx -y jarvis-ade plugins validate meu-plugin

validate [dir] (padrão: a pasta atual) confere o plugin como o Marketplace e o instalador do app vão conferir. A única opção é --json (resultado em JSON).

Erros (saída 1): ade.plugin.json fora do schema do app (id kebab-case, versão semver, tipos de configuração, ids duplicados, caminhos fora do plugin…), arquivos referenciados que não existem, repository do package.json ausente ou que não seja do GitHub e files que não inclui o ade.plugin.json (ou o que ele referencia).
Avisos (não falham o comando): dependencies, scripts preinstall/install/postinstall, a keyword jarvis-ade-plugin ausente e a versão do package.json diferente da do manifesto.

Rode antes de cada release: são as mesmas regras das checagens automáticas do Marketplace.

Variáveis de ambiente e opções globais

Variáveis de ambiente do CLI
Variável	Para quê
`JARVIS_MARKETPLACE_URL`	Endereço do Marketplace (padrão `https://jarvis-license.vidiio.net`). `--registry` tem prioridade.
`JARVIS_ADE_BRIDGE_URL`	Com `JARVIS_ADE_BRIDGE_TOKEN`: onde está o app aberto. Normalmente você não precisa definir: sem elas, o CLI lê o arquivo `bridge.json` que o app deixa na pasta de dados dele.
`NO_COLOR`	Desliga as cores (elas só aparecem num terminal).

Além das opções de cada comando, valem -h, --help (também em jarvis-ade plugins <comando> --help) e -v, --version.

Códigos de saída e o caminho manual

Códigos de saída do CLI
Código	Significado
`0`	Tudo certo.
`1`	Erro: plugin não encontrado, o app recusou a instalação, você cancelou a confirmação, o validate achou erros, o init não sobrescreveu arquivos.
`2`	Uso incorreto: comando ou opção inválidos, valor desconhecido em --sort ou --category (o CLI lista os válidos), id fora do formato handle/slug, --json sem --yes, sem terminal e sem --yes.
`3`	O Jarvis ADE não está aberto (ou não respondeu).

Sem o app aberto — ou sem o CLI

Com o código 3, ou se o app recusar a instalação, o CLI imprime a instalação manual: Plugins → Importar → npm <pacote> (ou git <url>) e um deep link para abrir a instalação no app:

deep link

jarvisade://plugins/install?handle=<handle>&slug=<slug>

O mesmo caminho manual serve para quem não quer usar o CLI: no app, Marketplace de Plugins → Instalados → Importar plugin, com a origem Pacote npm (o nome do pacote) ou URL git (o repositório). O instalador do app valida o manifesto e copia os arquivos, sem executar nada do plugin.

Procurando plugins para instalar? Navegue pelo Marketplace. Para publicar o seu, registre no Marketplace.