Metadata-Version: 2.5
Name: tenstorrent
Version: 1.1.0
Summary: Tenstorrent CLI (tt): the single entry point to the Tenstorrent software stack
Project-URL: Homepage, https://github.com/tenstorrent/tt-cli
Project-URL: Repository, https://github.com/tenstorrent/tt-cli
Project-URL: Issues, https://github.com/tenstorrent/tt-cli/issues
Project-URL: Changelog, https://github.com/tenstorrent/tt-cli/releases
Author-email: June Knauth <jknauth@tenstorrent.com>
Maintainer-email: Tenstorrent <jknauth@tenstorrent.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSE_understanding.txt
License-File: NOTICE
Keywords: accelerator,ai,cli,tenstorrent,tt-flash,tt-smi
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: packaging>=23
Requires-Dist: platformdirs>=4
Requires-Dist: rich>=13
Requires-Dist: tomlkit>=0.12
Requires-Dist: typer>=0.27.2
Requires-Dist: uv>=0.5
Description-Content-Type: text/markdown

# tt — the Tenstorrent CLI

One command for everything Tenstorrent.

`tt` is the single entry point to the Tenstorrent software stack. It either implements a
function natively or delegates to an existing tool (tt-smi, tt-installer, etc.) behind a stable interface.

> [!IMPORTANT]
> This is beta software. Expect breaking changes often as we add features. We welcome your feedback to help us improve tt-cli. If you have an issue or a comment, please don't hesitate to let us know through the GitHub [issues page](https://github.com/tenstorrent/tt-cli/issues/new).

## Quick start

