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 <path> finds your secure environment, checks your data on your machine, copies it in, and follows the ingest to the end.

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 <path> ingests a dataset: it copies the files into your secure environment’s storage, checks them there, and lists the dataset on tracebloc. Your data never leaves your infrastructure.

tracebloc data ingest ~/data/churn_train.csv

tracebloc data <path> is a shortcut for the same command. On a terminal, the CLI looks at the files first and asks only what they can’t say. An ingest goes through these steps, and nothing is copied until the last one:

The path. Drag a file or folder into the terminal, or type its path.
The questions. For a table, which column the model should predict. The task when two tasks fit the data.
The checks. The layout, the values, and what training needs. A problem that stops the ingest is a blocker; one you decide on is a warning.
The summary. What goes where, and what leaves your secure environment.
Ingest it as Training data or Test data. Your answer starts the copy.

To ingest from a script or CI, pass the answers as flags with --no-input; see Scripted ingest.

Guided ingest

tracebloc data ingest <path> on a terminal runs the guided ingest on this page. The commands, flags and checks in Scripted ingest work the same from a script.

At each question, type the option’s number or its name, or press Enter for the answer shown in brackets. Press Ctrl-C at any question to stop; nothing is ingested.

Give the path

Type the path after tracebloc data, or run tracebloc data alone and drag the file or folder into the terminal when it asks:

? Drag a file or folder here, or paste its path:

Over SSH, where nothing can be dragged into the terminal, the CLI asks you to type the path, and Tab completes it. One Tab completes as much as the names have in common; a second Tab lists them:

? Type the path to a file or folder, or run tracebloc data . from inside it: ~/data/churn_202
  churn_2023.csv  churn_2024.csv

A name with spaces or brackets completes escaped, the way your shell reads it: ~/My\ Data/patients\ $2024$.csv. Paths with spaces, quotes or a trailing space work as your terminal pastes them. tracebloc data . takes the folder you are in. If you give the folder above your dataset, the CLI finds the dataset inside it:

? Drag a file or folder here, or paste its path: '/Users/lukas/xrays'
  ✔ The dataset is inside it, in “chest x-rays”

If nothing is at the path, the CLI offers the nearest path that exists. Press Enter to take it. If the CLI can’t tell which task the files are laid out for, it names what it found and waits for you to fix the files. See Dataset layout for what each task needs.

Answer the questions

The column to predict. For a table, the CLI lists each column with a few of its values and asks which one the model should predict. Columns that can’t be predicted, such as an ID column that holds a different value in every row, are listed with the reason and can’t be picked:

  Which column should the model predict?
    1) churn             no, yes
    2) gender            male, female
    3) contract          month-to-month, two-year, one-year
    4) payment_method    paypal, invoice, direct debit, …  4 values
    5) support_calls     0 – 6
    6) age               numbers 19 – 78
    7) tenure_months     numbers 1 – 72
    8) monthly_charges   numbers 19.40 – 118.88
    9) total_charges     numbers 40.22 – 8,456.96
       customer_id       different in every row, so it can't be predicted
? Column: [1]
  ✔ Tabular classification · predicts churn

Type the column’s number or its name, or press Enter for the one in brackets. In a wide table the CLI lists the likely columns first; type part of a name to list the others. The task. The CLI works the task out from the files and the column you picked. When two tasks fit, it asks which one you mean, with no guess:

The data	The question
A 0/1 column next to a duration column	What should the model predict? How long until the event happens (time-to-event prediction), or whether it happens (tabular classification)
A column of a few whole numbers, such as ratings	Predict a class or a number? Each value is its own class (tabular classification), or 5 is more than 4 (tabular regression)
A number column, with rows in time order	What should the model do with it? Forecast its next values (time-series forecasting), or predict it from the other columns in each row (tabular regression)
Text pairs with no labels	What should the model learn from each pair? To continue the text (causal language modeling), or to turn the first part into the second (sequence-to-sequence)

For a folder of images or texts, the layout settles the task and the CLI asks no question. What the dataset holds. The CLI asks whether the data is about real patients. Press Enter for patient data, or choose open or synthetic data:

  What does this dataset hold?
    1) Patient data     about real patients
    2) Open data        published for anyone to use
    3) Synthetic data   generated, with no patient behind it
