# CLI overview

Install the CLI, sign in with an account or an API key, pick a context and profile, read JSON output and handle exit codes.


`gotactl` is a command-line client for the public API. People use it from a terminal to look up customers, invoices and payments or to test webhooks in a sandbox; CI jobs use it with an API key instead of a session. Before it sends a request, the CLI reads the API catalog at `https://api.gota.umbeluzi.com/.well-known/api-catalog` and caches it for five minutes, and it resolves the paths for each API surface (`business`, `auth` and the rest) from that catalog.

## Install

The binary is static and has no dependencies. Put it in a folder on your `PATH`, then check the version, commit, build date and the API URL it will call:

```bash
gotactl version
```

To target a different server, pass `--api-url` on a command or save the value in a profile.

## Sign in

`gotactl auth login` supports three methods:

| Command | Use it when |
| :--- | :--- |
| `gotactl auth login` | Device grant: prints a URL and a one-time code. Works over SSH and in containers with no browser. |
| `gotactl auth login --web` | Opens your browser and completes sign-in with PKCE through a local loopback address. |
| `gotactl auth login --with-api-key` | Reads an API key from standard input and stores it in the OS keychain. |

The CLI never takes a key as a flag value. In automation, pipe it in with `--api-key-stdin`, or set the environment variable named after the CLI: its name in upper case, hyphens turned into underscores, followed by `_API_KEY`. If both a key and a session are available, an interactive terminal uses the session and CI or a non-terminal run uses the key; `--auth key` or `--auth oauth` overrides that. `gotactl auth status` prints the active profile and issuer, and `gotactl auth logout` revokes the session and deletes local credentials.

## Contexts and profiles

One person can belong to several contexts, such as a live utility and its sandbox. `gotactl contexts list` shows each one: whether it's the current one, its `id`, its kind (resident, utility or platform), its name and its `mode`. With a session, `gotactl contexts use <id>` switches to another one; with an API key the command fails before any request is sent, because a key belongs to exactly one context. If you work against more than one installation, create profiles and move between them with `gotactl auth switch <profile>` or with `--profile` on a single command.

## Who can use which command

What a command does depends on the context you're in, not on the CLI. A resident sees their own accounts, invoices, payments and readings; a utility's staff see the utility's; the platform's staff see the utilities, their organizations, subscriptions and plans. Run a command meant for another kind of context and the CLI stops before sending anything, says who the command is for and lists what your context can use. Switch with `gotactl contexts use <id>`, or sign in with another account.

{{< cli-audiences >}}

## A complete example

In a CI job that holds a test key in the `API_KEY` secret:

```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"
  ]
}
```

An `sk_test_` key always reports `mode` as `sandbox`. Next, list customers and keep only the fields you need:

```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"
  }
]
```

## Output format

In a terminal, commands print a table. When output goes to a file or a pipe, they print indented JSON. A bare `--json` forces JSON with every field; `--json id,display_name` keeps only those fields and, on a list, returns the items of `data` directly. Put `--json` last or follow it with a field list: the next word, unless it starts with `-`, is read as the field list. For operations without their own command, `gotactl api GET business:/customers -f limit=5` sends the request through the catalog, and `--paginate` follows `next_cursor` until `has_more` is `false`.

## Exit codes

| Code | Meaning |
| :--- | :--- |
| `0` | Success |
| `1` | General error |
| `2` | Usage error: invalid flags or arguments |
| `3` | Not signed in or not allowed (`401`, `403`) |
| `4` | Not found (`404`) |
| `5` | Rate limited (`429` after retries) |
| `6` | Server error (`5xx`), network unreachable, or the API catalog is missing |

Configuration lives in `config.toml` under your user config folder, with mode `0600`; the CLI refuses the file if the group or others can read it. Secrets go to the OS keychain, or to a `credentials` file with the same mode when no keychain is available.

## Next steps

- [Every CLI command and flag](/docs/cli/reference)
- [Automate billing and sandbox tasks with the CLI](/docs/guides/automate-cli)
- [Receive webhooks on your machine with `webhooks listen`](/docs/webhooks/testing)
- [Create and roll the API key your CI job uses](/docs/getting-started/api-keys)

