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

# Upgrade

Upgrade the Telys SDK with pipx or pip, re-verify the signed runtime, and confirm the new version.

Upgrade Telys by upgrading the Python package: `pipx upgrade telys` or `pip install -U telys`. An SDK upgrade leaves your credentials, collections, and the installed runtime under `$TELYS_HOME` untouched. If a release expects a newer runtime or a refreshed license, `telys` tells you, and you re-verify.

{% hint style="warning" %}
Do not use `telys runtime update` to upgrade — it is a stub that prints "not implemented yet" and exits `2`. Upgrade the SDK with pip/pipx; refresh the runtime with `telys runtime install`.
{% endhint %}

## Upgrade steps

{% stepper %}
{% step %}

#### Note your current version

```bash
telys version
```

This prints `telys <version> (format v<N>)`, for example `telys 0.1.15 (format v1)`. Record it to confirm the change afterward.
{% endstep %}

{% step %}

#### Upgrade the package

Use the tab matching your install method.

{% tabs %}
{% tab title="pipx" icon="terminal" %}

```bash
pipx upgrade telys
```

{% endtab %}

{% tab title="pip" icon="python" %}

```bash
pip install -U telys
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Re-verify the runtime

Confirm the signed runtime still verifies against the new SDK:

```bash
telys runtime verify
```

If verification reports the runtime missing or out of date, reinstall it:

```bash
telys runtime install
```

{% endstep %}

{% step %}

#### Re-authenticate if prompted

If a command reports an expired or missing license, sign in again:

```bash
telys login
```

Add `--plan telys_pro` if you are on a commercial plan.
{% endstep %}

{% step %}

#### Confirm the new version

```bash
telys version
```

{% endstep %}
{% endstepper %}

## Expected result

`telys version` reports the newer release, and `telys runtime verify` succeeds:

```
telys 0.1.15 (format v1)
runtime VERIFIED  [macos-arm64]  /Users/you/.telys/runtime/macos-arm64
  artifacts: libty_runtime.dylib, libame_kernel.dylib, telys_manifest.json
  license: tier=developer exp=1788500000
```

Your collections under `$TELYS_HOME` open as before. The format version in parentheses is the on-disk format the SDK expects; if it is unchanged across the upgrade, no migration is needed.

{% hint style="info" %}
If `telys version` still shows the old number, your shell is resolving a stale `telys` on `PATH`. Run `pipx list` (pipx) or `which telys` (pip) to find which environment provides the command.
{% endhint %}

## Next steps

* [Verify your install](https://docs.telys.ai/start-here/verify-install.md) — a fuller post-upgrade health check.
* [Changelog](https://docs.telys.ai/resources/changelog.md) — what changed in this release.
* Next: [Uninstall Telys](https://docs.telys.ai/operations/uninstalling.md) if you need to remove it instead.
