# Automate with the CLI

Write a nightly job that submits meter readings from a CSV file and exports open invoices, passing the key on standard input, reading JSON output and branching on the CLI's exit codes.


## What you will build

A shell script for cron or a CI schedule that does two things every night: it sends the meter readings collected during the day, one request per row of a CSV file, and it writes the utility's open invoices to a JSON file for another system to pick up. The script never puts the key on the command line, retries nothing by hand that the CLI or the API already makes safe, and stops with a message a person can act on when something is wrong.

## Prerequisites

- A sandbox and a restricted test key (prefix `sk_rtest_`) with `business:readings:create`, `business:readings:read` and `invoices:read`, stored in the job's secrets as `API_KEY`.
- `gotactl` on the runner's `PATH` and `jq` for building request bodies.
- A CSV file with the header `meter_id,value,measured_at`, where `measured_at` is an RFC 3339 time.

The global flags this guide uses:

| Flag | Description |
| :--- | :--- |
| `--api-key-stdin` | Read an API key from standard input |
| `--json` | Output JSON, optionally limited to comma-separated field names |
| `--idempotency-key` | Idempotency-Key header for write requests |

## 1. Pass the key on standard input

```bash
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin whoami --json mode
```

```json
{
  "mode": "sandbox"
}
```

✓ Checkpoint: `mode` is `sandbox`. `--api-key-stdin` reads the first line of standard input and checks the key prefix before any request leaves the machine, so a value that is not an API key fails at once with exit code `2`. Because the key takes standard input, request bodies in this script go in files.

## 2. Submit one reading per row

The readings endpoint needs `meter_id`, `value` (a decimal written as a string), `unit`, `measured_at`, `client_reading_id` and `idempotency_key`. Building both IDs from the meter and the time makes a re-run of the same file harmless.

```bash
jq -n --arg m "mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9" --arg v "1342.517" --arg t "2026-11-18T16:40:00Z" \
  '{meter_id:$m,value:$v,unit:"m3",measured_at:$t,client_reading_id:("nightly-"+$m+"-"+$t),idempotency_key:("nightly-"+$m+"-"+$t)}' > reading.json

printf '%s\n' "$API_KEY" | gotactl --api-key-stdin api POST business:/readings --input reading.json --json id,meter_id,status
```

```json
{
  "id": "rdg_2pR5dV1xQm6ZtB4nKc8WyL3hGa7",
  "meter_id": "mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9",
  "status": "submitted"
}
```

✓ Checkpoint: `status` is `submitted`, or `review_required` when the plausibility check wants a person to look at it. Sending the same `idempotency_key` with the same data returns the original reading; the same key with different data is refused with `409`. The meter must be active, `unit` must be the meter's own unit, and `measured_at` may not be before its installation or more than 5 minutes in the future.

## 3. Export the open invoices

```bash
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin invoices list --status open --all \
  --json id,invoice_number,account_id,amount_due_cents > open-invoices.json
```

✓ Checkpoint: `open-invoices.json` holds a JSON array with one object per invoice and only the four fields you asked for. `--all` follows `next_cursor` until `has_more` is `false`, so the file is complete however many pages there are.

## 4. Stop on the right errors

```bash
set -u
tail -n +2 readings.csv | while IFS=, read -r meter value at; do
  jq -n --arg m "$meter" --arg v "$value" --arg t "$at" \
    '{meter_id:$m,value:$v,unit:"m3",measured_at:$t,client_reading_id:("nightly-"+$m+"-"+$t),idempotency_key:("nightly-"+$m+"-"+$t)}' > reading.json
  printf '%s\n' "$API_KEY" | gotactl --api-key-stdin api POST business:/readings --input reading.json --json id,status
  code=$?
  case $code in
    0) ;;
    3) echo "access refused: key revoked, scope missing or meter not active ($meter)" >&2; exit 3 ;;
    5|6) echo "API busy or unreachable: run the job again, the idempotency keys make it safe" >&2; exit "$code" ;;
    *) echo "row refused: $meter at $at" >&2 ;;
  esac
done
```

✓ Checkpoint: a refused row is logged and the loop moves on; a `401` or `403` (exit code `3`) or an unreachable API ends the job. The API answers `403` for a meter that is not active as well as for a key that lacks the scope, so the message names the meter. A `5xx` response also exits with `6`. The CLI already waits on `429` using `Retry-After` and gives up with code `5` after its third attempt. Every error is printed on standard error with the problem's title, detail and `request_id`.

## Test it

Run the script against the sandbox and look at the result with `gotactl readings list --meter-id mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9 --json id,value,status`. Each request the key made is listed in the dashboard under **Developers** > **Logs**. For write commands that have no idempotency field in the body, the global `--idempotency-key` flag sends the `Idempotency-Key` header.

## Next steps

- [Every CLI command and its flags](/docs/cli/reference)
- [Limit the job's key to the scopes it uses](/docs/getting-started/restricted-keys)
- [What the readings endpoint checks before it accepts a value](/docs/guides/record-readings)

