> ## Documentation Index
> Fetch the complete documentation index at: https://cralo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration and troubleshooting

> Configure reliable Cralo execution for AI agents.

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:

```json theme={null}
{
  "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

```bash theme={null}
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.

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