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_) withbusiness:readings:create,business:readings:readandinvoices:read, stored in the job's secrets asAPI_KEY. gotactlon the runner'sPATHandjqfor building request bodies.- A CSV file with the header
meter_id,value,measured_at, wheremeasured_atis 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#
printf '%s\n' "$API_KEY" | gotactl --api-key-stdin whoami --json mode
{
"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.
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
{
"id": "rdg_2pR5dV1xQm6ZtB4nKc8WyL3hGa7",
"meter_id": "mtr_2pR5cK8wNd3XqL7vTb1MzH4yJf9",
"status": "submitted"
}
3. Export the open invoices#
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#
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.