tracebloc CLI

The tracebloc CLI is how you manage your secure environment and its data from your own machine: sign in, connect this machine to tracebloc, ingest datasets, list and delete them, check the connection, and set how much of the machine training may use. tb is the short alias — every command on this page works as tb … too.

You never touch Helm, edit YAML, or run kubectl. tracebloc data ingest finds your secure environment, checks your data locally, copies it in, runs the ingestion, and streams the progress for you.

Install

If you deployed with the Quick Start one-liner, the CLI is already installed. Otherwise, install the CLI on its own:

macOS / Linux
Windows (PowerShell)

curl -fsSL https://github.com/tracebloc/cli/releases/latest/download/install.sh | sh

irm https://github.com/tracebloc/cli/releases/latest/download/install.ps1 | iex

Binaries are cosign-signed and multi-arch; the installer also creates the tb alias (unless an unrelated tb is already installed). Pin a version with sh -s -- --version vX.Y.Z (or $env:TRACEBLOC_RELEASE_VERSION='vX.Y.Z' on Windows). Verify:

tracebloc version

Run tracebloc with no arguments for a welcome screen that shows who you’re signed in as, whether your secure environment is running, and the next commands to try.

tracebloc login          # browser device flow: open the URL on any device, sign in, approve the code
tracebloc client create  # register this machine as a secure environment (the installer runs this for you)
tracebloc client status  # online, offline, or pending — add --wait to poll until online

login works on a headless or SSH machine — the browser doesn’t have to be on the same machine — and is safe to re-run (pass --force to switch accounts). client create takes its name from --name or TRACEBLOC_CLIENT_NAME, otherwise it generates one; on a cluster that already runs a secure environment, it adopts that one instead of creating a second one.

Check your secure environment

tracebloc doctor         # is it connected and ready to train? Tells you what to fix if not
tracebloc cluster info   # which cluster, namespace, and secure environment the next data ingest will target
tracebloc resources      # how much of this machine tracebloc may use

doctor exits 0 when healthy, 2 when it found a problem, 3 when it can’t read your local config. --diagnose writes a redacted support bundle you can send to tracebloc.

If a command exits with code 4, it found no secure environment or shared storage on the cluster, or the cluster’s data ingestor is too old for the task. The error message says which. If the ingestor is too old, try again after your secure environment’s hourly auto-upgrade has run (tracebloc upgrade updates only the CLI); otherwise run tracebloc doctor. If your secure environment runs in a namespace the CLI did not find, add -n <your-namespace>. cluster info, doctor, resources, and the data commands all accept -n, --context, and --kubeconfig.

Ingest a dataset

tracebloc data ingest copies a local dataset into your secure environment’s storage, runs the ingestion, and follows it to completion. Your data never leaves your infrastructure.

tracebloc data ingest ./train.csv \
  --task tabular_classification \
  --name my_dataset_train \
  --intent train \
  --label-column label

For object detection, there is no label column. The CLI reads the image size from your first image; pass --target-size to state it:

tracebloc data ingest ./visdrone \
  --task object_detection \
  --name visdrone_train \
  --intent train \
  --target-size 1920x1080

Ingest the test split the same way with --intent test and its own --name. Omit the flags on a terminal to run guided: the CLI asks four numbered questions (split, name, path and task), then the questions your task needs, such as the label column or the image resolution. See Guided ingest. Add --dry-run to check your data and your secure environment without creating anything.

Guided ingest

Run tracebloc data ingest on a terminal without flags, and the CLI asks one question at a time. A flag you do pass becomes that question’s default, and the question is still asked. If your flags already answer every question, the CLI goes straight to the review.

Step	Question	What you can type
1	Split: training or test data	`1` or `train`, `2` or `test`
2	Name: the dataset name	Letters, digits and underscores, starting with a letter or underscore, for example `churn_train`
3	Path: where your data is	The path to the file or folder that holds your data (see Dataset layout)
4	Data type: asked only when the CLI can’t tell from the layout	`tabular`, `image` or `text`
4	Task: the task this data is for	The task’s number, or its `--task` value, for example `image_classification`
	Label or Target: the column to learn	A column from your CSV header. Not asked for object detection, masked or causal language modeling, seq2seq or embeddings
	Keypoints: keypoint detection only	A whole number, for example `17`
	Resolution: image tasks	`WxH`, or Enter to read it from your first image (see Image resolution)
	Column types: tabular and time-series tasks	Enter to accept the inferred types, or overrides such as `age:INT,price:FLOAT`
	Label policy: regression, forecasting and time-to-event tasks	`bucket` or `passthrough`
	Time column: time-to-event prediction only	The column name; Enter takes `time`
	Proceed with the ingest? after the review	`y`, `yes`, `n` or `no`; Enter takes the capital letter in `(Y/n)`

