CLI do Connect

Gerada da ajuda e das opções do pacote @zoppy-crm/connect-cli (Zoppy-crm/zoppy-connect@f1ae3a72be71).

A CLI é para quem tem TI própria e quer escrever e ajustar conectores no próprio editor, com versionamento, em vez de só pela conversa de construção. Ela segue as mesmas regras da tela: login com a conta da Zoppy, só MASTER ou ADMIN, e nada roda sem ensaio limpo e sem publicar com prévia e confirmação.

Instalar

O pacote fica no GitHub Packages da organização zoppy-crm e é privado: sua conta do GitHub precisa de acesso de leitura a ele. Precisa do Node 22 ou mais novo.

Crie no GitHub um token clássico (personal access token classic) com o escopo read:packages. O GitHub Packages não aceita tokens fine-grained.
Aponte o escopo @zoppy-crm para o registro e entre com o token como senha:

npm config set @zoppy-crm:registry https://npm.pkg.github.com
npm login --scope=@zoppy-crm --auth-type=legacy --registry=https://npm.pkg.github.com

Ou, direto no ~/.npmrc:

@zoppy-crm:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<seu token>

Instale e confira:

npm install -g @zoppy-crm/connect-cli
zoppy-connect --version

Entrar

zoppy-connect login

O login abre a Zoppy no navegador. Você entra com a sua conta (com a verificação em duas etapas, se estiver ligada), confere na tela de consentimento a permissão que a CLI pede (connect:build: “Construir, ensaiar e editar o código dos conectores pela CLI do Connect”) e autoriza. O navegador volta para um endereço local (127.0.0.1) que a CLI abre só durante o login. Se o navegador não abrir, use zoppy-connect login --no-browser e abra o endereço mostrado num navegador da mesma máquina: o retorno vai para 127.0.0.1.

Só entram usuários MASTER ou ADMIN de uma loja com o Connect liberado e com o termo do Connect aceito. Ao terminar, a CLI mostra a loja e o papel com que entrou.

O acesso fica num arquivo legível só pelo seu usuário, e se renova sozinho:

Sistema	Arquivo
Linux	`~/.config/zoppy-connect/credentials.json` (ou `$XDG_CONFIG_HOME/zoppy-connect`)
macOS	`~/Library/Application Support/zoppy-connect/credentials.json`
Windows	`%APPDATA%\zoppy-connect\credentials.json`

ZOPPY_CONNECT_CONFIG_DIR troca a pasta. zoppy-connect logout revoga o acesso na Zoppy e apaga o arquivo. Para usar a staging, entre com --api-url https://api-connect-staging.zoppy.com.br.

O ciclo de um conector

O conector é criado na tela do Connect (ou pela conversa); a CLI trabalha sobre um conector que já existe, pelo id dele.

1. Baixar: `init`

zoppy-connect init <connectorId>
cd <nome-do-conector>
npm install

A pasta recebe connector.ts, manifest.json (com $schema, para o editor validar), .zoppy-connect.json (o conector e a versão de onde a pasta partiu), package.json, tsconfig.json e .npmrc. O init também lista os segredos que ainda estão sem valor.

2. Editar com os tipos do SDK

O npm install da pasta instala o próprio @zoppy-crm/connect-cli, que traz os tipos do SDK e o schema do manifesto. O editor completa o ctx e aponta erros no manifesto:

import type { ConnectorContext, ConnectorResult } from '@zoppy-crm/connect-cli/sdk';

export default async function run(ctx: ConnectorContext): Promise<ConnectorResult> {
  return { done: true };
}

O import type some na compilação: o conector continua sem dependências.

3. Enviar: `push`

zoppy-connect push -m "o que mudou"

Cada push cria uma versão nova, com origem cli, por cima da versão de onde a pasta partiu. Se outra versão entrou depois (pela tela, pela conversa ou por outra pasta), o push é recusado e nada é gravado: baixe a mais nova em outra pasta (init <connectorId> --dir <pasta>), junte as suas mudanças e envie de novo. Depois do envio, a CLI avisa os hosts novos esperando aprovação e os segredos sem valor.

4. Ensaiar: `rehearse`

zoppy-connect rehearse --sample
zoppy-connect rehearse --full

O ensaio roda a versão mais nova de verdade, lendo dos sistemas, sem escrever em nenhum. A CLI espera o fim e mostra:

os contadores por objeto e o erro com a linha do código, se houver;
as requisições planejadas: as escritas (ctx.http.write) que o ensaio registrou e não mandou, com método, endereço e corpo;
as chamadas feitas como leitura com método de escrita (writesAsReads): POST, PUT, PATCH ou DELETE por ctx.http.request, para você conferir que não são escritas;
os problemas que impedem publicar, como connect.write_without_lookup (um POST que cria registros sem consultar antes se eles já existem; veja Como um conector funciona).

A amostra roda poucas fatias. Publicar exige um ensaio completo (--full) limpo da versão. Hosts novos e segredos sem valor fazem o ensaio ser recusado: aprove e preencha na tela e ensaie de novo.

5. Publicar: `publish`

zoppy-connect publish

A CLI mostra a prévia do que muda e pede o seu sim (s). Sem a confirmação, nada é publicado. --yes confirma sem perguntar, depois de mostrar a prévia. Um conector já ligado passa a rodar a versão nova no cron; um que não está ligado continua parado até ser ligado na tela ou pelo MCP.

6. Acompanhar: `runs`

zoppy-connect runs
zoppy-connect runs <runId>

Lista as execuções (gatilho, versão, situação) ou mostra uma inteira: contadores, erro, requisições planejadas, passos, quarentena e escritas enviadas. Veja Execuções e quarentena.

O que nunca passa pela CLI

