> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/cli/environment-and-exit-codes.md).

# Environment & exit codes

Reference for the environment variables the telys CLI honors and the exit codes every command returns — 0 ok, 1 not-ready, 2 usage or not-implemented.

Every `telys` command is configured through the environment and reports its outcome through a small, stable set of exit codes. For the full catalogue of SDK-level variables (kernel paths, license issuer/audience, verify-key overrides), see [Environment variables](https://docs.telys.ai/operations/environment-variables.md).

## Exit codes

The CLI uses three exit codes consistently across commands:

| Code | Name                    | When you see it                                                                                                                                                        |
| ---- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | success                 | The command completed. Bare `telys` (help) also exits `0`.                                                                                                             |
| `1`  | not ready               | A well-defined "not ready" state — for example, `telys runtime status` when no runtime is installed, or a command that needs the runtime when it is missing.           |
| `2`  | usage / not implemented | A malformed invocation (missing required flag, no transport for `serve`), or a command that is not implemented — `telys runtime update` is the one stub and exits `2`. |

Branch on outcomes in scripts:

```bash
if telys runtime status; then
  echo "runtime ready"
else
  telys runtime install
fi
```

## Environment variables the CLI honors

### On-disk state

| Variable              | Default           | Effect                                                                                                            |
| --------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `TELYS_HOME`          | `~/.telys`        | Root of all on-disk state: cached credentials, device key, installed runtime.                                     |
| `TELYS_MEMORY_PATH`   | `~/.telys/memory` | Memory directory used by the MCP server and `telys mem` when `--path` is not given.                               |
| `TELYS_MCP_WORKSPACE` | —                 | Repo root the MCP auto-indexer maps for `telys_index_repo` / `telys_repo_search` when `--workspace` is not given. |

### Credentials and licensing

| Variable             | Default | Effect                                                             |
| -------------------- | ------- | ------------------------------------------------------------------ |
| `TELYS_TOKEN`        | —       | Control-plane auth token override (used by `login` and API calls). |
| `TELYS_API_KEY`      | —       | Telys API key override.                                            |
| `TELYS_LICENSE`      | —       | License token read by `telys serve` (with `--require-license`).    |
| `TELYS_ACCESS_TOKEN` | —       | Bearer token for `telys serve` over TCP.                           |

### Runtime selection

| Variable        | Default     | Effect                                                                                                                                             |
| --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TELYS_RUNTIME` | `""` (auto) | Force the runtime backend: `native` or `local`. Empty means auto-select. Read when the runtime is loaded (`serve`, `mcp`, `mem`, and library use). |

### Control-plane and download hosts

| Variable             | Default                     | Effect                                                        |
| -------------------- | --------------------------- | ------------------------------------------------------------- |
| `TELYS_ACCOUNTS_URL` | `https://accounts.thyn.ai`  | Identity portal for device-code sign-in.                      |
| `TELYS_API_URL`      | `https://api.telys.ai`      | Control plane for keys, device approval, and licensing.       |
| `TELYS_PACKAGES_URL` | `https://packages.telys.ai` | Signed-runtime download host used by `telys runtime install`. |

{% hint style="info" %}
`$TELYS_TOKEN` and `$TELYS_API_KEY` override the credentials cached by `telys login`, letting a provisioned CI job skip the interactive flow entirely. Point the three `*_URL` variables at your own hosts to run against a self-managed control plane.
{% endhint %}

## Where each variable is used

| Command                                                 | Reads                                                                                                     |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [`telys login`](https://docs.telys.ai/cli/login.md)     | `TELYS_HOME`, `TELYS_ACCOUNTS_URL`, `TELYS_API_URL`, `TELYS_PACKAGES_URL`, `TELYS_TOKEN`, `TELYS_API_KEY` |
| [`telys runtime`](https://docs.telys.ai/cli/runtime.md) | `TELYS_HOME`, `TELYS_PACKAGES_URL`                                                                        |
| [`telys serve`](https://docs.telys.ai/cli/serve.md)     | `TELYS_ACCESS_TOKEN`, `TELYS_LICENSE`, `TELYS_RUNTIME`                                                    |
| [`telys mcp`](https://docs.telys.ai/cli/mcp.md)         | `TELYS_MEMORY_PATH`, `TELYS_MCP_WORKSPACE`, `TELYS_HOME`, `TELYS_RUNTIME`                                 |
| [`telys mem`](https://docs.telys.ai/cli/mem.md)         | `TELYS_MEMORY_PATH`, `TELYS_HOME`, `TELYS_RUNTIME`                                                        |

`TELYS_RUNTIME` is read by the runtime loader (`telys.runtime.load_runtime()`) — the `serve` / `mcp` / `mem` commands and any Python program using the library. `telys runtime status` also loads the runtime (it reports the kernel source of the selected impl, so the override is honored there too); `telys runtime install/verify` manage the installed artifacts and do not read it.

## See also

* [Environment variables](https://docs.telys.ai/operations/environment-variables.md) — the full list, including kernel paths and verify-key overrides.
* [On-disk layout](https://docs.telys.ai/operations/on-disk-layout.md) — what lives under `$TELYS_HOME`.
* [CLI overview](https://docs.telys.ai/cli/overview.md) — the command tree these variables configure.
