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:
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.
| Comando | Moradores | Equipas das empresas | Equipa 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:
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin whoami --json credential,mode,scopes
{
"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:
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin customers list --limit 2 --json id,display_name,status
[
{
"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.