/tinker command reference #

Pi users run these as /tinker .... Other coding agents replace /tinker with node scripts/agent-cli.mjs; see coding-agents.md.

Start here #

You only need a few commands for the normal workflow:

Goal	Command
See a free local demo	/tinker demo
Prepare your own data without API usage	/tinker improve <data> --goal "..." --budget demo
Check your setup	/tinker doctor
See the next step	/tinker next
Learn about Inkling	/tinker inkling
Choose Inkling or a checkpoint	/model

The demo budget makes no API calls. Commands using --yes may sample or train through the Tinker API.

/tinker inkling [info|sweep] #

Shows Inkling setup and registers base Inkling in Pi automatically. After setting TINKER_API_KEY, select either the 64K or 256K model with /model.

/tinker inkling
/tinker inkling sweep --prompt "A representative task" --efforts low,medium,high,xhigh --yes

The sweep calls Tinker's official sample_reasoning script. Presets map to low=0.2, medium=0.7, high=0.9, and xhigh=0.99; raw floats in [0, 1) also work. Options: --max-tokens, --temperature, --timeout, and --yes.

Install the required renderer stack with:

uv pip install -U 'tinker-cookbook[inkling]'

/tinker improve [input] [options] #

The easiest way to fine-tune. It prepares data, checks it, runs a small test, trains, evaluates the checkpoint, and registers it in Pi.

/tinker improve data.csv --goal "better support answers" --budget demo
/tinker improve data.csv --goal "better support answers" --budget smoke --yes
/tinker improve data.csv --goal "better support answers" --budget small --yes

In order, it does this:

1. prepares your data and editable Python files,
2. checks the environment and validates examples,
3. creates a held-out eval and measures the base model,
4. runs only two training steps first,
5. scales only after confirmation,
6. evaluates and registers the checkpoint,
7. shows wins, regressions, and suggested data improvements.

Budgets:

Budget	API usage	Meaning
demo	no	Setup, project files, doctor, lightweight validation. Stops before API calls.
smoke	yes	Baseline eval + 2-step smoke training.
small	yes	Smoke, then short training run, checkpoint eval, comparison, registration.
real	yes	Larger managed run. Still confirmation-first unless --yes.

Options:

Option	Default	Meaning
--goal / --metric	TODO	What should improve
--budget	demo	demo, smoke, small, or real
--model	thinkingmachines/Inkling	Base model / renderer model
--effort	0.9	Inkling baseline/checkpoint eval effort; both use the same value
--steps	budget default	Override scale-up max steps
--yes	false	Confirm API-using stages
--force	false	Overwrite generated files / rerun baseline
--alias	generated	Alias for registered checkpoint
--register	true	Register checkpoint for chat if one is found

/tinker deploy <checkpoint-or-alias> [alias] [options] #

Generates app/client snippets for using a trained Tinker sampler checkpoint through the OpenAI-compatible endpoint.

/tinker deploy latest
/tinker deploy my-sft
/tinker deploy tinker://.../sampler_weights/... support-sft

Writes by default:

deploy/<alias>/README.md
deploy/<alias>/.env.example
deploy/<alias>/python_client.py
deploy/<alias>/node_client.mjs
deploy/<alias>/fastapi_app.py

Options:

Option	Default	Meaning
--out	deploy/<alias>	Output directory
--alias	positional/generated	Friendly name
--force	false	Overwrite existing files

/tinker demo #

Zero-data demo. Copies the built-in customer-support example, creates a guided project, writes editable training/eval files, and shows the next step.

/tinker demo
/tinker next
/tinker doctor

This is the best first command for someone who wants to see what pi-tinker can do before bringing real data.

/tinker new [input] [options] #

The easiest entrypoint. Starts the golden path from CSV, JSON, JSONL, TXT/MD, a docs directory, or a built-in example.

/tinker new data.csv --goal "better customer support answers"
/tinker new data/train.jsonl --goal "structured extraction accuracy"
/tinker new --example customer-support

If the input is not chat JSONL, /tinker new converts it to data/train.jsonl, scaffolds editable Python/eval files, creates .tinker-pi/state.json, recommends starter settings, and shows the next wizard step.

Options:

