CLI Tool

The tt CLI lets you manage behaviour specs, runs, models, and datasets from the command line — without writing API calls. It is the recommended way to use Tuned Tensor.

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

Installation

Install globally via npm:

npm install -g @tuned-tensor/cli

Verify the installation with tt --version.

Or run from source:

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

Authentication

Store your API key so you don't need to pass it on every command:

tt auth login tt_your_api_key

Check your auth status:

tt auth status

Other auth commands:

tt auth logout — Remove stored credentials
tt -k tt_your_api_key <command> — Pass API key inline (overrides stored key)
tt -u https://your-api.example.com <command> — Use a custom base URL (e.g. for local dev)

Commands Overview

Command	Description
`tt auth`	Manage authentication (login, logout, status)
`tt specs`	List, create, get, update, delete behaviour specs
`tt runs`	List runs, start a run, get details, cancel, watch
`tt datasets`	List and manage datasets
`tt models`	List fine-tuned models
`tt balance`	Show available credits, held credits, and recent transactions
`tt topup`	Open Stripe Checkout to add credits
`tt init`	Create a local behaviour spec file (tunedtensor.json)
`tt push`	Push local spec to the Tuned Tensor API
`tt eval`	Validate a local behaviour spec file

Quick Examples

List specs and runs

tt specs list
tt runs list

Start a run

tt runs start <spec-id>

Use tt runs watch <run-id> to poll until the run completes.

Manage credits

tt balance              # show available credits, holds, and recent transactions
tt topup --amount 25    # open Stripe Checkout for a $25 top-up
tt topup                # interactive amount picker

tt balance separates available credits from total balance. Active runs and auto-tune sessions place estimated costs on hold, so a positive total balance can still be blocked by 402 insufficient_credits when available credits are too low.

Create a spec from a local file

# Create a local spec template
tt init -n "My Spec" --model meta-llama/Llama-3.2-3B-Instruct

# Edit tunedtensor.json, then push to the API
tt push

Local spec file (tunedtensor.json)

tt init scaffolds a tunedtensor.json file in the current directory. This is your source of truth — edit it, keep it in version control, and tt push whenever you want to sync it to Tuned Tensor.

The typical loop:

tt init --name "Customer Support Bot" --model Qwen/Qwen2.5-7B-Instruct-Turbo

# Edit tunedtensor.json — add examples, guidelines, constraints

tt push                    # create or update the spec on the server
tt runs start <spec-id>    # kick off a run
tt runs watch <run-id>     # stream status until complete

Spec validation with tt eval

tt eval validates your local tunedtensor.json. It checks required fields, confirms examples are present, warns when guidelines are missing, and checks simple constraints against example outputs. It does not call a model or the Playground API.

tt eval

Configuration

Credentials are stored in ~/.config/tuned-tensor/config.json (respects XDG_CONFIG_HOME).

API key precedence:

--api-key / -k flag
TUNED_TENSOR_API_KEY environment variable
Stored config from tt auth login

Global options

-k, --api-key <key> — Override stored API key
-u, --base-url <url> — Custom API base URL (default: https://www.tunedtensor.com)
--json — Output raw JSON
--no-color — Disable colors