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

After completing this workflow, you can import CSV, Parquet, TDMS, HDF5, ULog, or backup files into an Asset from the command line, 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

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.