Option	Default	Meaning
--goal / --metric	prompt/TODO	What should improve
--model	thinkingmachines/Inkling	Starter model
--example	false	Built-in example slug, e.g. customer-support
--out	data/train.jsonl	Output path when converting data
--prepare	false	Force conversion even for JSONL
--force	false	Overwrite generated files

/tinker prepare <input> [options] #

Converts common data into Tinker chat JSONL.

Supported inputs:

• CSV with question/answer, prompt/completion, input/output, or messages columns.
• JSON array, or object with examples[]/data[].
• JSONL with messages[] or prompt/response-style fields.
• TXT/MD files or directories for starter document-summary examples.

/tinker prepare support.csv --out data/train.jsonl

/tinker recommend [goal] [options] #

Gives a simple starter model/method/settings recommendation and the next commands.

/tinker recommend --goal "valid JSON extraction" --data data/train.jsonl

/tinker doctor [jsonl] #

Diagnoses local setup and project readiness: API key, Python, uv, Tinker CLI, Python imports, generated files, script compilation, selected data, and next wizard step.

/tinker doctor data/train.jsonl

/tinker examples list|copy [slug] #

Lists or copies concrete starter examples.

/tinker examples list
/tinker examples copy customer-support
/tinker demo
/tinker new --example structured-extraction

Current examples:

• customer-support
• structured-extraction
• concise-writing

/tinker start [jsonl] [options] #

Beginner step-by-step fine-tuning wizard. This is the simplest entrypoint for people who have examples and want to improve an open model without knowing the Tinker internals.

/tinker start data/train.jsonl --model thinkingmachines/Inkling --metric "support answer quality"

It creates project files, stores progress in .tinker-pi/state.json, and guides the user through:

1. environment setup,
2. data selection,
3. file creation,
4. validation,
5. baseline eval,
6. smoke test,
7. training/checkpoint discovery,
8. checkpoint eval,
9. before/after comparison,
10. registering the checkpoint for chat in Pi.

Options:

Option	Default	Meaning
--model	prompt / thinkingmachines/Inkling	Starter model
--metric	prompt	What should improve
--log	logs/sft-<timestamp>	Training log path
--force	false	Overwrite generated files

/tinker next #

Shows wizard progress and the next recommended action.

/tinker reset #

Deletes .tinker-pi/ wizard state for this project. It does not delete training data, generated scripts, logs, or checkpoints.

/tinker setup #

Checks local prerequisites:

• TINKER_API_KEY
• python3
• uv
• tinker CLI
• Python imports for tinker, tinker_cookbook, and tml_renderers
• Python 3.11+ for Inkling

It does not install anything automatically. If packages are missing, install:

uv pip install -U 'tinker-cookbook[inkling]'

/tinker init [jsonl] [options] #

Guided golden-path setup for a chat SFT project. In interactive Pi, it asks for missing values; in print/non-interactive mode, pass them as arguments.

Example:

/tinker init data/train.jsonl --model thinkingmachines/Inkling --metric "held-out support quality"

Generated files:

• README.md
• train_sft.py
• eval_checkpoint.py
• tinker.yaml
• notes/plan.md

Options are the same as /tinker sft, plus:

Option	Default	Meaning
--metric	prompt/TODO	What should improve before scale-up

/tinker validate <jsonl> [options] #

Runs two validation layers:

1. lightweight JSONL/message-shape checks in TypeScript,
2. Python-backed Tinker Cookbook renderer/token-mask validation when dependencies are installed.

The Python-backed check loads the recommended renderer for the model and produces a data-readiness report: READY, SMOKE ONLY, or FIX DATA FIRST. It tokenizes examples, checks trainable assistant-token masks, reports token and trainable-token histograms, identifies zero-trainable rows, flags truncation risk, lists longest examples, estimates token volume per epoch, and shows decoded previews plus trainable-token snippets.

Example:

/tinker validate data/train.jsonl --model thinkingmachines/Inkling

Options:

Option	Default	Meaning
--model	thinkingmachines/Inkling	Model for renderer/tokenizer validation
--examples	200	Number of examples to tokenize/check
--max-length	32768	Length threshold for truncation-risk warnings
--quick	false	Only run lightweight JSONL checks