Questions with a numbered list. Type the option’s number, or its name: the whole option, or its first word (for a task, the --task value alone). Case doesn’t matter. A number always means the position in the list. If a word matches more than one option, or the answer matches none, the CLI asks again: “Type a number from 1 to N or the option’s name”. Press Enter to take the default shown in brackets, for example [2]. Other questions. Type the value. Press Enter to take the default shown in brackets. If the answer isn’t valid, the CLI says why and asks again. On any question except the last, type ? for a short hint. Press Ctrl-C to stop at any step, or answer n at the last question: the CLI prints “Cancelled — nothing was ingested.” and creates nothing. Defaults from your last run. The defaults for split, name, path and task come from your previous guided ingest that finished or ran with --dry-run. The CLI saves those four answers in ~/.tracebloc/ingest-recall.json. Each dataset needs its own name, so check the name and the path when you switch between train and test: after ingesting the test split, the name offered may still be the test dataset’s. If the name you confirm already holds a dataset, the CLI asks “A dataset named … already exists — replace it?” before it copies anything. Answer n unless you mean to replace that dataset.

Image resolution

For an image task, the guided run asks for Image resolution: the size your images already are, written WxH — the width, the letter x, then the height, for example 1920x1080. tracebloc checks that every image has exactly this size; the ingest doesn’t resize them (training later resizes to the model’s input size). Press Enter to read it from your first image. --target-size and --min-size take the same WxH format. Type the letter x between the two numbers, not the × sign your file manager may show. To read an image’s size:

macOS: run sips -g pixelWidth -g pixelHeight <file> in Terminal, or select the file in Finder, choose File > Get Info and read Dimensions under More Info.
Linux: run file <file>; for a JPEG or PNG it prints the width and height.
Windows: right-click the file, choose Properties > Details and read Dimensions.

tracebloc data push (and tracebloc dataset push) is a deprecated alias of tracebloc data ingest and will be removed in a future release. Use data ingest.

Tasks

Pick one with --task:

Family	`--task` values
Image	`image_classification`, `object_detection`, `keypoint_detection`, `semantic_segmentation`
Text	`text_classification`, `masked_language_modeling`, `causal_language_modeling`, `seq2seq`, `token_classification`, `sentence_pair_classification`, `embeddings`
Tabular / time series	`tabular_classification`, `tabular_regression`, `time_series_forecasting`, `time_series_classification`, `time_to_event_prediction`

Dataset layout

What you pass as <dataset> depends on the task family. A bare .csv file is accepted only for tabular and time-series tasks; image and text datasets must be a folder.

Tabular / time series
Image
Text

A single CSV — pass the file itself, or a folder holding exactly one .csv:

churn.csv

Time-series classification adds fixed sequence_id and timestamp columns — see its template.

Image classification, keypoint detection, and semantic segmentation: a folder with labels.csv and images/. Semantic segmentation adds masks/ with one PNG mask per image, named <image>_mask.png (001_mask.png for 001.jpg), and labels.csv needs a populated mask_id column.

cats_dogs/
├── labels.csv
└── images/
    ├── 001.jpg
    └── ...

Object detection: images/ plus annotations/ (one Pascal VOC .xml per image, 001.xml pairs with 001.jpg) and no labels.csv. Labels come from each object’s <name> in the XML; a stray labels.csv is ignored, not rejected.

visdrone/
├── images/
│   └── 001.jpg
└── annotations/
    └── 001.xml

Images must be .jpg, .jpeg, or .png, and all images in one dataset must share a single type.

A folder with labels.csv and a folder of .txt files. Every text task uses texts/, except masked language modeling, which uses sequences/.

reviews/
├── labels.csv
└── texts/
    ├── 001.txt
    └── ...

