> 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/troubleshooting/license-and-login.md).
# License & login
`telys login` uses a browser **device-code** flow (RFC 8628) by default: it prints a code, you approve it at the accounts portal, and Telys caches your credentials and license under `$TELYS_HOME` (default `~/.telys`). Most login problems are a browser that won't open, a stale or expired license, or the wrong plan. All are fixable from the CLI.
{% hint style="info" %}
Login writes `token`, `api_key`, `device_key.pem`, `device_id`, and `login_license.jwt` under `~/.telys`. When in doubt, sign in again — it refreshes all of them.
{% endhint %}
## Quick check
```bash
telys login # sign in (free telys_developer by default)
telys runtime verify # confirms the cached license is valid and trusted
```
## Errors and fixes
Login fails or hangs — the browser never opens
The device-code flow opens your default browser to the accounts portal. On a headless host, over SSH, or in a locked-down desktop, that can fail silently.
**Cause:** no usable browser on this machine, or the environment blocks launching one.
**Fix:** skip the auto-open and approve the code manually, or switch to a token (next entry).
```bash
telys login --no-browser # prints the code + URL; approve it on any device
```
Open the printed URL on any machine with a browser, enter the code, and the CLI completes on approval. Portal: `https://accounts.thyn.ai`.
Headless / CI sign-in with --token
CI, containers, and bare SSH sessions have no browser, so the device-code flow can't complete interactively.
**Cause:** you need non-interactive sign-in.
**Fix:** pass a control-plane token directly. Keep it in an environment variable, never inline in a script.
```bash
telys login --token "$TELYS_TOKEN" # non-interactive
telys login --token "$TELYS_TOKEN" --no-install # sign in now, install the runtime later
```
Set `$TELYS_TOKEN` (control-plane auth) or `$TELYS_API_KEY` (API key) to override cached credentials for a single command.
Expired or invalid license
The cached license is a signed offline token. Verification (RS256, offline) checks the issuer, audience, version, and expiry with a small grace window, and rejects an aged-out or tampered token.
**Cause:** the license expired, the clock is wrong, or the cached `login_license.jwt` is stale.
**Fix:** sign in again to refresh the license, then re-verify.
```bash
telys login # refreshes ~/.telys/login_license.jwt
telys runtime verify # re-checks iss / aud / ver / exp
```
If it still fails after a fresh login, the problem is in the token's claims or the verify keys — see the dedicated page.
Next: [Signature verification failures](/troubleshooting/signature-verification.md)
Wrong plan — feature or activation refused
You're signed in, but on a tier that doesn't grant the operation. `telys login` defaults to the free `telys_developer` plan (1 device).
**Cause:** you need a commercial tier (for example `telys_pro`) but signed in on `telys_developer`.
**Fix:** sign in with the plan you want, or upgrade in the portal first, then sign in again.
```bash
telys login --plan telys_pro # commercial plan — subscribe via Stripe checkout
telys login --plan telys_enterprise # sales-assisted
```
Tiers: `telys_developer` (free, 1 device) · `telys_pro` (commercial) · `telys_enterprise` (sales) · `telys_team` (self-host / `telys serve`). Manage subscriptions at `https://accounts.thyn.ai`; pricing at `https://telys.ai/pricing`.
## Next steps
If login succeeds but the runtime or license still won't verify, the problem is signature or claim checking, not sign-in.
Next: [Signature verification failures](/troubleshooting/signature-verification.md)
---
# 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/troubleshooting/license-and-login.md?ask=&goal=
```
`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.