# 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.

{{< cli-audiences >}}

## 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

- [Referência de todos os comandos e opções da CLI](/docs/cli/reference)
- [Automatizar tarefas de facturação e testes com a CLI](/docs/guides/automate-cli)
- [Receber webhooks na máquina local com `webhooks listen`](/docs/webhooks/testing)
- [Criar e renovar a chave de API que a CLI usa em CI](/docs/getting-started/api-keys)