Each task’s dataset template shows its exact columns and an example — for example causal language modeling, sequence-to-sequence, token classification, sentence-pair classification, embeddings, and semantic segmentation.

One data ingest is capped at 1 GiB total and 500 MiB per file. For image datasets, the images and their annotation or mask files count together.

If your dataset is over the cap, make it smaller (JPEG instead of PNG, a lower resolution, or fewer samples), or ingest it with the Helm ingestor chart, which has no size limit.

Key flags

Flag	What it does
`--task`	The task this data is for (table above). Omit it on a terminal to pick interactively.
`--name`	A name for the dataset — starts with a letter or underscore, then letters, digits, or underscores. You reference it by this name when you start an experiment.
`--intent`	`train` (default) or `test`.
`--label-column`	The label column — in `labels.csv` for image and text tasks, in the data CSV for tabular. Required for every task that has a label column: tabular, time series, `image_classification`, `keypoint_detection`, `semantic_segmentation`, `text_classification`, `token_classification`, and `sentence_pair_classification`. On a terminal, guided mode asks for it; with flags only, a missing value fails validation. Rejected for `object_detection` and the self-supervised text tasks (`masked_language_modeling`, `causal_language_modeling`, `seq2seq`, `embeddings`).
`--dry-run`	Check your data and the target without creating anything.
`--no-input`	Never prompt; fail on missing required values (for CI and scripts).
`--overwrite`	Replace a dataset of the same name: its current data is deleted first (same as `data delete`), then the new data is ingested.
`--output-json`	Print a machine-readable JSON result on stdout (human output goes to stderr; implies `--no-input`).
`--detach`	Exit as soon as the ingestion run is accepted, without streaming progress.
`--schema`	Tabular / time series only: column types as `col:TYPE,col:TYPE` (e.g. `age:INT,price:FLOAT`). Default: inferred from the CSV.
`--label-policy`	`tabular_regression`, `time_series_forecasting`, `time_to_event_prediction` only: `bucket` (default — bins the target so the raw value never leaves your secure environment) or `passthrough`.
`--time-column`	`time_to_event_prediction` only: the time/duration column (default: a column named `time`).
`--target-size`	Image tasks only: the resolution your images already are, as `WxH` with the letter `x` (e.g. `512x512`); see Image resolution. The ingest doesn’t resize images — it rejects images of any other size (training later resizes to the model’s input size). Default: read from your first image, so pass it explicitly if your first image is not the size the rest share.
`--min-size`	Image tasks only: reject images smaller than `WxH` before ingesting. Default: no local check, but your secure environment still rejects images smaller than 32x32.
`--number-of-keypoints`	`keypoint_detection` only (required): keypoints per sample, e.g. `17` for COCO pose.

Run tracebloc data ingest --help for the full list.

Exit codes

Useful when you script data ingest:

Code	Meaning
`0`	Ingested successfully (with `--detach`: copied and submitted)
`1`	Any other failure
`2`	The dataset settings failed validation, or the task isn’t supported
`3`	Local layout or kubeconfig error
`4`	Cluster reachable but no secure environment or shared storage found, or its data ingestor is too old for this task (nothing was copied)
`5`	The CLI couldn’t get permission to submit the ingestion run
`6`	A dataset with this name already exists — re-run with `--overwrite` or pick a different `--name`
`7`	Copying the files into your secure environment failed (or, with `--overwrite`, deleting the old dataset failed)
`8`	Your secure environment rejected the ingestion run
`9`	The ingestion run failed, or finished with row-level failures shown in its summary

List and delete datasets

tracebloc data list                      # datasets in your secure environment: split, records, size, format, ingested when
tracebloc data delete my_dataset_train   # delete a dataset's data from your secure environment

data delete is destructive and can’t be undone; it asks for confirmation (--yes skips it, --dry-run shows what would be deleted). The dataset’s catalog entry on tracebloc is kept as a record and marked unavailable, so experiments that used it keep their history. tracebloc data rm is an alias. Both commands accept --output-json.

Validate a config locally

tracebloc data validate ingest.yaml

Checks an ingest.yaml against the embedded v1 schema in milliseconds — no cluster required. Exits 0 when valid, 2 on schema violations, 3 when the file can’t be read or parsed. The declarative form (also accepted by the Helm ingestor chart), shown for a tabular dataset:

