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

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

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

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

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#