Tuned Tensor

TT CLI

Use tt to train models locally or in the cloud, compare results, verify artifacts, and serve models. Its local agent helps you prepare workflows and inspect runs.

Open source (Apache-2.0). Source and issues at github.com/tunedtensor/tuned-tensor-cli. Published to npm as @tuned-tensor/cli.

Installation

On Linux or macOS, the installer installs Node.js 22.19+ if needed and puts tt on your PATH. Local adapter training additionally needs uv, Linux, and a compatible NVIDIA CUDA GPU. TT prepares the packaged Python environment on first use.

curl -fsSL https://tunedtensor.com/install.sh | sh
tt --version

Inspect the script first with curl -fsSL https://tunedtensor.com/install.sh | less. Set TT_VERSION on the sh process to pin a specific release, for example: curl -fsSL https://tunedtensor.com/install.sh | TT_VERSION=0.17.0 sh. Without it, npm installs the latest release. If npm's global prefix is not writable, the installer uses ~/.local.

Or install the npm package directly:

npm install -g --ignore-scripts @tuned-tensor/cli
tt --version

Uninstall with the same tool that installed it:

# curl installer or npm
npm uninstall -g @tuned-tensor/cli

If the installer used ~/.local, target that prefix instead:

npm uninstall -g --prefix ~/.local @tuned-tensor/cli

Run from source:

git clone https://github.com/tunedtensor/tuned-tensor-cli.git
cd tuned-tensor-cli
npm install
npm run build
npm link

Commands

tt                     # open the conversational terminal
tt shell               # same, explicitly
tt status              # local project context (no GPU probe)
tt init                # create tunedtensor.json
tt doctor              # check GPU, uv, and spec
tt validate            # validate the spec
tt pipeline run --spec tunedtensor.json  # train, evaluate, and write the paired report
tt runs list           # list local runs
tt runs report <run-id> # inspect one local run
tt models …            # prefetch, verify, serve, activate
tt serve               # OpenAI-compatible local server
tt pipeline …          # define local training and evaluation steps
tt agent …             # configure the local TT agent
tt auth login          # save one Tuned Tensor access token
tt cloud …             # cloud specs, datasets, runs, and models
tt usage               # managed agent usage
tt balance             # cloud credit balance
tt publish <run-id>    # publish a local report to the dashboard

These commands also work in scripts and CI. tt --help lists all commands. Local commands work without a Tuned Tensor token. Use tt cloud … for cloud operations; both modes use the same CLI.

Agent shell

TT runs the agent loop and stores conversations on your machine. Direct local commands work without a token. To use the managed model, create an access token in the dashboard settings and save it once:

tt auth login
tt
› What happened in my latest training run?

If you have not selected a provider, login selects the managed model automatically. Tuned Tensor chooses the model and sends requests to OpenRouter through its API. Your TT token covers this model access and cloud commands, so there is no separate model key to configure.

To choose your own model, use your OpenRouter key. Requests go directly to OpenRouter, and you can select any OpenRouter model ID:

tt
› /login openrouter
› /model openrouter/<model-id>

Use /login tunedtensor to save a Tuned Tensor token inside the shell, or /model tunedtensor/managed to return to managed inference after choosing your own provider. Either option works with local or cloud workflows. Cloud commands require a TT token.

For your own provider, /login <provider> prompts for its API key with hidden input. Use /login to list providers first. After saving a key, you can select a model from a script:

tt agent models --all
tt agent configure --provider openrouter --model <model-id> --thinking off
tt agent status

--thinking accepts off, minimal, low, medium, high, xhigh, or max for supported provider models. Managed inference uses off; the server controls its model. Override the saved selection for one process with TUNED_TENSOR_AGENT_PROVIDER, TUNED_TENSOR_AGENT_MODEL, and TUNED_TENSOR_AGENT_THINKING. These values are not credentials.

Ordinary sentences go to the selected agent model. The model has no shell or general filesystem tool. Known commands such as runs list, doctor, and models list still execute directly. Prefix a command with : to make that intent explicit.

