> 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/login.md).

# telys login

Reference for telys login — the device-code sign-in that caches your credentials and installs the signed runtime, with interactive and CI examples.

Sign in and activate a license on this machine. `telys login` runs a browser device-code flow (RFC 8628) against the accounts portal, caches credentials under `$TELYS_HOME`, and — unless told otherwise — installs the signed native runtime for your platform.

## Synopsis

```
telys login [--token TOKEN] [--plan PLAN] [--no-install] [--no-browser]
```

## Options

| Flag           | Value   | Default           | Meaning                                                                                                   |
| -------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------- |
| `--token`      | token   | (none)            | Use a control-plane token directly instead of the interactive device-code flow. Intended for headless/CI. |
| `--plan`       | plan id | `telys_developer` | Tier to activate: `telys_developer` (free), `telys_pro`, `telys_enterprise`, `telys_team`.                |
| `--no-install` | flag    | off               | Sign in only; do not download or install the signed runtime.                                              |
| `--no-browser` | flag    | off               | Do not open a browser; print the verification URL and user code for you to open elsewhere.                |

## The device-code flow

By default, `login` opens your browser at the accounts portal (`$TELYS_ACCOUNTS_URL`, default `https://accounts.thyn.ai`) and polls the control plane (`$TELYS_API_URL`) until you approve the device. On success it caches credentials and installs the runtime.

```bash
telys login
telys login --plan telys_pro     # activate a commercial tier
```

With `--no-browser`, the same flow runs but prints the URL and code to open in a browser on another machine — useful over SSH:

```bash
telys login --no-browser
# Visit https://accounts.thyn.ai/device and enter code: WDJB-MJHT
```

## What it stores

On success, `telys login` writes the following under `$TELYS_HOME` (default `~/.telys`):

| File                | Contents                                            |
| ------------------- | --------------------------------------------------- |
| `token`             | Cached control-plane auth token.                    |
| `api_key`           | Cached Telys API key.                               |
| `device_key.pem`    | Per-device Ed25519 key (mode `0600`).               |
| `device_id`         | Random device identifier (uuid4 hex).               |
| `login_license.jwt` | The license issued to this device by `telys login`. |

Unless you pass `--no-install`, it also installs the signed runtime under `$TELYS_HOME/runtime/<platform>/` — the same install as [`telys runtime install`](https://docs.telys.ai/cli/runtime.md).

{% hint style="info" %}
`login` sends no collection data anywhere — it only exchanges credentials with the identity and control-plane hosts. For a self-managed control plane, set `$TELYS_ACCOUNTS_URL` and `$TELYS_API_URL` before running it.
{% endhint %}

## Headless and CI

CI has no browser to approve a device. Supply a token instead, and skip the runtime install if you only need to authenticate:

{% tabs %}
{% tab title="token flag" icon="terminal" %}

```bash
telys login --token "$TELYS_TOKEN"
```

{% endtab %}

{% tab title="environment" icon="gear" %}

```bash
export TELYS_TOKEN="…"     # control-plane token
telys login --no-install   # authenticate without downloading the runtime
```

{% endtab %}
{% endtabs %}

`$TELYS_TOKEN` and `$TELYS_API_KEY` also override the cached credentials at runtime, so a fully provisioned CI job can skip `login` entirely. See [Environment & exit codes](https://docs.telys.ai/cli/environment-and-exit-codes.md).

## Exit codes

| Code | Meaning                                                    |
| ---- | ---------------------------------------------------------- |
| `0`  | Signed in (and, unless `--no-install`, runtime installed). |
| `1`  | Authentication or install could not complete.              |
| `2`  | Usage error (for example, an unknown flag).                |

## See also

* [Sign in & activate a license](https://docs.telys.ai/start-here/sign-in.md) — the guided walkthrough.
* [Device-code sign-in](https://docs.telys.ai/licensing/device-code-sign-in.md) — how the flow works and what it grants.
* [Plans & licensing](https://docs.telys.ai/licensing/tiers-and-pricing.md) — which `--plan` value to use.
* [telys runtime](https://docs.telys.ai/cli/runtime.md) — install and verify the runtime separately.
