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.

CommandResidentsUtility staffPlatform staff
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–✓–

In every context: api, auth, contexts, docs, openapi, version, whoami.

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#