/tinker eval init #

Creates a minimal editable eval harness:

• eval.py
• data/eval.jsonl

The eval JSONL format is:

{"messages":[{"role":"user","content":"..."}],"expected":"...","match":"contains"}

Supported match modes:

• contains
• exact
• prefix

/tinker eval baseline [options] #

Runs eval.py against a base model and writes eval_results/baseline.json by default.

/tinker eval baseline --model thinkingmachines/Inkling --effort 0.9 --yes

/tinker eval checkpoint <tinker-path> [options] #

Runs the same eval against a Tinker sampler checkpoint.

/tinker eval checkpoint tinker://.../sampler_weights/... --model thinkingmachines/Inkling --effort 0.9 --yes

For both baseline and checkpoint:

Option	Default	Meaning
--model	thinkingmachines/Inkling	Base model / renderer model
--effort	0.9	Inkling reasoning effort in [0, 1); keep identical before/after
--data	data/eval.jsonl	Eval JSONL
--out	eval_results/baseline.json or checkpoint-based name	Output JSON
--limit	all	Limit examples
--max-tokens	128	Generation limit
--temperature	0.0	Sampling temperature
--yes	false	Skip confirmation

/tinker eval compare <baseline.json> <candidate.json> #

Compares two eval result files and reports accuracy delta, wins, and regressions.

/tinker eval compare eval_results/baseline.json eval_results/step-20.json

/tinker sft <jsonl> [options] #

Scaffolds an editable supervised fine-tuning project using tinker-cookbook without the guided wizard.

Example:

/tinker sft data/train.jsonl --model thinkingmachines/Inkling --steps 20

Options:

Option	Default	Meaning
--model	thinkingmachines/Inkling	Tinker base model ID
--steps / --max_steps	20	Generated max_steps
--batch-size	8	Chat examples per batch
--lr / --learning-rate	2e-4	Learning rate
--test-size	0	Held-out examples for NLL eval
--max-length	32768	Max tokenized sequence length
--log	logs/sft-<timestamp>	Log/checkpoint directory
--force	false	Overwrite existing scaffold files

/tinker smoke [script] [--yes] #

Runs a 2-step smoke test:

python3 train_sft.py max_steps=2

It asks for confirmation in interactive mode because this can create a real Tinker training client and incur small API usage. Pass --yes to skip confirmation.

Example:

/tinker smoke train_sft.py --yes

Options:

Option	Default	Meaning
--timeout	1800000	Timeout in milliseconds

/tinker monitor <log_dir> #

Pins a live metrics widget above the editor and updates it every 5 seconds from:

• metrics.jsonl
• checkpoints.jsonl

Example:

/tinker monitor logs/sft-2026-06-03T18-08-42

Stop monitoring:

/tinker monitor --stop

/tinker checkpoints <log_dir> #

Reads checkpoints.jsonl, lists state/sampler checkpoints, and in interactive Pi lets you select a sampler checkpoint to register as a Pi model.

Example:

/tinker checkpoints logs/sft-2026-06-03T18-08-42

/tinker status [log_dir] #

Shows recent Tinker runs via:

tinker run list --limit 10

If log_dir is provided, also reads metrics.jsonl and displays a compact view of the latest numeric metrics.

/tinker use <checkpoint> [alias] #

Registers a Tinker sampler checkpoint as a Pi model using Tinker's Anthropic-compatible inference endpoint. Supply the base model so Inkling checkpoints retain reasoning, image, and effort capabilities.

Example:

/tinker use tinker://0034...:train:0/sampler_weights/000080 my-sft --base-model thinkingmachines/Inkling

Then select it with:

/model

Options:

Option	Default	Meaning
--alias	tinker-N	Display name in Pi
--base-model	unknown	Set to thinkingmachines/Inkling for an Inkling checkpoint
--context	65536 for Inkling, otherwise 32768	Context window to advertise to Pi
--max-tokens	16384 for Inkling, otherwise 4096	Max output tokens to advertise to Pi

Registrations are saved to:

~/.pi/agent/tinker-checkpoints.json

/tinker use --list #

Lists registered checkpoint models.

/tinker use --remove <alias-or-tinker-path> #

Removes a registered checkpoint model.