> ## Documentation Index > Fetch the complete documentation index at: https://tracevell.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Tracevell datasets CLI The `lmnr-cli dataset` command manages datasets in Tracevell from your terminal: list and inspect them, create new ones from local files, push or pull datapoints, rename a dataset, and delete one. It ships in the standalone [`lmnr-cli`](https://tracevell.com/docs/platform/cli) npm package, so you do not need the `@lmnr-ai/lmnr` SDK installed to use it. > [!NOTE] > > `lmnr-cli` replaces the dataset commands that used to ship with the `@lmnr-ai/lmnr` SDK (`lmnr datasets ...`). The old SDK-bundled CLI is deprecated; use `lmnr-cli dataset` instead. ## Install ```bash theme={null} # Run directly with npx (no install) npx lmnr-cli@latest dataset list # Or install globally npm install -g lmnr-cli ``` The rest of this page assumes a global install (`lmnr-cli dataset ...`). With `npx`, prefix each command with `npx lmnr-cli@latest`. ## Usage ### Creating a new dataset and iterating on it **1. Prepare input files** Prepare input files for the dataset. Supported formats are: `.json`, `.jsonl`, `.csv`. Every datapoint must at least have a `data` field. Save this file as `data.json` (or `data.jsonl` or `data.csv`). For JSON, the file must contain **one array** of datapoints. For JSONL, the file must contain **one datapoint per line**. For CSV, the file must contain **a header row and one datapoint per row**. Examples: **JSON** ```json theme={null} [ { "data": { "color": "red", "size": "large" } }, { "data": { "color": "blue", "size": "small" } }, ] ``` **JSONL** ```jsonl theme={null} {"data": {"color": "red", "size": "large"}} {"data": {"color": "blue", "size": "small"}} ``` **CSV** ```csv theme={null} data,target "{""color"": ""red"", ""size"": ""large""}","{""expected_output"": ""red""}" "{""color"": ""blue"", ""size"": ""small""}","{""expected_output"": ""blue""}" ``` **2. Authenticate and link your project** The CLI authenticates as you, the signed-in user. Run `lmnr-cli setup` once in your project: it logs you in (opens a browser to authorize the CLI) and links the current directory to a project by writing `.lmnr/project.json`. Every dataset command then runs against that linked project. ```bash theme={null} lmnr-cli setup ``` Alternatively, target a project explicitly with `--project-id` on any command: ```bash theme={null} lmnr-cli dataset --project-id list ``` > [!NOTE] > > Unlike the old SDK-bundled CLI, `lmnr-cli` does not use a project API key. See [Authenticate](https://tracevell.com/docs/platform/cli.md#authenticate) and [Directory-scoped projects](https://tracevell.com/docs/platform/cli.md#directory-scoped-projects) for details. **3. Create a new dataset** Create a new dataset from the input file. This command will create a new dataset with the name `my-cli-dataset` and save the datapoints to the file `my-cli-dataset.json`. The datapoints are saved to a new file in order to: * Store datasets in the Tracevell format. In particular, datapoint id is crucial for versioning ([Learn more](https://tracevell.com/docs/datasets/introduction.md#versioning)). * Not overwrite existing files. ```bash theme={null} lmnr-cli dataset create my-cli-dataset data.json -o my-cli-dataset.json ``` **4. Work on the dataset locally** Make any changes required to the dataset by editing the file `my-cli-dataset.json`. Make sure to not edit the `id` field of the datapoints. > [!NOTE] > > If you delete a datapoint, this will not affect the dataset in Tracevell. > This is because the push operation only pushes new datapoint (versions) to the dataset. **5. Push the changes to Tracevell** Push the changes to Tracevell. ```bash theme={null} lmnr-cli dataset push my-cli-dataset.json -n my-cli-dataset ``` This will push the changes to the dataset in Tracevell. **6. Pull the changes from Tracevell** If you need to update the local dataset with the latest changes from Tracevell, you can pull the changes. ```bash theme={null} lmnr-cli dataset pull my-cli-dataset.json -n my-cli-dataset ``` This will pull the changes from the dataset in Tracevell to the local file `my-cli-dataset.json`. > [!WARNING] > > This will overwrite the contents of the current file `my-cli-dataset.json`. ### Working on an existing dataset **1. Authenticate and link your project** Run `lmnr-cli setup` once to log in and link the current directory to your project (see [above](#creating-a-new-dataset-and-iterating-on-it)): ```bash theme={null} lmnr-cli setup ``` **2. Select the dataset to work on** List all datasets and select the one you want to work on. ```bash theme={null} lmnr-cli dataset list ``` **3. Pull the data from Tracevell** Pull the data from Tracevell to a local file. ```bash theme={null} lmnr-cli dataset pull my-dataset.json -n my-dataset ``` This will pull the changes from the dataset in Tracevell to the local file `my-dataset.json`. > [!WARNING] > > If `my-dataset.json` already exists, this will overwrite the contents of the file. **4. Work on the dataset locally** Make any changes required to the dataset by editing the file `my-dataset.json`. Make sure to not edit the `id` field of the datapoints. > [!NOTE] > > If you delete a datapoint, this will not affect the dataset in Tracevell. > This is because the push operation only pushes new datapoint (versions) to the dataset. **5. Push the changes to Tracevell** Push the changes to Tracevell. ```bash theme={null} lmnr-cli dataset push my-dataset.json -n my-dataset ``` This will push the changes to the dataset in Tracevell. ### Setting the CLI to call a local Tracevell instance The `dataset` command has optional arguments for pointing at a self-hosted instance: * `--base-url`: The base URL of the Tracevell instance. Do NOT include port here. Default is `https://api.lmnr.ai` (or the `LMNR_BASE_URL` env variable). * `--port`: The HTTP port of the Tracevell instance. Default is 443 (or the `LMNR_HTTP_PORT` env variable). For local self-hosted Tracevell, use 8000. * `--project-id`: The id of the project to target. If not provided, resolves from the nearest `.lmnr/project.json`. ```bash theme={null} lmnr-cli dataset --base-url http://localhost --port 8000 list ``` See [Self-hosting](https://tracevell.com/docs/platform/cli.md#self-hosting) for the full self-hosted setup. ## Reference ```bash theme={null} lmnr-cli dataset [command] ``` ## General options These are shared by every `dataset` subcommand. ``` --project-id Target project id. Defaults to the linked .lmnr/project.json --base-url Base URL for the Tracevell API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable --port Port for the Tracevell API. Defaults to 443 or LMNR_HTTP_PORT env variable --json Output structured JSON to stdout ``` ## Commands Dataset names are display labels and do not need to be unique. Use the dataset ID returned by `list` when you need to target one dataset unambiguously. ### List all datasets List all datasets. ```bash theme={null} lmnr-cli dataset list ``` ``` ID Created At Name 2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a 2026-09-15 10:03:26 qa-eval Total: 1 dataset(s) ``` ### Get a dataset Get dataset metadata by its canonical ID. Useful for confirming an id resolves in this project before scripting a push or a delete against it. ```bash theme={null} lmnr-cli dataset get ``` ```bash theme={null} lmnr-cli dataset get 2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a --json ``` ```json theme={null} { "id": "2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a", "name": "qa-eval", "projectId": "85602090-0a3b-415a-b616-e9cd788e6a64", "createdAt": "2026-09-15T10:03:26.545138Z" } ``` ### Rename a dataset `update` takes the dataset id and a new name in `-n` / `--name`. Renaming keeps every datapoint and its version history: only the display name changes, so anything referencing the dataset **by id** keeps working while pushes and pulls that pass `-n ` stop resolving. ```bash theme={null} lmnr-cli dataset update 2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a -n qa-eval-v2 ``` ``` Updated dataset "qa-eval-v2" (2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a). ``` ### Delete a dataset Delete a dataset and its datapoints. ```bash theme={null} lmnr-cli dataset delete 2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a ``` ``` Deleted dataset "qa-eval-v2" (2b5f01c6-5a10-4abd-b8c7-05f9d7be3b9a) and its datapoints. ``` > [!WARNING] > > Deleting a dataset is permanent and removes every datapoint in it, including all datapoint versions. There is no confirmation prompt. Pull a copy first (`dataset pull`) if you may want the data back. ### Create a new dataset Create a dataset from input files. ```bash theme={null} lmnr-cli dataset create [options] ``` ``` Arguments: name Name of the dataset to create paths Paths to files or directories containing data to push Options: -o, --output-file Path to save the pulled data (required) --output-format Output format (json, csv, jsonl). Inferred from file extension if not provided -r, --recursive Recursively read files in directories (default: false) --batch-size Batch size for pushing/pulling data (default: 100) ``` ### Push datapoints to a dataset Push datapoints to an existing dataset from a file or files. ```bash theme={null} lmnr-cli dataset push [options] ``` ``` Arguments: paths Paths to files or directories containing data to push Options: -n, --name Name of the dataset (either name or id must be provided) --id ID of the dataset (either name or id must be provided) -r, --recursive Recursively read files in directories (default: false) --batch-size Batch size for pushing data (default: 100) ``` ### Pull datapoints from a dataset Pull datapoints from a dataset to a file or print them to the console. ```bash theme={null} lmnr-cli dataset pull [options] [output-path] ``` ``` Arguments: output-path Path to save the data. If not provided, prints to console Options: -n, --name Name of the dataset (either name or id must be provided) --id ID of the dataset (either name or id must be provided) --output-format Output format (json, csv, jsonl). Inferred from file extension if not provided --batch-size Batch size for pulling data (default: 100) --limit Limit number of datapoints to pull --offset Offset for pagination (default: 0) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.