CLI reference

gotactl accounts

List and inspect accounts

gotactl accounts get

Get an account by ID

Examples

bash
gotactl accounts get acc_123 --json

gotactl accounts list

List accounts

Flags

--allboolFetch all pages
--customer-idstringFilter by customer ID
--limitintMaximum items to return
--statusstringFilter by status

Examples

bash
gotactl accounts list --limit 25 --json

gotactl api

Send a raw API request resolved through the API catalog

Flags

--fieldstringArrayQuery parameter (GET) or JSON body field (key=value)
--headerstringArrayAdditional HTTP header (Name: Value)
--inputstringRead request body from file (or - for stdin)
--paginateboolFollow next_cursor across pages

Examples

bash
gotactl api GET business:/customers -f limit=5 --json

gotactl api-keys

List, create, roll, and revoke API keys for the active context

gotactl api-keys create

Create an API key in the active context (requires OAuth)

Flags

--modestringKey mode (live or test)
--namestringKey name
--outstringWrite the secret to a 0600 file instead of stdout
--scopestringArrayScope to grant (repeatable)
--show-secretboolPrint the secret to stdout even on a TTY

Examples

bash
gotactl api-keys create --name ci-ingest --scopes readings:write --out key.txt

gotactl api-keys list

List API keys in the active context

Examples

bash
gotactl api-keys list --json

gotactl api-keys revoke

Revoke an API key in the active context (requires OAuth)

Examples

bash
gotactl api-keys revoke key_123

gotactl api-keys roll

Roll an API key in the active context (requires OAuth)

Flags

--outstringWrite the secret to a 0600 file instead of stdout
--overlap-secondsint64Overlap duration in seconds
--show-secretboolPrint the secret to stdout even on a TTY

Examples

bash
gotactl api-keys roll key_123 --out key.txt

gotactl auth

Authenticate and manage profiles

gotactl auth login

Sign in via device grant, browser PKCE (--web), or API key (--with-api-key)

Flags

--contextstringSign in directly to a specific context ID
--webboolSign in using a browser and PKCE
--with-api-keyboolRead an API key from stdin and store it in the keychain

gotactl auth logout

Revoke the active session and remove local credentials

gotactl auth status

Show current authentication status, profile, and issuer

gotactl auth switch

Switch the active profile in config.toml

gotactl contexts

List and switch account contexts

gotactl contexts list

List available contexts for the signed-in account

Examples

bash
gotactl contexts list --json

gotactl contexts use

Switch the active OAuth session to another context

Flags

--webboolUse browser PKCE if interaction_required is returned

gotactl customers

Manage customers

gotactl customers get

Get a customer by ID

Examples

bash
gotactl customers get cus_123 --json

gotactl customers list

List customers

Flags

--allboolFetch all pages
--limitintMaximum items to return
--searchstringSearch query
--statusstringFilter by status

Examples

bash
gotactl customers list --limit 10 --json id,display_name

gotactl docs

Export the CLI command tree and metadata (use --json)

gotactl events

Trigger domain events in a sandbox

gotactl events trigger

Trigger a real domain event in the active sandbox

Flags

--listboolList supported event types

Examples

bash
gotactl events trigger invoice.paid
gotactl events trigger --list

gotactl invoices

List and inspect invoices

gotactl invoices get

Get an invoice by ID

Examples

bash
gotactl invoices get inv_123 --json

gotactl invoices list

List invoices

Flags

--account-idstringFilter by account ID
--allboolFetch all pages
--customer-idstringFilter by customer ID
--limitintMaximum items to return
--statusstringFilter by status

Examples

bash
gotactl invoices list --status issued --json

gotactl openapi

Print the OpenAPI document discovered from the API catalog

gotactl organizations

List the organizations on the platform

gotactl organizations get

Get an organization by ID

Examples

bash
gotactl organizations get org_123 --json

gotactl organizations list

List the organizations on the platform

Flags

--allboolFetch all pages
--limitintMaximum items to return
--statusstringFilter by status

Examples

bash
gotactl organizations list --status active

gotactl payments

List and inspect payments

gotactl payments get

Get a payment by ID

Examples

bash
gotactl payments get pay_123 --json

gotactl payments list

List payments

Flags

--account-idstringFilter by account ID
--allboolFetch all pages
--invoice-idstringFilter by invoice ID
--limitintMaximum items to return
--statusstringFilter by status

Examples

bash
gotactl payments list --limit 25 --json

gotactl plans

List the subscription plans

gotactl plans get

Get a plan by ID or code

gotactl plans list

List the subscription plans

Flags

--allboolFetch all pages
--limitintMaximum items to return

Examples

bash
gotactl plans list

gotactl readings

List and submit meter readings

gotactl readings list

List meter readings

Flags

--accountstringOnly this account (ID or number)
--allboolFetch all pages
--limitintMaximum items to return
--meter-idstringFilter by meter ID

Examples

bash
gotactl readings list --meter-id mtr_123 --json

gotactl readings submit

Submit a meter reading

Flags

--accountstringYour account (ID or number), if you have several
--atstringWhen it was read (RFC 3339; default now)
--meterstringMeter ID
--unitstringUnit of the reading
--valuestringReading on the meter's dial, e.g. 512.3

Examples

bash
gotactl readings submit --meter mtr_123 --value 42.5 --json

gotactl sandbox

Manage sandbox state and simulated payments

gotactl sandbox advance

Advance pending simulated payments or generate sandbox readings

Flags

--outcomestringTarget outcome: confirmed, failed, or expired
--paymentstringSpecific pending payment ID to advance (defaults to all pending)
--readingsboolAlso generate a new cycle of sandbox meter readings

Examples

bash
gotactl sandbox advance
gotactl sandbox advance --payment pay_123 --outcome expired

gotactl subscriptions

List the utilities' subscriptions

gotactl subscriptions get

Get a subscription by ID

Examples

bash
gotactl subscriptions get sub_123 --json

gotactl subscriptions list

List the utilities' subscriptions

Flags

--allboolFetch all pages
--limitintMaximum items to return
--statusstringFilter by status
--tenant-idstringFilter by tenant ID

Examples

bash
gotactl subscriptions list --status past_due

gotactl utilities

List the utilities on the platform

gotactl utilities get

Get a utility by tenant ID or slug

Examples

bash
gotactl utilities get aguas-da-beira

gotactl utilities list

List the utilities on the platform

Flags

--allboolFetch all pages
--limitintMaximum items to return

Examples

bash
gotactl utilities list

gotactl version

Print version, commit, build date, and configured API URL

gotactl webhooks

Listen to and forward webhook events

gotactl webhooks listen

Forward domain events from the API to a local HTTP endpoint

Flags

--confirm-liveboolConfirm listening on a live context
--eventsstringComma-separated list of event types to forward
--forward-tostringLocal URL to receive forwarded webhook POSTs
--liveboolAllow listening on a live context
--poll-intervaldurationPolling interval, used only against servers without CLI sessions

Examples

bash
gotactl webhooks listen --forward-to http://localhost:3000/hook
gotactl webhooks listen --forward-to http://localhost:3000/hook --events invoice.paid,payment.received

gotactl whoami

Show the current identity, active context, or API key details

Examples

bash
gotactl whoami --json