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

# Sift CLI reference

> Complete command, subcommand, and flag reference for the Sift CLI.

This page documents every command, subcommand, and flag in the Sift CLI. For installation and configuration, see [Sift CLI](/documentation/cli/sift-cli).

## Sift CLI how-tos

* [Sift CLI setup](/documentation/cli/sift-cli)
* [Import files with the Sift CLI](/documentation/cli/import-files-with-the-sift-cli)
* [Export data with the Sift CLI](/documentation/cli/export-data-with-the-sift-cli)

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

```bash theme={null}
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](#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](#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](#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](#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](#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](#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](#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. |