? Holds: [1]

The summary shows your answer on its holds line. Pass --holds to answer it up front, and the CLI doesn’t ask. Columns to leave out. A column whose values look like IDs, names, email addresses or phone numbers could leave your secure environment with the dataset’s statistics. The CLI warns about it and offers to leave it out:

  ⚠ email looks like email addresses, and its values could leave your secure environment.
    Fix: Leave it out of the dataset; your file stays as it is.
? Leave email out of the dataset? [Y/n]

Enter leaves the column out: it isn’t copied, and your file isn’t changed. Answer n to keep it. The summary lists what you left out. The name. The dataset takes its name from the file or folder, for example churn_train for churn_train.csv. The CLI asks for a name only when the one it found is taken. One name in your account always means the same columns, and datasets of one name train together in a use case:

If a dataset of that name with the same columns is on another of your secure environments, the CLI says so and Enter keeps the name.
If it has other columns, that’s a blocker, and Enter takes the next free name:

  ✖ churn_train on lukas-server has other columns (7, not 10).
    One name in your account always means the same columns.
    Fix: Pick another name, or press Enter for churn_train_2.
? Name for this one: [churn_train_2]

Read the summary

Before anything is copied, the CLI shows what it will ingest, where, and what leaves your secure environment:

  Summary
    name:                churn_train
    task:                Tabular classification
    column to predict:   churn
    data:                /Users/lukas/data/churn_train.csv · 200 rows · 10 columns
    holds:               Patient data
    secure environment:  lukas-macbook

  Leaves your secure environment: the column names, the row count and the
  class counts. No row.

    1) Training data      models learn from it
    2) Test data          models are scored on it; its row labels stay here
    3) Change something
? Ingest it as:

What leaves depends on the task. No row ever does:

The data	What leaves your secure environment
A table with a class to predict	The column names, the row count and the class counts
A table with a number to predict	The column names, the row count and the target’s count, sum, min and max
Images or texts with classes	The record count and the class counts
Texts with no labels	The record count

Ingest it as has no default. Choose 1 for Training data, the data models learn from, or 2 for Test data, the data models are scored on. Your answer starts the copy. If you pass --intent train or --intent test, the CLI doesn’t ask: the summary offers Ingest it as training data (or test data) and Change something, and asks Go ahead?. A use case needs both; see Pair test data with training data.

Change something

Choose 3 to change an answer before you ingest:

    1) The column to predict    churn
    2) The task                 Tabular classification
    3) The name                 churn_train
    4) The secure environment   lukas-macbook
    5) The data                 /Users/lukas/data/churn_train.csv
    6) What it holds            Patient data
? Change what?

Each change goes back to the checks and then to the summary, never to the start. A new column to predict can change the task. The task offers only the tasks that fit the column, and says so when only one does. The secure environment lists the secure environments this machine reaches. The data asks for a new path, then asks the questions for the new data. What it holds asks again, and Enter keeps your answer.

The run

Once you choose Training data or Test data, the CLI copies the data and follows it to the end, one tick per step:

  ✔ Copied into lukas-macbook · 1 file · 439 B
  ✔ Checked again in your secure environment
  ✔ Stored · 20 records
  ✔ Listed on tracebloc

  Ingested into lukas-macbook
    patients  Training data · 20 records

The other half. If the file or folder next to this one looks like the other half, for example churn_test.csv next to churn_train.csv, the CLI offers to ingest it now, as the other kind of data, with the same column and task. It takes its name from the first one: churn_w3_train makes the other half churn_w3_test.

  A use case also needs test data for this task.
  The file next to this one looks like the other half:
    ~/data/churn_test.csv
? Ingest churn_test as test data now? [y/N]

