Import files with the Sift CLI

After completing this workflow, you can import CSV, Parquet, TDMS, HDF5, ULog, MCAP, 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.
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.
For every command, flag, and supported value, see the Sift 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>.

The CSV importer accepts --run only.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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:

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 an MCAP file

Import an MCAP file into an Asset. See import mcap for supported topics and current limitations.

sift-cli import mcap ./recording.mcap --asset rover --wait

MCAP logs on a non-Unix epoch need an explicit start time. Pass --relative-start-time (-s) as an RFC 3339 timestamp:

sift-cli import mcap ./recording.mcap --asset rover --relative-start-time 2026-07-02T15:04:05Z

To import named metadata records as Run metadata, pass --metadata-record for each one. This requires --run or --run-id:

sift-cli import mcap ./recording.mcap \
  --asset rover \
  --run flight-01 \
  --metadata-record device_info

If a topic or record can’t be decoded, the import fails by default. Pass --parse-error-policy ignore-error to import what decoded and skip the rest:

sift-cli import mcap ./recording.mcap --asset rover --run flight-01 --parse-error-policy ignore-error --wait

Use --complex-types-import-mode to control how variable-cardinality fields import. See import mcap for the available modes.

Import backup files

Import backup files generated by sift_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.

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:

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

Get started

Ingest telemetry

Investigate

Detect and review

Transform

Export

Sift CLI

Integrate

Manage workspace

Reference

Import files with the Sift CLI

Before you begin

Import commands

Import a CSV file

Import a Parquet file

Flat dataset

Channel per row

Import a TDMS file

Import an HDF5 file

Import a ULog file

Import an MCAP file

Import backup files

Time formats

​Before you begin

​Import commands

​Import a CSV file

​Import a Parquet file

​Flat dataset

​Channel per row

​Import a TDMS file

​Import an HDF5 file

​Import a ULog file

​Import an MCAP file

​Import backup files

​Time formats

Before you begin

Import commands

Import a CSV file

Import a Parquet file

Flat dataset

Channel per row

Import a TDMS file

Import an HDF5 file

Import a ULog file

Import an MCAP file

Import backup files

Time formats