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.

Quick start

Install with uv (recommended):

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:

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.

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.

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.

For a comprehensive view on packaging, publishing and pulling down community models read more here

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 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.

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'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 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 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.