Configuration and troubleshooting

Use these settings and machine-readable contracts to make agent tool calls predictable and recoverable.

Environment variables

Variable	Purpose
`CRALO_API_KEY`	API key for unattended agents; overrides stored credentials.
`CRALO_API_URL`	API base URL; default: `https://api.cralo.ai/v1`.
`CRALO_REQUEST_TIMEOUT_MS`	Per-request API timeout in milliseconds; default: `30000`.
`CRALO_TELEMETRY_DISABLED`	Disable optional telemetry.

The legacy OPENTOOLER_* names remain supported for existing automation. CRALO_API_BASE_URL, OPENTOOLER_API_URL, and OPENTOOLER_API_BASE_URL are accepted as endpoint aliases. Precedence is CRALO_API_URL, CRALO_API_BASE_URL, OPENTOOLER_API_URL, then OPENTOOLER_API_BASE_URL. Existing published @opentooler/cli releases keep https://api.opentooler.ai/v1 as their default and will not receive new versions. The primary @cralo/cli package defaults to https://api.cralo.ai/v1.

JSON output contract

With --json, stdout contains one JSON document:

{
  "ok": true,
  "data": {},
  "meta": {}
}

Errors include a semantic exit code and a machine-readable payload that agents can use to choose a recovery action.

Exit codes

Code	Meaning	Recommended action
0	Success	Continue.
2	Usage or input error	Fix the command or schema input.
3	Authentication required	Run `cralo auth login` or configure a key.
4	Credits or policy blocked	Check balance and top up if approved.
5	Tool unavailable	Search or describe the tool again.
6	Invocation failed	Read error details; do not blind-retry.
7	Invocation timeout	Get the invocation status instead of duplicating work.
8	Network or service unavailable	Retry safe reads after checking connectivity.
9	Rate limited	Wait for the advised backoff period.

Diagnose setup

cralo doctor --json

doctor reports platform, architecture, CLI and protocol versions, credential presence, keychain availability, API reachability, latency, and video-transcription prerequisites. INVOCATION_ADMISSION_UNKNOWN is produced locally by the CLI when it cannot confirm whether a paid call was admitted (for example, the network dropped after submission). The related API-level code for an unknown outcome after a wait budget is INVOCATION_OUTCOME_UNKNOWN; both have the same recovery rule: retry the exact same tool and input with the same idempotency key.

If a paid call returns INVOCATION_ADMISSION_UNKNOWN, the agent must rerun only the exact original tool and payload with the supplied idempotency key.

Getting started

Using Cralo

CLI reference

Configuration and troubleshooting

Environment variables

JSON output contract

Exit codes

Diagnose setup

​Environment variables

​JSON output contract

​Exit codes

​Diagnose setup

Environment variables

JSON output contract

Exit codes

Diagnose setup