Sift CLI reference

This page documents every command, subcommand, and flag in the Sift CLI. For installation and configuration, see Sift CLI.

Sift CLI how-tos

Global flags

These flags apply to any command.

Flag	Description
`--profile <name>`	The profile to use. Defaults to `default`.
`--disable-tls`	Disable TLS for non-cloud Sift environments.
`--version`	Print the CLI version.
`--help`	Print help for a command or subcommand.

config

Manage Sift CLI configuration. The config file is named sift.toml and lives in your user data directory.

Subcommand	Description
`config show`	Display the contents of the current config file.
`config where`	Show the path to the current config file.
`config create`	Create a new config file. Fails if one already exists.
`config update`	Update fields in the existing config file.

config update

Flag	Description
`--interactive` / `-i`	Edit or create a profile through prompts. Ignores other flags.
`--grpc-uri` / `-g <uri>`	Base gRPC endpoint for Sift.
`--rest-uri` / `-r <uri>`	Base REST endpoint for Sift.
`--api-key` / `-k <key>`	API key used for authentication.

The command writes to the profile named by the global --profile flag, or default when omitted.

ping

Ping the Sift API to verify credentials and connectivity. Takes no flags.

sift-cli ping

import

Import time series files into Sift.

Common import flags

These flags apply to the Parquet, TDMS, HDF5, and ULog import commands.

Flag	Description
`<path>`	Path to the file to import. Positional.
`--asset` / `-a <name>`	Name of the Asset this data belongs to. Required.
`--run` / `-r <name>`	Run name to associate with the import.
`--run-id <id>`	ID of an existing Run to add data to. Takes precedence over `--run`.
`--wait` / `-w`	Wait until the import finishes processing.
`--preview` / `-p`	Preview the parsed schema without uploading.

import csv

Import a CSV file. Unless specified, all columns are inferred as type string or double. When you pass --channel-column, supply a --data-type, --unit, and --description for each one; the counts must match.

Flag	Description
`<path>`	Path to the CSV file. Positional.
`--asset` / `-a <name>`	Name of the Asset. Required.
`--run` / `-r <name>`	Run name to associate with the import.
`--header-row <n>`	Row containing column headers, 1-based. Default `1`.
`--first-data-row <n>`	Row where data starts, 1-based. Default `2`.
`--channel-column` / `-c <n>`	1-based index of a column to override. Repeatable.
`--data-type` / `-d <type>`	Data type for each `--channel-column`. Repeatable.
`--unit` / `-u <unit>`	Unit for each `--channel-column`. Repeatable.
`--description` / `-n <text>`	Description for each `--channel-column`. Repeatable.
`--enum-config` / `-e <pairs>`	Enum configuration pairs `<key,name>`, for example `"0,start\|1,stop"`.
`--bit-field-config` / `-b <triplets>`	Bit-field triplets `<name,index,length>`, for example `"12v,0,4\|led,4,4"`.
`--time-column` / `-t <n>`	1-based index of the time column. Default `1`.
`--time-format` / `-f <format>`	Time format used in the file. Default `absolute-rfc3339`.
`-s <time>`	RFC 3339 start time to use if the time format is relative.
`--wait` / `-w`	Wait until the import finishes processing.
`--preview` / `-p`	Preview the parsed schema without uploading.

import parquet flat-dataset

A Parquet file where every column is exclusive to a single Channel, except for the time column. By default, every non-time column is imported. When you pass --channel-path, supply a --data-type, --unit, and --description for each one; the counts must match.

Flag	Description
`--channel-path` / `-c <path>`	Path of a data column to import. Repeatable.
`--data-type` / `-d <type>`	Data type for each `--channel-path`. Repeatable.
`--unit` / `-u <unit>`	Unit for each `--channel-path`. Repeatable.
`--description` / `-n <text>`	Description for each `--channel-path`. Repeatable.
`--enum-config` / `-e <pairs>`	Enum configuration pairs `<key,name>`.
`--bit-field-config` / `-b <triplets>`	Bit-field triplets `<index,name,bit_count>`.
`--time-path` / `-t <path>`	Path to the time column. Auto-detected from `time`, `timestamp`, `timestamps`, `ts` if omitted.
`--time-format` / `-f <format>`	Time format. Inferred from the column’s Arrow type if omitted.
`--relative-start-time` / `-s <time>`	RFC 3339 start time to use if the time format is relative.
`--complex-types-mode` / `-m <mode>`	Strategy for maps, lists, and structs. Default `ignore`.

Plus the common import flags.

import parquet cpr

A Parquet file laid out single-channel-per-row.

Flag	Description
`--mode <mode>`	Channel mode: `single` or `multi`. Required.
`--data-path <path>`	Path to the column holding values. Used in both modes.
`--time-path` / `-t <path>`	Path to the time column. Auto-detected if omitted.
`--time-format` / `-f <format>`	Time format. Inferred from the column’s Arrow type if omitted.
`--relative-start-time` / `-s <time>`	RFC 3339 start time to use if the time format is relative.
`--complex-types-mode` / `-m <mode>`	Strategy for maps, lists, and structs. Default `ignore`.
`--channel-name <name>`	Channel name for every row. Required in `single` mode.
`--data-type <type>`	Data type for the channel. Single mode.
`--unit <unit>`	Channel unit. Single mode.
`--description` / `-n <text>`	Channel description. Single mode.
`--name-path <path>`	Path to the column holding Channel names. Required in `multi` mode.

Plus the common import flags.

import tdms

Import a TDMS file.

Flag	Description
`--start-time-override <time>`	Override the start time.
`--fallback-method` / `-f <method>`	Fallback for channels with missing timing. `fail-on-error` (default) or `ignore-error`.
`--time-format <format>`	Time format for channels not using the TDMS timestamp type.
`--relative-start-time` / `-s <time>`	Relative start time for channels using a non-standard time channel.
`--import-file-properties`	Import TDMS file properties to the Run as metadata.