Answer y to ingest it. Enter or n ends the ingest, and What’s next? names the command for the other half. Test data that already pairs with training data on tracebloc isn’t offered the training half. A folder that holds both a training and a test table asks which to ingest: both, or only one of them. For both, the summary asks Go ahead?, with Ingest it as training data or Change something, and the test table follows with the same column and task. Stopping. Press Ctrl-C at any question and nothing is ingested. Press it during the copy and the CLI removes the partial copy: “Stopped. Nothing was ingested, and the partial copy was removed.” Once the copy is done and the run is submitted, the ingest goes on in your secure environment and the window can close. The dataset shows up in tracebloc data list when it’s done.

Choose the secure environment

The CLI ingests into your active secure environment, and the summary always names it. To ingest into another one this machine reaches, choose Change something › The secure environment, or pass its name:

tracebloc data ingest ~/data/patients.csv --secure-environment lukas-server

If the secure environment doesn’t answer, the CLI says so and asks whether to try again:

  ✗ Can't reach your secure environment lukas-macbook (connection refused).
    Make sure the machine it runs on is on and awake, then try again.
? Try again? [Y/n]

A scripted run doesn’t retry: it exits 4 and ingests nothing. If you name a secure environment this machine doesn’t reach, the CLI lists the ones it does reach. --secure-environment finds the cluster and namespace for you: it can’t be combined with -n, and a --context that points at another cluster stops the ingest. If the copy finds no room in your secure environment’s storage, nothing is copied and the run exits 7. Make room on the machine, for example with tracebloc data delete <name>, then ingest again.

Pair test data with training data

A use case trains on training data and scores models on test data for the same task. When you ingest test data, the CLI looks for training data on the same secure environment that it pairs with: the same columns, and no class the training data lacks.

? Ingest it as: 2
  ✔ Pairs with churn_train on lukas-macbook: the same 10 columns, and its classes ("no", "yes") are all in the training data

If nothing pairs with it yet, that’s a warning, and the default is No:

  ⚠ No training data on lukas-macbook pairs with this yet.
    churn_train has the classes "no" and "yes"; this one also has "maybe".
    A use case refuses test data with a class its training data lacks.
? Ingest it anyway? [y/N]

A use case refuses test data with a class its training data lacks, or with a column whose type differs from the training data’s. Fix the test data, or ingest it anyway if the training data comes later.

Checks before the copy

The CLI reads your files on your machine and runs the checks before anything is copied: the layout, the values, and what training needs. It prints each problem with what to do about it:

Blocker (✖): the ingest can’t go on. In a guided run the CLI waits: “Fix the files, then press Enter to check again.” A scripted run exits 3.
Warning (⚠): the ingest can go on, and you decide. A guided run asks, and its default is the safe answer. A scripted run prints the warning and goes on.

Your secure environment’s data ingestor checks the data again after the copy. Nothing is stored unless every check passes.

