> ## Documentation Index
> Fetch the complete documentation index at: https://laminarai-docs-lam-1786-dataset-cli-lmnr-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Laminar datasets CLI

The `lmnr-cli dataset` command manages datasets in Laminar from your terminal: list them, create new ones from local files, and push or pull datapoints. It ships in the standalone [`lmnr-cli`](/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.
</Note>

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

<Steps>
  <Step title="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:

    <Expandable title="JSON">
      ```json theme={null}
      [
          { "data": { "color": "red", "size": "large" } },
          { "data": { "color": "blue", "size": "small" } },
      ]
      ```
    </Expandable>

    <Expandable title="JSONL">
      ```jsonl theme={null}
      {"data": {"color": "red", "size": "large"}}
      {"data": {"color": "blue", "size": "small"}}
      ```
    </Expandable>

    <Expandable title="CSV">
      ```csv theme={null}
      data,target
      "{""color"": ""red"", ""size"": ""large""}","{""expected_output"": ""red""}"
      "{""color"": ""blue"", ""size"": ""small""}","{""expected_output"": ""blue""}"
      ```
    </Expandable>
  </Step>

  <Step title="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 <your-project-id> list
    ```

    <Note>
      Unlike the old SDK-bundled CLI, `lmnr-cli` does not use a project API key. See [Authenticate](/platform/cli#authenticate) and [Directory-scoped projects](/platform/cli#directory-scoped-projects) for details.
    </Note>
  </Step>

  <Step title="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 Laminar format. In particular, datapoint id is crucial for versioning ([Learn more](/datasets/introduction#versioning)).
    * Not overwrite existing files.

    ```bash theme={null}
    lmnr-cli dataset create my-cli-dataset data.json -o my-cli-dataset.json
    ```
  </Step>

  <Step title="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 Laminar.
      This is because the push operation only pushes new datapoint (versions) to the dataset.
    </Note>
  </Step>

  <Step title="Push the changes to Laminar">
    Push the changes to Laminar.

    ```bash theme={null}
    lmnr-cli dataset push my-cli-dataset.json -n my-cli-dataset
    ```

    This will push the changes to the dataset in Laminar.
  </Step>

  <Step title="Pull the changes from Laminar">
    If you need to update the local dataset with the latest changes from Laminar, 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 Laminar to the local file `my-cli-dataset.json`.

    <Warning>
      This will overwrite the contents of the current file `my-cli-dataset.json`.
    </Warning>
  </Step>
</Steps>

### Working on an existing dataset

<Steps>
  <Step title="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
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Pull the data from Laminar">
    Pull the data from Laminar 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 Laminar to the local file `my-dataset.json`.

    <Warning>
      If `my-dataset.json` already exists, this will overwrite the contents of the file.
    </Warning>
  </Step>

  <Step title="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 Laminar.
      This is because the push operation only pushes new datapoint (versions) to the dataset.
    </Note>
  </Step>

  <Step title="Push the changes to Laminar">
    Push the changes to Laminar.

    ```bash theme={null}
    lmnr-cli dataset push my-dataset.json -n my-dataset
    ```

    This will push the changes to the dataset in Laminar.
  </Step>
</Steps>

### Setting the CLI to call a local Laminar instance

The `dataset` command has optional arguments for pointing at a self-hosted instance:

* `--base-url`: The base URL of the Laminar 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 Laminar instance. Default is 443 (or the `LMNR_HTTP_PORT` env variable). For local self-hosted Laminar, 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](/platform/cli#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 <id>   Target project id. Defaults to the linked .lmnr/project.json
  --base-url <url>    Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable
  --port <port>       Port for the Laminar API. Defaults to 443 or LMNR_HTTP_PORT env variable
  --json              Output structured JSON to stdout
```

## Commands

### List all datasets

List all datasets.

```bash theme={null}
lmnr-cli dataset list
```

### Create a new dataset

Create a dataset from input files.

```bash theme={null}
lmnr-cli dataset create [options] <name> <paths...>
```

```
Arguments:
  name                      Name of the dataset to create
  paths                     Paths to files or directories containing data to push

Options:
  -o, --output-file <file>  Path to save the pulled data (required)
  --output-format <format>  Output format (json, csv, jsonl). Inferred from file extension if not provided
  -r, --recursive           Recursively read files in directories (default: false)
  --batch-size <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] <paths...>
```

```
Arguments:
  paths                Paths to files or directories containing data to push

Options:
  -n, --name <name>    Name of the dataset (either name or id must be provided)
  --id <id>            ID of the dataset (either name or id must be provided)
  -r, --recursive      Recursively read files in directories (default: false)
  --batch-size <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>         Name of the dataset (either name or id must be provided)
  --id <id>                 ID of the dataset (either name or id must be provided)
  --output-format <format>  Output format (json, csv, jsonl). Inferred from file extension if not provided
  --batch-size <size>       Batch size for pulling data (default: 100)
  --limit <limit>           Limit number of datapoints to pull
  --offset <offset>         Offset for pagination (default: 0)
```