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: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 client (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 client, it adopts that client 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 client 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 reports that no tracebloc client was found (exit code 4), your client runs in another namespace — 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

Omit the flags on a terminal to run guided — the CLI asks for the task, name, and label column. Add --dry-run to check your data and your secure environment without creating anything.

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.

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.

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.

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.
`--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` (e.g. `512x512`). tracebloc never resizes — it rejects images of any other size. Default: read from your first image.
`--min-size`	Image tasks only: reject images smaller than `WxH` before ingesting. Default: no size check.
`--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)
`2`	The dataset settings failed validation, or the task isn’t supported
`3`	Local layout or kubeconfig error
`4`	Cluster reachable but no tracebloc client or shared storage found
`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):

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)

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
`tracebloc client create`	Register this machine as a client, or adopt the one already on this cluster
`tracebloc client status`	Online, offline, or pending (`--wait` polls until online)
`tracebloc data ingest <dataset>`	Ingest a local dataset (guided if you omit flags)
`tracebloc data list`	List the datasets in your secure environment
`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 client 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`)
`tracebloc prepare-host [user]`	Run once as an administrator so a non-admin user can install tracebloc
`tracebloc version`	CLI version, git SHA, and build date
`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

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

​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

Tasks

Dataset layout

Key flags

Exit codes

List and delete datasets

Validate a config locally

Command reference

CLI or Helm chart?