› What happened in my latest training run?
› runs list

Conversations persist under ~/.tuned-tensor/agent/threads (or $TUNED_TENSOR_HOME/agent/threads). Use /new, /threads, and /resume <id> to manage them. The agent can prepare a new local spec folder with at least two examples. Creating it requires /approve and fails if the path already exists. A proposed pipeline runs only as a dry run after approval. Start or cancel actual training with a direct CLI command.

/model shows and changes the TT agent model. The training base model is set separately in your spec. List providers with /model, list one provider with /model <provider>, search with /model <query>, or switch with /model <provider>/<model>.

Quick examples

Train locally

tt init --name "Support Adapter" --model Qwen/Qwen3.5-2B --profile spark
# Edit tunedtensor.json and replace both placeholder examples.
tt doctor tunedtensor.json
tt validate tunedtensor.json
tt models prefetch tunedtensor.json
tt pipeline run --spec tunedtensor.json
tt runs report <run-id>

See Local Training for GPU requirements, verification, activation, and serving.

Inspect runs and models

tt runs list
tt runs report <run-id>
tt models list
tt models verify local-<run-id>
tt serve local-<run-id>
tt status

Use tt --json when a script needs to parse command output. tt runs list returns a compact summary of local runs.

Cloud runs and reporting

Use the same TT installation for cloud operations. The dashboard shows reports, datasets, and models. New training uses the local pipeline with optional GPU execution in your own AWS account.

tt auth login
tt cloud push --file tunedtensor.json
tt cloud runs list
tt cloud runs report <run-id>
tt usage
tt balance

See Run workflows for AWS GPU setup. Use tt topup or billing settings to add cloud credits. tt publish <local-run-id> shares a local run report with the dashboard when you choose to upload it.

The agent can prepare cloud spec changes for /approve. Approval requires the same TT token and API origin used to prepare the proposal. If either changes, restore the original token and API origin or prepare a new proposal. Use /reject to discard a proposal without applying it.

Pipelines

tunedtensor.json is the source of truth for behavior and training settings. TT uses its embedded pipeline or derives the canonical recipe from the saved spec; a separate recipe file is not required.

  • Adapter (default): LoRA fine-tuning of a text model.
  • Foundation: tokenizer and GPT training from scratch, with fine-tuning and optional reinforcement learning.
  • Decision: typed choice, yes/no, or score predictions; training runs on CPU, Apple MPS, or CUDA.

Orchestration stays local. Adapter and foundation training need a supported NVIDIA CUDA host, either local or your own AWS instance configured through runtime.gpu in the spec. Decision training runs on the machine executing TT and does not use runtime.gpu.

tt pipeline validate --spec tunedtensor.json
tt --json pipeline plan --spec tunedtensor.json
tt pipeline run --spec tunedtensor.json --dry-run
tt pipeline run --spec tunedtensor.json

Explicit --file remains supported for separate recipes, but cannot override a conflicting embedded pipeline. See the CLI pipeline guide for engine-specific stages, customization, and legacy project migration.

tunedtensor.json

tt init creates a tunedtensor.json file in the current directory. Edit it, keep it in version control, and run from that file. The fields are described in the spec file guide.

Configuration

TT stores the account token and model selection in ~/.tuned-tensor/config.json, provider keys in ~/.tuned-tensor/agent/auth.json, and custom model definitions in ~/.tuned-tensor/agent/models.json. Set TUNED_TENSOR_HOME to use another directory. Provider keys then live in $TUNED_TENSOR_HOME/agent/auth.json.

When TUNED_TENSOR_HOME is unset, TT continues using an existing XDG config or agent directory until the corresponding file or directory exists under ~/.tuned-tensor/. Credentials from ~/.pi/agent/ are not imported. Use tt auth status to check the selected account origin and whether a TT token is configured.

  • --json: output raw JSON
  • --no-color: disable colors
  • -h, --help: show command help

See also