Override the API Address of an Okibi CLI at Run Time
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
Override the API Address of an Okibi CLI at Run Time
A generated CLI has the API address from your spec compiled in. To point it at a staging server, a proxy or a different region without a new release, you override it when you run the command. This guide shows which override works, which one is silently ignored, and how to tell the difference.
What you will build
Three checks of the override: the compiled address, the two ways to override it, and a dead-address test that proves which one is read.
okibi clis endpoint status -> compiled address ACME_ORDERS_BASE_URL_OVERRIDE / --base-url -> per-run address dead port + --data-source live -> proof that the override was used
AI Prompt
Using the Okibi CLI and the generated acme-orders CLI, point the CLI at a different API address for one run. Requirements: - Run `okibi clis endpoint status acme-orders --json` and report `apiBaseUrl`. - Override the address with `ACME_ORDERS_BASE_URL_OVERRIDE` and, separately, with `--base-url`, using `acme-orders doctor --agent`. - Prove which variable is read by pointing each at a closed port with `orders list --limit 1 --data-source live --no-cache` and reporting the result. Also set both the variable and `--base-url` and report which one `doctor` shows. - Report the warning printed when a read cannot reach the API without `--data-source live`. - Run the verification step below before finishing.
Prerequisites
-
The Acme Orders example files,
openapi.json(a fictional orders API spec) andserver.py(a mock server for it). Download them into your working directory:curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/server.py
-
acme-ordersgenerated from the Acme Orders example spec and built with Go (okibi generate --spec ./openapi.json --name acme-orders --agent;okibi generate --agentdoes not download the CLI, so wait untilokibi status <run-id> --json(<run-id>isbuild.runIdfrom its output) shows"status": "succeeded", then runokibi pull <run-id>andgo build -o ./acme-orders ./cmd/acme-ordersinside the project), withACME_ORDERS_API_KEYexported (export ACME_ORDERS_API_KEY=demo-key; the example server calls the same keyACME_API_KEY) and the Acme Orders example API running (ACME_API_KEY=demo-key python3 server.py --port 8099). -
Okibi CLI
0.2.11, logged in.
1. Read the address the project is set to
okibi clis endpoint status acme-orders --json
{ "apiBaseUrl": "http://127.0.0.1:8099/v1" }
This is the address in the project's current official source. It came from the spec's servers entry at generation time. It is not proof of what an installed binary does: a binary installed from an earlier release, or one that was configured differently, can use another address. To see what the binary you run uses, ask that binary:
./acme-orders doctor --agent | grep base_url
"base_url": "http://127.0.0.1:8099/v1",
2. Override it for one command
ACME_ORDERS_BASE_URL_OVERRIDE=http://localhost:8099/v1 ./acme-orders doctor --agent | grep base_url ./acme-orders doctor --agent --base-url http://localhost:8099/v1 | grep base_url
warning: sending credentials to localhost, not 127.0.0.1, because the base URL is overridden "base_url": "http://localhost:8099/v1",
Both forms printed the same warning and address. The warning goes to stderr, so it appears even when you pipe the output through grep. The warning appears when the override points at a different host than the compiled one, because the API key goes there.
3. See which wins when both are set
ACME_ORDERS_BASE_URL_OVERRIDE=http://localhost:8099/v1 ./acme-orders doctor --agent --base-url http://127.0.0.1:8099/v1 | grep base_url
"base_url": "http://127.0.0.1:8099/v1",
With both set, the --base-url flag wins over the environment variable. With neither, the compiled address is used.
4. Prove which variable is read
Point each name at a closed port and force a live read:
env ACME_ORDERS_BASE_URL_OVERRIDE=http://127.0.0.1:9/v1 ./acme-orders orders list --limit 1 --data-source live --no-cache --agent env ACME_ORDERS_BASE_URL=http://127.0.0.1:9/v1 ./acme-orders orders list --limit 1 --data-source live --no-cache --agent
Error: GET /orders: Get "http://127.0.0.1:9/v1/orders?limit=1": dial tcp 127.0.0.1:9: connect: connection refused
The first command failed to connect, so the override was used. The second printed orders from the real API (preceded by a {"event":"truncated",...} line, which comes from --limit), so ACME_ORDERS_BASE_URL (without _OVERRIDE) is ignored on this CLI.
5. See the fallback without --data-source live
This needs local data to fall back on. If you have not run ./acme-orders sync --agent yet, the same command fails with API unreachable and nothing synced for "orders" to fall back on.
./acme-orders orders list --limit 1 --base-url http://127.0.0.1:9/v1 --agent
warning: API unreachable (connect: connection refused); answering from local data synced N minutes ago (the number depends on when you last synced). Pass --data-source live to fail instead.
The command still returned an order, from the local store. A dead address looks like success unless you add --data-source live.
Verify the result
env ACME_ORDERS_BASE_URL_OVERRIDE=http://127.0.0.1:9/v1 ./acme-orders orders list --limit 1 --data-source live --no-cache --agent 2>&1 | head -1
Expected: Error: GET /orders: Get "http://127.0.0.1:9/v1/orders?limit=1": dial tcp 127.0.0.1:9: connect: connection refused.
How it works
The address is compiled in as a default. --base-url and ACME_ORDERS_BASE_URL_OVERRIDE replace it for one run. Read commands use --data-source auto by default, which falls back to local data when the API cannot be reached.
Common issues
The variable name differs from older builds
An earlier generation of this CLI read ACME_ORDERS_BASE_URL. This one ignores it. Check the name your own build reads with the dead-port test in step 3.
The override is per run
It changes one command or one shell. Users who installed the CLI keep the compiled address. Changing the compiled address for everyone needs a new release, which this guide does not cover.
Overrides move your API key
The CLI warns when the new host differs, and still sends the key there. Do not point it at a host you do not control.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.0" command: "env ACME_ORDERS_BASE_URL_OVERRIDE=http://127.0.0.1:9/v1 ./acme-orders orders list --limit 1 --data-source live --no-cache --agent" expected_result: "connection refused error, proving the override variable is read"
