> 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 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.0b2 (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.0b2 (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](/start-here/verify-install.md) — a fuller post-upgrade health check.
* [Changelog](/resources/changelog.md) — what changed in this release.
* Next: [Uninstall Telys](/operations/uninstalling.md) if you need to remove it instead.


---

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