> 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/start-here/sign-in.md).

# Sign in

Run telys login to complete the device-code browser flow (or pass a token for CI), activate a license, and provision the signed runtime for your platform.

`telys login` does three things in one step: signs your device in with a device-code flow, activates a license for your plan, and provisions the signed native runtime. The default plan is the free `telys_developer` tier (one device); pass `--plan telys_pro` for commercial rights.

## Log in

{% tabs %}
{% tab title="Interactive" icon="browser" %}

```bash
telys login
```

Opens the accounts portal in your browser, prints a user code, and waits while you approve the device. Standard flow on a workstation.
{% endtab %}

{% tab title="Headless / CI" icon="terminal" %}

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

Authenticates with a token from the accounts portal instead of a browser — for CI runners and remote shells. `--no-browser` prints the verification URL instead of opening one.
{% endtab %}

{% tab title="Commercial plan" icon="briefcase" %}

```bash
telys login --plan telys_pro
```

Activates commercial-use rights on the `telys_pro` tier. Manage the subscription at [accounts.thyn.ai](https://accounts.thyn.ai).
{% endtab %}
{% endtabs %}

## How the device-code flow works

The default flow is the OAuth 2.0 device authorization grant (RFC 8628): the CLI requests a code, you approve it in a browser signed in to your account, and the CLI polls until approval completes.

{% stepper %}
{% step %}

#### Start login

Run `telys login`. The CLI contacts the accounts portal (`accounts.thyn.ai`) and receives a user code and a verification URL.
{% endstep %}

{% step %}

#### Approve the device

Your browser opens the verification URL. Sign in if needed and confirm the code shown in your terminal. With `--no-browser`, open the printed URL manually.
{% endstep %}

{% step %}

#### Receive credentials and license

On approval, the CLI stores your device credentials and a signed login license under `~/.telys`, then activates your plan.
{% endstep %}

{% step %}

#### Provision the runtime

Unless you pass `--no-install`, the CLI downloads the signed runtime for your platform and verifies it offline before finishing.
{% endstep %}
{% endstepper %}

## Options

| Flag            | Effect                                                                              |
| --------------- | ----------------------------------------------------------------------------------- |
| `--token TOKEN` | Authenticate non-interactively with a token (headless / CI).                        |
| `--plan PLAN`   | Plan to activate. Default `telys_developer`; use `telys_pro` for commercial rights. |
| `--no-install`  | Sign in and activate a license, but skip provisioning the runtime.                  |
| `--no-browser`  | Do not open a browser; print the verification URL to approve manually.              |

## What gets stored

Sign-in writes to your Telys home directory, `~/.telys` (override with `$TELYS_HOME`):

| File                | Contents                                                   |
| ------------------- | ---------------------------------------------------------- |
| `device_key.pem`    | The device's Ed25519 key (mode `0600`).                    |
| `device_id`         | This device's identifier (a UUID4 hex string).             |
| `token`             | The cached control-plane credential.                       |
| `api_key`           | The created Telys API key (rotatable).                     |
| `login_license.jwt` | The signed license issued to this device by `telys login`. |

The signed runtime, when installed, lands under `~/.telys/runtime/<platform>/` — see [**On-disk layout**](https://docs.telys.ai/operations/on-disk-layout.md).

## Expected result

A successful sign-in confirms the device, activates your plan, and (unless `--no-install`) provisions and verifies the runtime. Confirm readiness:

```bash
telys runtime status
echo $?          # 0 = runtime ready
```

{% hint style="info" %}
The free `telys_developer` tier is limited to **one device**. Sign in each additional machine separately; manage devices and subscription at [accounts.thyn.ai](https://accounts.thyn.ai). See [**Plans & licensing**](https://docs.telys.ai/licensing/tiers-and-pricing.md) for what each plan includes.
{% endhint %}

{% hint style="warning" %}
Used `--no-install`? No runtime was provisioned. Run `telys login` again without the flag, or install it directly with `telys runtime install`, before creating collections.
{% endhint %}

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Verify your install</strong></td><td>Confirm the runtime is ready and genuine.</td><td><a href="https://docs.telys.ai/start-here/verify-install.md">Verify install</a></td></tr><tr><td><strong>Quickstart: your first collection</strong></td><td>Create, add, and search on-device.</td><td><a href="https://docs.telys.ai/quickstarts/quickstart-first-collection.md">First collection</a></td></tr><tr><td><strong>Tiers &#x26; pricing</strong></td><td>Plans, devices, and commercial rights.</td><td><a href="https://docs.telys.ai/licensing/tiers-and-pricing.md">Plans &amp; licensing</a></td></tr></tbody></table>

Next: [**Verify your install**](https://docs.telys.ai/start-here/verify-install.md), then run the [**Quickstart**](https://docs.telys.ai/quickstarts/quickstart-first-collection.md).