What the CLI says	What it means, and the fix
`tracebloc can't tell what this is`	The files aren’t laid out the way any task needs. Lay them out as the dataset template for your task shows.
`Column names can't contain "%(" or "%s"`	The database refuses those characters in a column name. Rename the column.
`Column names must differ by more than letter case`	The database can’t tell `Region` from `region`. Rename one of them.
`<column> holds true or false, but line 5 says “maybe”` (or dates, or a declared length)	A value doesn’t fit its column’s type. Correct the value or leave it empty. For a text column that’s too short, declare it longer with `--schema`.
`Too few rows to train on`	Training keeps 15% of the rows aside to check itself, so it needs at least 10. Add rows.
`Few rows in a class` (warning)	A class with fewer than 10 rows is learned poorly. Add rows to it.
`<column> is spelled two ways` (warning)	`Yes` and `yes` become two classes. If they’re one class, spell it one way.
`--label-column <column>: different in every row`	An ID-like column can’t be predicted. Pick the column the model should predict.
`has no column called timestamp, which time-series data orders its rows by; date looks like it`	Rename your time column to `timestamp`.
`The rows aren't in time order`	Sort the file by its time column, oldest first.
`is the time until the event, but it is 0 or below`	Time-to-event data needs a time above 0 in every row. Fix or remove those rows.
`has 7 words but 6 tags`	Token classification needs exactly one tag for each word.
`is listed twice`	A file appears on two lines of `labels.csv` with different labels. Keep one line for each file.
`runs ingestor <version>, which reads this layout differently`	Your secure environment’s data ingestor is older than this CLI expects. Update it, then ingest again.
`This CLI is too old for tracebloc`	Run `tracebloc upgrade`, then ingest again.
`<column> uses decimal commas` (a note)	A CSV saved with semicolons and decimal commas, as Excel does in much of Europe, ingests as it is. The copy writes the commas as dots, and your file stays as it is.
`holds numbers whose comma could be a decimal point or a thousands separator`	The CLI can’t tell `52,034` from fifty-two thousand. Write numbers with a decimal point (`1.234`) or with no thousands separator (`1234`).
`is Windows-1252 (Latin-1) text, converted to UTF-8 in the copy` (a note)	A Latin-1 or Windows-1252 CSV ingests as it is. The copy holds it as UTF-8, and your file stays as it is.
`isn't UTF-8, and line 4 holds bytes that aren't Windows-1252 either`	The file is in an encoding the CLI can’t convert safely. In Excel, save it as CSV UTF-8 in its place, then run it again.
`mixes UTF-8 with another encoding from line 4`	Part of the file is UTF-8 and part isn’t, so no conversion is safe. Retype the accented characters from that line on, save the file as UTF-8, then run it again.
`is converted to CSV in the copy` (a note)	An Excel workbook (`.xlsx` or `.xlsm`) ingests as it is. The copy holds its sheet as CSV, and your workbook stays as it is.
`has 2 sheets, Kunden and Notizen, and a dataset is one table`	Name the sheet to ingest with `--sheet`, for example `--sheet Kunden`. Only the sheets Excel shows count.
`is a formula Excel never calculated`	The cell holds no value to copy. Open the workbook in Excel, save it, then run it again.
`is protected with a password`	In Excel, remove the password (File › Info › Protect Workbook), save it, then run it again.
`can't be read as an Excel workbook: it may be damaged`	In Excel, choose File › Save As › CSV UTF-8, then pass the `.csv` file.
`is an Excel workbook, and tracebloc reads CSV`	An old `.xls` workbook. In Excel, choose File › Save As › CSV UTF-8, then pass the `.csv` file.
`is unpacked into the copy; your file stays as it is` (a note)	A zip archive ingests as it is. The copy holds what it unpacks, without the extra files macOS adds, and your zip stays as it is.
`.zip is protected with a password, so tracebloc can't read it`	Unzip it yourself, then pass the folder. The CLI prints both commands.
`whose path leaves the archive, so tracebloc won't unpack it`	A file in the zip would land outside the dataset’s folder. Zip the dataset’s folder again, then pass the new zip or the folder.
`can't be read as a zip archive: it may be damaged`	Unzip it yourself, then pass the folder. The CLI prints both commands.
`images are smaller than 32x32, the smallest this ingest takes`	Use images at least 32x32 pixels.
`images are WebP`	The data ingestor doesn’t read WebP. Save the images as PNG or JPEG, and change their names in `labels.csv` to match.
`YOLO labels for 12 images are converted to Pascal VOC in the copy` (a note)	A YOLO export ingests as object detection. The copy holds its labels as Pascal VOC, named from `data.yaml`, and your files stay as they are.
`This folder holds YOLO labels (labels/*.txt) but no class names, so its objects can't be named`	Add `classes.txt` beside `labels/`, one class name per line in the order of the class numbers, then run it again.
`Line 2 of labels/val/site_11.txt has 7 values, and a YOLO object line has 5`	Write each object as a class number and four numbers from 0 to 1 (centre x, centre y, width, height), then run it again.
`files are in iCloud or OneDrive and not downloaded to this Mac`	In Finder, right-click the folder and choose Download Now, then run it again.
`macOS didn't let this terminal read`	In System Settings › Privacy & Security › Files and Folders, turn on the folder for your terminal app, then run it again.
`images sit directly in <folder>, beside the class folders`	In a folder of class folders, every image belongs in the folder of its class. Move it there.
`The class folder <class> holds no .jpg, .jpeg or .png images`	Add its images, or move the folder out.

When a fix is a different command, the CLI prints that command in full, so you can copy it.

Scripted ingest