apiVersion: tracebloc.io/v1
kind: IngestConfig
category: tabular_classification
table: my_dataset_train
intent: train
csv: /data/shared/my_dataset/train.csv
label: label
schema:
  age: INT
  income: FLOAT
  label: VARCHAR(32)

For object_detection, leave out csv and label and give images and annotations instead.

Command reference

Command	Does
`tracebloc login`	Sign in in your browser (device code)
`tracebloc logout`	Sign out — revokes the token and clears it locally
`tracebloc auth status`	Whether you’re signed in, and to which environment (`--check` exits `0` only when signed in, else `1`)
`tracebloc client create`	Register this machine as a secure environment, or adopt the one already on this cluster
`tracebloc client remove <id>`	Revoke a secure environment on your account by its Client ID or client number, keeping its history: one whose machine is gone, or, from CLI v0.11.24, one you set up from this machine on another cluster such as EKS. Refuses the one on this machine’s own cluster (use `tracebloc delete`). `--yes` skips the typed-name prompt; `--force` removes it even if it reports online or training, or the CLI can’t confirm where it runs
`tracebloc client status`	Online, offline, or pending (`--wait` polls until online). `--seal` instead runs the chart’s conformance checks and reports sealed or unsealed (exit `0` sealed, `2` unsealed or unknown, `3` cluster unreachable, `4` no secure environment found)
`tracebloc data ingest <dataset>`	Ingest a local dataset (guided if you omit flags)
`tracebloc data list`	List the datasets in your secure environment (`--all` adds system tables)
`tracebloc data delete <name>`	Delete a dataset’s data from your secure environment
`tracebloc data validate <path>`	Validate an `ingest.yaml` locally
`tracebloc cluster info`	Which cluster, namespace, and secure environment the CLI targets
`tracebloc doctor`	Check the connection and readiness to train (`--diagnose` for a support bundle)
`tracebloc resources`	How much of this machine tracebloc may use, in total and per experiment
`tracebloc resources set`	Raise the per-experiment ceiling (`--cores`, `--memory`, `--gpus`, or `max`); applies to the next experiment
`tracebloc upgrade`	Update the CLI to the latest signed release (the secure environment’s services upgrade themselves every hour)
`tracebloc delete`	Remove tracebloc from this machine (`--keep-data` keeps `~/.tracebloc`; `--yes` skips the typed-name prompt and `--confirm-name <name>` confirms without a terminal; `--force` offboards even if the secure environment still reports online; `--for-reinstall` revokes first, tears down only if that worked, and keeps the CLI and your sign-in — `--yes` does not confirm it: type the name, or pass `--confirm-name` off a terminal)
`tracebloc prepare-host [user]`	Run once as an administrator so a non-admin user can install tracebloc. With `TRACEBLOC_SUBSTRATE=k3s` it sets up native k3s and adds the user to the `tracebloc` group; see Linux prerequisites
`tracebloc version`	CLI version, git SHA, and build date (`--output-json` for JSON; `tracebloc --version` prints the same line)
`tracebloc completion`	Generate shell completion

data also answers to dataset. Add --help to any command for the full flag list, --verbose for step-by-step detail, or --plain to turn off color. For lifecycle tasks (upgrade, stop/start, uninstall), see Operations.

CLI or Helm chart?

Both submit to the same ingestion protocol — pick the one that fits your workflow:

CLI — local data on your workstation; the everyday choice. Handles copying and submission for you.
Helm ingestor chart — Kubernetes-native / GitOps, when your data is already staged on the cluster.

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Install

Check your secure environment

Ingest a dataset

Guided ingest

Image resolution

Tasks

Dataset layout

Key flags

Exit codes

List and delete datasets

Validate a config locally

Command reference

CLI or Helm chart?

​Install

​Sign in and connect this machine

​Check your secure environment

​Ingest a dataset

​Guided ingest

​Image resolution

​Tasks

​Dataset layout

​Key flags

​Exit codes

​List and delete datasets

​Validate a config locally

​Command reference

​CLI or Helm chart?

Install

Sign in and connect this machine

Check your secure environment

Ingest a dataset

Guided ingest

Image resolution

Tasks

Dataset layout

Key flags

Exit codes

List and delete datasets

Validate a config locally

Command reference

CLI or Helm chart?