> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import files with the Sift CLI

> Import CSV, Parquet, TDMS, HDF5, ULog, and backup files into Sift from the command line.

The Sift CLI imports telemetry files into an Asset. Use it for command-line imports and scripted ingestion without writing code against the API.

## Before you begin

* Install and configure the CLI. See [Sift CLI setup](/documentation/cli/sift-cli).
* Identify the Asset that owns the data. When you import, you can name an existing Asset or a new one.
* Confirm your file has a time column in a [supported time format](#time-formats).
* For every command, flag, and supported value, see the [Sift CLI reference](/documentation/reference/cli-reference).

## Import commands overview

Every import command imports into an Asset named by `--asset`.

To associate the data with a Run, or to create or reuse a Run by name, pass `--run <name>`.

To append to an existing Run, use `--run-id <id>`.

<Note>
  The CSV importer accepts `--run` only.
</Note>

Two flags apply to all import commands:

* `--preview` parses the file and prints the detected schema without uploading.
* `--wait` blocks until Sift finishes processing the import.

## Import a CSV file

Import a CSV file into an Asset. Unless you specify column types, the CLI infers each column as either string or double.

```bash theme={null}
sift-cli import csv ./data.csv --asset my-asset --wait
```

To override specific columns, pass `--channel-column` with the 1-based column index. Supply a `--data-type`, `--unit`, and `--description` for each `--channel-column`. The counts must match. Units and descriptions can be empty strings.

```bash theme={null}
sift-cli import csv ./data.csv \
  --asset my-asset \
  --channel-column 2 --data-type double --unit volts --description "" \
  --channel-column 3 --data-type bool --unit "" --description ""
```

CSV import defaults the header row to row 1, the first data row to row 2, and the time column to column 1. Override these with `--header-row`, `--first-data-row`, and `--time-column`. Set the time format with `--time-format`.

## Import a Parquet file

Parquet import has two layouts. Choose the subcommand that matches your file.

### Flat dataset

Use `flat-dataset` when every column holds one Channel, except for the time column. By default, the CLI imports every non-time column.

```bash theme={null}
sift-cli import parquet flat-dataset ./data.parquet --asset my-asset
```

To import a subset of columns, pass `--channel-path` for each Channel. Supply a `--data-type`, `--unit`, and `--description` for each `--channel-path`. The counts must match. Units and descriptions can be empty strings.

```bash theme={null}
sift-cli import parquet flat-dataset ./data.parquet \
  --asset my-asset \
  --channel-path voltage --data-type double --unit volts --description "" \
  --channel-path current --data-type double --unit amps --description ""
```

The CLI auto-detects the time column from the common names `time`, `timestamp`, `timestamps`, and `ts`. Set `--time-path` to name it explicitly. The CLI infers the time format from the column's Arrow type unless you set `--time-format`.

### Channel per row

Use `cpr` when the file is laid out one Channel value per row. The `--mode` flag selects the layout:

* `single`: the file holds `[time, value]` and every row belongs to one Channel. Name it with `--channel-name`.
* `multi`: the file holds a name column and a value column. Set `--name-path` to the column holding Channel names. The CLI creates a Channel per unique name.

```bash theme={null}
sift-cli import parquet cpr ./data.parquet \
  --asset my-asset \
  --mode multi \
  --data-path value \
  --name-path channel
```

Both Parquet layouts handle complex columns (maps, lists, structs) through `--complex-types-mode`, which defaults to `ignore`.

## Import a TDMS file

Import a TDMS file into an Asset.

```bash theme={null}
sift-cli import tdms ./data.tdms --asset my-asset
```

For Channels with missing timing information, `--fallback-method` controls behavior and defaults to `fail-on-error`. Set it to `ignore-error` to skip those Channels. To import TDMS file properties to the Run as metadata, pass `--import-file-properties`.

## Import an HDF5 file

Import an HDF5 file into an Asset. Two flags are required: `--schema`, which names the file's layout (`one-d`, `two-d`, or `compound`), and `--time-format`. Add `--relative-start-time` (`-s`) when the time format is relative.

```bash theme={null}
sift-cli import hdf5 ./data.h5 --asset my-asset --schema one-d --time-format absolute-unix-seconds
```

HDF5 import supports these Channel types across all schemas: `bool`, `int8/16/32/64`, `uint8/16/32/64`, `float32`, and `float64`. Datasets with other types produce a client-side error.

The time-column flag depends on the schema:

* `--time-name` (one-d): the leaf name of the time dataset when it differs from the auto-detected names `time`, `timestamp`, `timestamps`, or `ts`.
* `--time-index` (two-d): the index of the time column. Defaults to 0.
* `--time-field` (compound): the name of the time field.

## Import a ULog file

Import a PX4 ULog file into an Asset. ULog files are self-describing, so the CLI imports every logged topic by default, naming each Channel `<message>_<multi_id>.<field>` (for example `sensor_accel_0.x`). Logged status text becomes `log_messages` Channels.

```bash theme={null}
sift-cli import ulog ./flight.ulg --asset my-asset --wait
```

ULog timestamps are relative to boot time. Sift anchors the timeline using the log's GPS time fix, unless you provide an explicit start time with `--relative-start-time` (`-s`), which takes precedence:

```bash theme={null}
sift-cli import ulog ./flight.ulg --asset my-asset --relative-start-time 2026-07-02T15:04:05Z
```

To import ULog info messages or parameter values as Run metadata, pass `--info-key` or `--param-key` for each one. Both require `--run` or `--run-id`:

```bash theme={null}
sift-cli import ulog ./flight.ulg \
  --asset my-asset \
  --run "test flight 2026-07-02" \
  --info-key sys_name \
  --param-key MC_PITCH_P
```

If the file ends with a truncated record or contains corrupt segments, the import fails by default. Pass `--parse-error-policy ignore-error` to import the records that parsed and skip the rest.

## Import backup files

Import backup files generated by [sift\_stream](/documentation/reference/asset-settings#stream), part of the `sift_app` built-in system Asset. If ingestion fails, `sift_stream` writes the in-flight data to a local backup. `sift-cli import backups` will replay them and import anything that did not make it into Sift.

```bash theme={null}
sift-cli import backups --path ./backups
```

If you omit `--path`, the CLI reads from your OS data directory. Pass `--cleanup` to delete the backup files after a successful upload.

To list backup files without importing them:

```bash theme={null}
sift-cli import backups ls ./backups
```

## Time formats

The `--time-format` flag accepts absolute and relative values. For the full list, see the [Sift CLI reference](/documentation/reference/cli-reference#time-formats).

For a relative format, set the relative start time (`-s`, or `--relative-start-time` on Parquet, TDMS, and HDF5) to an RFC 3339 timestamp that anchors the offsets.