Segredos. Os valores são preenchidos só no formulário da tela do conector. A CLI só diz quais faltam.
Criar conectores. O conector nasce na tela ou na conversa; a CLI trabalha sobre o id dele.
Aprovar hosts. Um host novo no manifesto espera aprovação na tela antes do ensaio.
Ligar, pausar, a primeira escrita e a quarentena. Ficam na tela, ou no MCP, sempre com prévia e confirmação.

Comandos

zoppy-connect: conectores do Zoppy Connect no seu editor

Uso: zoppy-connect <comando> [opções]

  login [--api-url <url>] [--issuer <url>] [--no-browser]
                                  entra com a sua conta da Zoppy (navegador, OAuth com PKCE)
  logout                          revoga o acesso e apaga desta máquina
  init <connectorId> [--dir <pasta>] [--force]
                                  baixa o código e o manifesto da versão mais nova
  push [-m, --message <resumo>] [--dir <pasta>]
                                  envia a pasta como versão nova (recusa se outra entrou antes)
  rehearse [--sample | --full] [--timeout <minutos>]
                                  ensaia a versão mais nova e mostra as requisições planejadas
  publish [-y, --yes]             mostra a prévia e publica depois da confirmação
  runs [<runId>] [--limit <n>]    lista as execuções ou mostra uma

  --connector <id> usa outro conector no lugar do da pasta; --dir <pasta> aponta a pasta.
  Segredos nunca passam pela CLI: preencha na tela do conector no Zoppy Connect.

`login`

Abre a Zoppy no navegador para você entrar e autorizar a CLI (OAuth com PKCE, retorno em 127.0.0.1). Confere a loja e o papel e guarda o acesso nesta máquina.

zoppy-connect login [--api-url <url>] [--issuer <url>] [--no-browser]

Opção	Tipo	Descrição
`--api-url`	texto	Endereço da API do Connect. Padrão: produção, ou `ZOPPY_CONNECT_API_URL`. Precisa ser https (http só na própria máquina).
`--issuer`	texto	Endereço do login, quando é diferente da API. Padrão: o da API, ou `ZOPPY_CONNECT_ISSUER_URL`.
`--no-browser`	bool	Não abre o navegador: mostra o endereço para você abrir num navegador desta mesma máquina, que recebe o retorno em `127.0.0.1`.

`logout`

Revoga o acesso na Zoppy e apaga o arquivo de acesso desta máquina.

zoppy-connect logout

`init`

Baixa o código e o manifesto da versão mais nova do conector numa pasta nova, com os arquivos para o editor. Sem versão ainda, começa de um modelo.

zoppy-connect init <connectorId> [--dir <pasta>] [--force]

Opção	Tipo	Descrição
`--dir`	texto	Pasta onde o conector é baixado. Padrão: uma pasta com o nome do conector.
`--force`	bool	Sobrescreve uma pasta que já tem um conector.

`push`

Envia o connector.ts e o manifest.json da pasta como uma versão nova (origem cli). Recusa sem gravar nada se outra versão entrou depois da que a pasta baixou.

zoppy-connect push [-m, --message <resumo>] [--dir <pasta>]

Opção	Tipo	Descrição
`--dir`	texto	Pasta do conector. Padrão: a pasta atual.
`-m, --message`	texto	Resumo do que mudou, que aparece no histórico de versões da tela.

`rehearse`

Ensaia a versão mais nova e espera o fim: contadores, erro com a linha do código, requisições planejadas, chamadas de leitura com método de escrita e problemas que impedem publicar.

zoppy-connect rehearse [--sample | --full] [--timeout <minutos>]

Opção	Tipo	Descrição
`--dir`	texto	Pasta do conector. Padrão: a pasta atual.
`--connector`	texto	Id de outro conector, no lugar do que a pasta aponta.
`--sample`	bool	Ensaio amostra, poucas fatias (o padrão).
`--full`	bool	Ensaio completo: lê a origem inteira. É o que libera publicar.
`--timeout`	texto	Quantos minutos esperar o fim do ensaio (padrão 30). Depois disso o ensaio continua e você acompanha com `runs`.

`publish`

Mostra a prévia do que muda e publica depois do seu sim. Publicar exige um ensaio completo limpo da versão.

zoppy-connect publish [-y, --yes]

Opção	Tipo	Descrição
`--dir`	texto	Pasta do conector. Padrão: a pasta atual.
`--connector`	texto	Id de outro conector, no lugar do que a pasta aponta.
`-y, --yes`	bool	Confirma sem perguntar, depois de mostrar a prévia (para scripts).

`runs`

Lista as execuções do conector, das mais novas para as mais antigas, ou mostra uma inteira quando recebe o id.

zoppy-connect runs [<runId>] [--limit <n>]

Opção	Tipo	Descrição
`--dir`	texto	Pasta do conector. Padrão: a pasta atual.
`--connector`	texto	Id de outro conector, no lugar do que a pasta aponta.
`--limit`	texto	Quantas execuções listar (padrão 20).

Códigos de saída

Código	Quando
0	Deu certo.
1	Falha: rede, ensaio que não passou, publicação recusada ou não confirmada.
2	Uso errado: opção, argumento ou manifesto inválido.
3	Sem login, ou acesso inválido, expirado ou revogado: rode `login`.
4	O papel, a loja ou o acesso não liberam a operação.
5	Conector ou execução não encontrados.
6	Conflito: outra versão entrou antes, ou já há uma execução rodando.

CLI do Connect

Instalar

Entrar

O ciclo de um conector

1. Baixar: init

2. Editar com os tipos do SDK

3. Enviar: push

4. Ensaiar: rehearse

5. Publicar: publish

6. Acompanhar: runs

O que nunca passa pela CLI

Comandos

login

logout

init

push

rehearse

publish

runs