Plus the common import flags.

import hdf5

Import an HDF5 file. Supported channel types across all schemas: bool, int8/16/32/64, uint8/16/32/64, float32, float64. Datasets with other types produce a client-side error.

Flag	Description
`--schema <schema>`	Schema type: `one-d`, `two-d`, or `compound`. Required.
`--time-format <format>`	Time format used in the time dataset or column. Required for HDF5 imports.
`--relative-start-time` / `-s <time>`	RFC 3339 start time if the time format is relative.
`--time-name <name>`	One-d: leaf name of the time dataset when it differs from the auto-detected names.
`--time-index <n>`	Two-d: index of the time column. Default `0`.
`--time-field <name>`	Compound: name of the time field.

The time flags --time-name, --time-index, and --time-field are mutually exclusive. Plus the common import flags.

import ulog

Import a PX4 ULog file.

Flag	Description
`--relative-start-time` / `-s <time>`	RFC 3339 UTC time of log start. Takes precedence over the log’s GPS time fix.
`--info-key <key>`	Info message key to import as Run metadata. Repeatable. Requires `--run` or `--run-id`.
`--param-key <name>`	Parameter name to import as Run metadata. Repeatable. Requires `--run` or `--run-id`.
`--parse-error-policy <policy>`	Handling for recoverable parse errors. `fail-on-error` (default) or `ignore-error`.

Plus the common import flags.

import backups

Import backup files generated by sift_stream.

Flag	Description
`--path` / `-p <dir>`	Directory containing backup files. Defaults to your OS data directory.
`--cleanup` / `-c`	Delete backup files after a successful upload.

Subcommand	Description
`import backups ls [path]`	List backup files in a directory. Defaults to your OS data directory.

export

Export Asset or Run data from Sift.

Common export flags

Flag	Description
`--output` / `-o <file>`	The file to generate. Required.
`--format` / `-f <format>`	Output format: `csv`, `parquet`, or `sun` (WinPlot). Required.
`--channel` / `-c <name>`	Channel name to include. Repeatable.
`--channel-id <id>`	Channel ID to include. Repeatable.
`--channel-regex` / `-x <regex>`	Regular expression selecting Channels by name.
`--calculated-channel <name>`	Calculated Channel name to include. Repeatable.
`--calculated-channel-id <id>`	Calculated Channel ID to include. Repeatable.
`--calculated-channel-regex <regex>`	Regular expression selecting Calculated Channels by name.
`--start <time>`	Start time in RFC 3339 format. Required for Asset exports.
`--stop <time>`	Stop time in RFC 3339 format. Required for Asset exports.

export run

Export data for a Run. Identify the Run by one of the following mutually exclusive selectors.

Flag	Description
`--name` / `-n <name>`	The name of the Run.
`--run-id` / `-r <id>`	The ID of the Run.
`--client-key` / `-k <key>`	The client key of the Run.

Plus the common export flags.

export asset

Export data for an Asset.

Flag	Description
`<asset>`	The name of the Asset. Positional.

Requires --start and --stop. Plus the common export flags.

install completions

Install shell autocompletions.

Subcommand	Description
`install completions print`	Print completions for your shell. Accepts `--shell` / `-s <shell>`; inferred from `$SHELL` if omitted.
`install completions update`	Update the completions file for the current shell.

doc

Serve the bundled Sift CLI documentation over HTTP.

Flag	Description
`--addr <address>`	Address the documentation server binds to. Default `0.0.0.0:3000`.

Data types

The --data-type flag accepts: infer, double, string, enum, bit-field, bool, float, int32, uint32, int64, uint64, bytes. Use infer to detect the type automatically while still setting values such as unit or description.

Time formats

The --time-format flag accepts the following values. For a relative format, set the relative start time flag to an RFC 3339 timestamp that anchors the offsets.

Type	Values
Absolute	`absolute-rfc3339` (default for CSV), `absolute-datetime`, `absolute-unix-seconds`, `absolute-unix-milliseconds`, `absolute-unix-microseconds`, `absolute-unix-nanoseconds`
Relative	`relative-nanoseconds`, `relative-microseconds`, `relative-milliseconds`, `relative-seconds`, `relative-minutes`, `relative-hours`

Complex types modes

The --complex-types-mode flag controls how Parquet maps, lists, and structs are imported:

Value	Description
`ignore`	Ignore columns containing complex types. Default.
`string`	Import complex types as JSON strings.
`bytes`	Import complex types as Arrow bytes.
`both`	Import complex types as both Arrow bytes and JSON strings.

Get started

Ingest telemetry

Investigate

Detect and review

Transform

Export

Sift CLI

Integrate

Manage workspace

Reference

Sift CLI reference

Sift CLI how-tos

Global flags

config

config update

ping

import

Common import flags

import csv

import parquet flat-dataset

import parquet cpr

import tdms

import hdf5

import ulog

import backups

export

Common export flags

export run

export asset

install completions

doc

Data types

Time formats

Complex types modes

​Sift CLI how-tos

​Global flags

​config

​config update

​ping

​import

​Common import flags

​import csv

​import parquet flat-dataset

​import parquet cpr

​import tdms

​import hdf5

​import ulog

​import backups

​export

​Common export flags

​export run

​export asset

​install completions

​doc

​Data types

​Time formats

​Complex types modes

Sift CLI how-tos

Global flags

config

config update

ping

import

Common import flags

import csv

import parquet flat-dataset

import parquet cpr

import tdms

import hdf5

import ulog

import backups

export

Common export flags

export run

export asset

install completions

doc

Data types

Time formats

Complex types modes