PT EN

Visão geral da CLI

Como instalar a CLI, iniciar sessão com conta ou chave de API, escolher contexto e perfil, ler a saída em JSON e interpretar os códigos de saída.

A gotactl é um cliente de linha de comandos para a API pública. Serve a quem trabalha no terminal (consultar clientes, facturas e pagamentos, testar webhooks em sandbox) e a automações em CI, que se autenticam com uma chave de API em vez de uma sessão. Antes de cada pedido, a CLI lê o catálogo da API em https://api.gota.umbeluzi.com/.well-known/api-catalog e guarda-o em cache durante cinco minutos; é daí que vêm os caminhos de cada área (business, auth e as restantes).

Instalar#

O binário é estático e não tem dependências. Coloque-o numa pasta que esteja no PATH e confirme a versão, o commit, a data de compilação e o URL da API que vai chamar:

bash
gotactl version

Para apontar para outro servidor, use --api-url num comando ou guarde o valor num perfil.

Iniciar sessão#

Há três formas de autenticação, todas através de gotactl auth login:

Comando Quando usar
gotactl auth login Concessão de dispositivo: mostra um URL e um código de uso único. Funciona por SSH e em contentores sem navegador.
gotactl auth login --web Abre o navegador e conclui o início de sessão com PKCE através de um endereço local.
gotactl auth login --with-api-key Lê uma chave de API da entrada padrão e guarda-a no porta-chaves do sistema.

A CLI nunca aceita uma chave como valor de uma opção. Numa automação, passe-a pela entrada padrão com --api-key-stdin, ou pela variável de ambiente cujo nome é o nome da CLI em maiúsculas, com hífens trocados por sublinhados, seguido de _API_KEY. Quando existem uma chave e uma sessão, a CLI usa a sessão num terminal interactivo e a chave em CI ou sem terminal; --auth key ou --auth oauth força a escolha. gotactl auth status mostra o perfil activo e o emissor, e gotactl auth logout revoga a sessão e apaga as credenciais locais.

Contextos e perfis#

Uma pessoa pode pertencer a vários contextos, por exemplo uma entidade gestora em produção e a sua sandbox. gotactl contexts list mostra cada um: se é o actual, o id, o tipo (morador, empresa ou plataforma), o nome e o mode. Com uma sessão iniciada, gotactl contexts use <id> muda de contexto; com uma chave de API o comando é recusado sem enviar nenhum pedido, porque cada chave pertence a um único contexto. Para trabalhar em mais do que uma instalação, crie perfis e alterne entre eles com gotactl auth switch <perfil> ou com --profile em cada comando.

Que comandos cada contexto pode usar#

O que um comando faz depende do contexto em que está, não da CLI. Um morador vê as suas contas, facturas, pagamentos e leituras; a equipa de uma empresa de água vê os da empresa; a equipa da plataforma vê as empresas, as suas organizações, subscrições e planos. Se correr um comando de outro tipo de contexto, a CLI pára antes de enviar o pedido, diz para quem é o comando e lista o que o seu contexto pode usar. Mude com gotactl contexts use <id> ou entre com outra conta.

ComandoMoradoresEquipas das empresasEquipa da plataforma
gotactl accounts✓✓–
gotactl api-keys✓✓✓
gotactl customers–✓–
gotactl events–✓–
gotactl invoices✓✓–
gotactl organizations––✓
gotactl payments✓✓–
gotactl plans––✓
gotactl readings✓✓–
gotactl sandbox–✓–
gotactl subscriptions––✓
gotactl utilities––✓
gotactl webhooks–✓–

Em qualquer contexto: api, auth, contexts, docs, openapi, version, whoami.

Exemplo completo#

Numa tarefa de CI com uma chave de teste no segredo API_KEY:

bash
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin whoami --json credential,mode,scopes
json
{
  "credential": "api_key",
  "mode": "sandbox",
  "scopes": [
    "business:customers:read",
    "invoices:read"
  ]
}

Uma chave sk_test_ aparece sempre com mode igual a sandbox. A seguir, liste clientes escolhendo só as colunas de que precisa:

bash
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin customers list --limit 2 --json id,display_name,status
json
[
  {
    "display_name": "Ana Macuácua",
    "id": "cus_2kT7xQ9mWb4RnL8vZc3PyH6dFs1",
    "status": "active"
  },
  {
    "display_name": "Padaria Esperança, Lda",
    "id": "cus_2kT7yB3nQe8VwM5tRj1XoK4gLa9",
    "status": "suspended"
  }
]

Formato da saída#

Num terminal, os comandos imprimem uma tabela. Quando a saída vai para um ficheiro ou para outro programa, imprimem JSON indentado. --json sozinho força JSON com todos os campos; --json id,display_name mantém só esses campos e, numa listagem, devolve directamente a lista de data. Coloque --json no fim do comando ou siga-o de uma lista de campos, porque a palavra seguinte, se não começar por -, é lida como lista de campos. Para operações sem comando próprio, gotactl api GET business:/customers -f limit=5 envia o pedido pelo catálogo e --paginate segue next_cursor até has_more ser false.

Códigos de saída#

Código Significado
0 Sucesso
1 Erro geral
2 Uso incorrecto: opções ou argumentos inválidos
3 Sem sessão ou sem permissão (401, 403)
4 Recurso não encontrado (404)
5 Limite de pedidos atingido (429 depois das novas tentativas)
6 Erro do servidor (5xx), rede inacessível ou catálogo da API em falta

O ficheiro de configuração fica em config.toml, na pasta de configuração do utilizador, com modo 0600; a CLI recusa-o se for legível pelo grupo ou por outros. Os segredos vão para o porta-chaves do sistema e, quando este não existe, para um ficheiro credentials com o mesmo modo.

Próximos passos#