> 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

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`](/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](/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](/start-here/sign-in.md) — the guided walkthrough.
* [Device-code sign-in](/licensing/device-code-sign-in.md) — how the flow works and what it grants.
* [Plans & licensing](/licensing/tiers-and-pricing.md) — which `--plan` value to use.
* [telys runtime](/cli/runtime.md) — install and verify the runtime separately.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/cli/login.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.