For a script or CI, pass --no-input. The CLI asks nothing: what the flags leave out, the files fill in. When they can’t, the run exits 2 and names the flag to add.

tracebloc data ingest ~/data/churn_train.csv \
  --label-column churn \
  --intent train \
  --no-input

The task and the name come from the files when you leave out --task and --name: ✔ Tabular classification · predicts churn · name churn_train, from the files. If the column fits two tasks, the run exits 2 and prints the command for each, with --task.
The column to predict is --label-column, for every table. If you mistype it, the run exits 2 and names the column it’s closest to.
A --task that contradicts the files wins, with a warning that prints the command with the task the files show.
Columns to leave out: --leave-out <column>, once per column. A column that looks like it could identify people is a warning, and the fix is the command with --leave-out. Naming a column the table doesn’t have stops the run.
Test data is --intent test.
What the dataset holds: --holds patient_data, open_data or synthetic_data. Without it, the dataset is marked as patient data. On a guided run, it answers the question up front. The mark decides which use case types you can create on the dataset, so pass --holds open_data or --holds synthetic_data when your data is not patient data.
Where it goes: --secure-environment <name>; see Choose the secure environment.
A dry run: --dry-run runs the checks and connects to your secure environment, and creates nothing. On a terminal, a dry run asks its questions one by one, in four numbered steps, instead of showing the summary.

A scripted run prints its progress in three phases: Check your data, Copy into your secure environment, and Validate and ingest.

Image resolution

Every image has to be exactly the same size. --target-size is that size, written WxH: the width, the letter x, then the height, for example 512x512. The ingest checks every image against it and rejects any that differ, so resize the odd ones out before you ingest. Without the flag, the CLI takes the most common size among your images. --min-size WxH rejects images smaller than that before the ingest; set it to the smallest size your model can train on. Images smaller than 32x32 always stop the run before the copy.

  Auto-detected image target size 512x512, the size 940 of 1000 images share (override with --target-size).

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 tracebloc data.

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 <path> 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

An Excel workbook (.xlsx or .xlsm) works too, as a file or as the only file in a folder: the copy holds its sheet as CSV. A workbook with more than one visible sheet needs --sheet. Time-series forecasting orders the rows by a column named timestamp. 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
    └── ...

For image classification, images sorted into one folder per class work too, with no labels.csv. Each image’s label is its folder’s name, and the CLI writes labels.csv in the copy. Your folders stay as they are:

xrays/
├── normal/
│   ├── 001.png
│   └── ...
└── pneumonia/
    ├── 002.png
    └── ...

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. WebP images stop the run before the copy. A YOLO export (labels/*.txt) is converted to Pascal VOC in the copy. Files whose names start with a dot, such as the ._ files macOS leaves beside copied images, are skipped.

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). Leave it out and the CLI works it out from the files.
`--name`	A name for the dataset — starts with a letter or underscore, then letters, digits, or underscores. Leave it out and the CLI takes it from the file or folder. You pick the dataset by this name when you create a use case.
`--intent`	`train` (default) or `test`. A guided run without it asks Ingest it as; with it, the summary asks only Go ahead?. Any other value exits `2` before any question.
`--label-column`	The column the model should predict: in `labels.csv` for image and text tasks, in the data CSV for tabular. Required in a scripted run for every task that has one: tabular, time series, `image_classification`, `keypoint_detection`, `semantic_segmentation`, `text_classification`, `token_classification`, and `sentence_pair_classification`. Left out for images sorted into class folders, whose label is the folder’s name. Refused for `object_detection` and the self-supervised text tasks (`masked_language_modeling`, `causal_language_modeling`, `seq2seq`, `embeddings`).
`--leave-out`	Tabular and time series only: a column to leave out of the dataset. It isn’t copied, and your file stays as it is. Repeat it for more columns.
`--holds`	What the dataset holds: `patient_data`, `open_data` or `synthetic_data`. Leave it out on a terminal and the CLI asks; a scripted run without it marks the dataset as patient data. The mark decides which use case types you can create on the dataset.
`--secure-environment`	The secure environment to ingest into, by name. Default: your active one.
`--dry-run`	Run the checks and connect to your secure environment, without creating anything.
`--no-input`	Never ask; fail on a missing value (for CI and scripts).
`--overwrite`	Replace a dataset of the same name. With a data ingestor v0.9.0 or newer, the current dataset stays until the new data has passed every check; with an older one, its data is deleted first (same as `data delete`).
`--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 following it.
`--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 — only the target’s count, sum, min and max leave your secure environment) or `passthrough`.
`--time-column`	`time_to_event_prediction` only: the time/duration column (default: a column named `time`).
`--sheet`	Excel workbooks only: the sheet to ingest. Needed when a workbook has more than one visible sheet.
`--target-size`	Image tasks only: see Image resolution. Default: the most common size among your images.
`--min-size`	Image tasks only: reject images smaller than `WxH` before ingesting. Default: 32x32; smaller images stop the run before the copy.
`--number-of-keypoints`	`keypoint_detection` only: keypoints per sample, e.g. `17` for COCO pose. Required in a scripted run.

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`	A flag is missing or wrong (the message names it), the dataset settings don’t fit the ingest schema, or the task isn’t one the CLI knows
`3`	A blocker in the checks before the copy, or a local layout or kubeconfig problem
`4`	The secure environment can’t be reached, wasn’t 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 was cut off, or there was no room for them (or, with `--overwrite`, deleting the old dataset failed)
`8`	Your secure environment rejected the ingestion run, or didn’t answer when it was submitted
`9`	The ingestion run failed, or finished with row-level failures shown in its summary
`11`	The run hadn’t started within 5 minutes, or was still running after an hour: the CLI stopped following it, and it goes on in your secure environment

What’s next

When the training data and the test data are both in, the CLI names the next step:

  What's next?
  1) Create the use case, and pick the datasets by name:
       https://ai.tracebloc.io/use-cases?create=1

Create the use case on tracebloc and pick each dataset by the name you gave it. Your datasets are listed under My Data on the Secure Environment page, and in your terminal with tracebloc data list.

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). Right after the delete, the CLI asks your secure environment to report its datasets to tracebloc, and My Data shows the dataset as Deleted within a few minutes. If that report can’t be made (for example, tracebloc is unreachable), the CLI says so and still exits 0: your secure environment’s next scheduled report, about hourly while it runs, marks the dataset Deleted. The dataset’s catalog entry on tracebloc is kept as a record, so experiments that used it keep their history. tracebloc data rm is an alias. Both commands accept --output-json; for data delete, platform_notified says whether tracebloc was told.

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 <path>`	Ingest a local dataset: guided on a terminal, or scripted with `--no-input`. `tracebloc data <path>` is the same command
`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 outbound [day]`	Show the outbound record: every message the outbound gate in your secure environment checked on one day (UTC), with its time, what it is, its size and what happened to it. With no day, the newest day the record holds; give a day as `YYYY-MM-DD` for another. The record stays in your secure environment and keeps the last 90 days, or less once it reaches 1 GiB
`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. With a secure environment linked to this machine, needs you signed in. With none linked (signed out, or none created here), needs no sign-in: it removes `~/.tracebloc`, the CLI and its PATH entry, and you type `tracebloc` to confirm; it refuses while the install record still lists a secure environment, and names the sign-in and relink. See With no secure environment linked and Delete it by hand (`--keep-data` keeps `~/.tracebloc`; `--yes` skips the typed-name prompt and `--confirm-name <name>` confirms without a terminal; `--force` deletes even while a training runs on it — without `--force` it refuses and names the experiments training there, and only warns about an experiment listed as running that has nothing training on this machine; `--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

Give the path

Answer the questions

Read the summary

Change something

The run

Choose the secure environment

Pair test data with training data

Checks before the copy

Scripted ingest

Image resolution

Tasks

Dataset layout

Key flags

Exit codes

What’s next

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

Give the path

Answer the questions

Read the summary

Change something

The run

Choose the secure environment

Pair test data with training data

Checks before the copy

Scripted ingest

Image resolution

Tasks

Dataset layout

Key flags

Exit codes

What’s next

List and delete datasets

Validate a config locally

Command reference

CLI or Helm chart?