Install with [uv](https://docs.astral.sh/uv/) (recommended):

```console
uv tool install tenstorrent
tt --help
```

(`uv tool update-shell` will make sure the `tt` binary is available on your PATH)

If you don't have uv, install it first:

```console
curl -LsSf https://astral.sh/uv/install.sh | sh
```

You can also install the CLI with any pip-compatible tool, such as pipx. We *highly recommend* placing tt-cli in an isolated venv so it can safely update itself. For other installation methods, see [DEVELOPERS.md](/docs/DEVELOPERS.md#other-ways-to-install-tt-cli).

## Telemetry

Telemetry is **opt-in**: nothing is collected or sent unless you say so. `tt` asks once, on first interactive run, and doesn't bother you about it on later runs.

If you opt in, `tt` records one event per command: the command name, exit code, duration, coarse OS facts, and argument values only when they match a known list (e.g. catalog model names). We never send free-form arguments, paths, error messages, or anything that identifies you or your machine. Exactly what is collected, every switch that controls it, and how delivery works: [TELEMETRY.md](/TELEMETRY.md).

If you change your mind about telemetry, use `tt config set telemetry.enabled true` or `false`. If you previously enabled telemetry, setting it to `false` opts you out and deletes anything not yet uploaded.

## Example commands

This is not an exhaustive list. For the full list of commands and options in each group, add `--help`, e.g. `tt model --help`.

| Device info | Functionality |
|---|---|
| `tt device status` | Detected devices: board, temperature, power, clock (`--json` for JSON output) |
| `tt device info [N…]` | Device metadata: PCI IDs, board id, firmware versions |
| `tt device reset [N…]` | Reset devices |
| `tt smi` | Hand this terminal to the interactive tt-smi TUI (`tt device top` also works) |

| Model serving | Functionality |
|---|---|
| `tt model list` | Models that run on this machine's detected hardware, from two sources: the released catalog (models Tenstorrent ships and tests via tt-inference-server) and community bundles (`--all` for every device; `--cached`, `--type`, `--hw` filters) |
| `tt model list --catalog` / `--community` | Narrow to one source: `--catalog` for the released catalog only; `--community` for bundles anyone has published with tt-model-manager on the Hugging Face Hub, not tested or maintained by Tenstorrent (served with `tt serve <namespace>/<name>`); `--community --cached` for the ones installed here |
| `tt model search [QUERY]` | Search the Hub for published tt-model bundles (`--catalog` for community-catalog listings only; `--arch`, `--limit`) |
| `tt model info NAME` | Model metadata: engines, per-device support/status, requirements, cache state; for a tt-model bundle id, its manifest and compatibility verdict (or catalog row) |
| `tt model pull NAME` | Download a catalog model's weights, a tt-model bundle, or any HuggingFace repo's weights (`--bundle` / `--weights-only` override detection; `--offline`; bundles: `--force`, `--no-weights`) |
| `tt model profiles NAME` | A pulled bundle's serve profiles and its default |
| `tt serve [NAME] [-- ARGS…]` | Serve a model via tt-inference-server, TT-Studio, or tt-model-manager for a community bundle id (`--inference-server`, `--studio` or `--model-manager` forces a path; with no NAME, pick from what that backend serves; bundles: `--profile`, `--detach`, `--print`, `--refresh`, `--no-update-check`, `--no-weights`) — see [Serving backends](#serving-backends) |
| `tt model curl [PROMPT]` | Send a chat completion to the model being served; unknown options go into the request body (`--max-tokens 40`), `--print` shows the curl instead |
| `tt model stop NAME...` | Stop running model servers; when studio deployed one, studio stops the model and then its own containers and services (`--profile` to stop only one profile of a bundle; `tt model stop $(tt model ps --names)` stops everything) |
| `tt model rm NAME` | Remove a model's local artifacts, keeping its weights unless `--include-weights` (`--dry-run`, `--yes`) |
| `tt model login` | Log in to the Hugging Face Hub for gated or private bundles and weights (`--token`) |
| `tt model publish` / `unpublish` | List or delist your pushed bundle in the community catalog; `tt model package` / `package-thin` / `push` forward to tt-model's authoring commands unchanged |
| `tt model ps` | Model servers running on this machine: name, backend, port, health, uptime (`--all` includes stopped containers; `--no-probe` skips the HTTP health check; `--names`/`-n` prints only the names) |
| `tt model logs NAME` | Output of a served model: the newest tt-inference-server log file for a catalog model, or `tt-model logs` for a bundle (`--follow`; `--tail N`; `--since` needs a running container; `--profile` for bundles) |

| Other | Functionality |
|---|---|
| `tt update [VERSION]` | Converge system software + tools onto the latest tested "golden" set (`--dry-run` to preview; `--yes` to skip the confirmation; `--force` to allow downgrades to golden; a tt-installer VERSION runs that release instead and implies `--force`) |
| `tt config` | Open the config file in your editor; `list`/`get`/`set`/`path` for scripting, `sync`/`reset` to maintain the file |
| `tt report issue` | Open a prefilled GitHub issue on tt-cli (environment details auto-collected; `--no-browser` to just print the URL) |
| `tt report bundle` | Collect a redacted support bundle (environment, tt-smi snapshot, config, tt and inference-server logs, container logs) and open a pre-filled email to support@tenstorrent.com with it attached (`--title` for the subject, `--no-open` to only write the files, `--mailto` for webmail, `--output` to choose the path) |
| `tt self update` | Upgrade `tt` itself where it owns its environment (`--check` to only look) — see [Keeping tt up to date](/docs/DEVELOPERS.md) |

For a comprehensive view on packaging, publishing and pulling down community models [read more here](/docs/community-models.md)

## Watching a model come up

A first serve can take ten minutes: the image is pulled, the weights are fetched, the
device is opened, the KV cache is sized and the model is warmed up. `tt serve` shows
those as a live checklist instead of the server's thousands of log lines, and returns
only once the endpoint actually answers — so `tt launch` straight afterwards works.
There is no flag for it; it is what serving looks like.

`tt serve` prints `tt model logs <model> --follow` before it starts, so that can be run in another terminal to watch the raw boot.

`TT_SERVE_READY_TIMEOUT=<seconds>` raises the one-hour bound on that wait. Ctrl-C stops
watching, not the server — the container keeps booting, and `tt model stop <model>`
ends it.

Both backends draw the same checklist. The long half of a serve — engine, device,
weights, KV cache, warmup — is the container's own boot, so tt reads
`docker logs` and classifies it itself rather than trusting either tool to
narrate it; only the preparation differs, and a bundle simply has one extra step.
[docs/serve-progress-contract.md](/docs/serve-progress-contract.md) has the
details, including what tt-model-manager emits.

Serving a catalog model needs a Hugging Face token: tt-inference-server fetches weights
and tokenizers from the Hub and asks for one interactively when `HF_TOKEN` is unset.
Run `hf auth login` once (or export `HF_TOKEN`) and `tt serve` stays non-interactive;
without one it says so up front rather than stopping at a prompt you cannot see.

## Interactive clients with `tt launch`

`tt serve` gives you an OpenAI-compatible endpoint; `tt launch` points a client at it. tt discovers what is running by asking the server itself (`GET /v1/models`) and configures the client's endpoint for you. `tt model ps` lists what is being served and on which port, using the same probe.

```bash
tt launch list                         # what can I connect, and is it usable now?
tt serve Qwen3-32B --port 8000         # in another terminal
tt launch openwebui --web-port 3080    # pull and run its container, after you confirm
tt launch stop openwebui               # stop it, keeping its data
```

## Serving backends

`tt serve NAME` picks the serving path from the model:

- **inference-server** — every model `tt model list` shows with source `tt-inference-server`, driven through tt-inference-server's `run.py`. Preferred whenever it knows the model.
- **studio** — every model in [TT-Studio](https://github.com/tenstorrent/tt-studio)'s catalog: most are tt-inference-server's, which studio deploys from the same images, plus the few only studio carries (today `Qwen3.5-9B` and `Qwen3.8-27B`), for which it is the default. `tt serve NAME --studio` picks it for any of them. tt clones studio's latest tagged release on first use and runs `run.py run NAME` from it, which brings the stack up, deploys the model and reports the endpoint; `tt model stop NAME` runs its `--stop-model` for anything studio deployed, then `--stop` to take studio's containers and services down with it; a deploy that fails is followed by the same `--stop`, so a broken deploy leaves nothing of studio's running. Single-chip models (a `P150` entry) are listed for the multi-card Blackhole boards too, the way studio runs them — one chip of a P300. Studio allocates chips and ports itself, so `--device` and `--port` are ignored there with a warning.
- **model-manager** — tt-model bundles (`namespace/name`) neither catalog knows.

`tt model info` shows the paths a model is served by (`inference-server, studio` for a model both offer). `--inference-server`, `--studio` or `--model-manager` forces a path and refuses one the model does not offer. With no model, `tt serve --studio` (or `--inference-server`, `--model-manager`) lists what that path serves on this machine — for studio, its whole catalog — and asks for a number; the picker needs a terminal and is off under `--json`/`--quiet`.

Every path inherits a Hugging Face token: `HF_TOKEN` from the shell if set, else the token `hf auth login` stored (`HF_TOKEN_PATH`, then `<HF_HOME>/token`). `tt serve --dry-run` names the source without printing the token.

## Configuration

Configuration is TOML at `~/.config/tenstorrent/config.toml` (XDG-compliant). `tt config` opens it with
explanatory comments; edits preserve comments. Prefer `tt config set <key> <value>` over hand-editing: it puts the key in the correct
table.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](/CONTRIBUTING.md) for details on:

- Reporting bugs via GitHub Issues
- Submitting pull requests
- Code standards and SPDX header requirements
- Our weekly PR review cadence

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](/LICENSE) file for the overall license, except where specified.

For clarification on how the Apache 2.0 license applies to this project, including hardware and patent considerations, see [LICENSE_understanding.txt](/LICENSE_understanding.txt).
