ElemBio CLI reference
Review all ElemBio CLI commands. Use the CLI to list and retrieve metadata, download data, and mount remote storage.
The ElemBio™ CLI is a command-line client for the ElemBio API. Use it to list and retrieve metadata, download data, and mount remote storage. For installation and your first commands, see the CLI quickstart.
Command groups
| Command | Purpose |
|---|---|
elembio login / logout / whoami | Authenticate and inspect the active identity |
elembio profile | Manage named credential profiles |
elembio runs | List, inspect, and download runs |
elembio executions | List, inspect, download, and read logs for executions |
elembio instruments | List and inspect instruments |
elembio storage | List, inspect, and download storage connections |
elembio mount | Mount run, execution, or storage data (experimental) |
elembio version / update / completion | Show version, self-update, and generate shell completion |
Global options
These persistent flags are inherited by all commands and their subcommands.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--api-url | string | No | — | Override the API endpoint |
--api-key | string | No | — | Override the API key |
--profile | string | No | default | Use a specific config profile |
-o, --output | string | No | table | Set output format: table, json, or yaml |
--no-headers | boolean | No | false | Omit table headers |
-q, --quiet | boolean | No | false | Suppress non-essential output |
List commands additionally accept wide as an output format.
Authentication
Authenticate the CLI and manage named credential profiles.
| Command | Purpose |
|---|---|
elembio login | Authenticate and store credentials in a profile |
elembio logout | Remove the stored credentials for the active profile |
elembio whoami | Show the active identity and the tenant the key belongs to |
elembio profile list | List configured profiles |
elembio profile current | Show the active profile |
elembio profile use <profile> | Switch the active profile |
elembio profile delete <profile> | Delete a profile |
Configuration and profiles
The CLI reads credentials from a config file or environment variables and supports multiple named profiles.
Config file
Credentials are stored in ~/.elembio/config.yaml under named profiles:
cat ~/.elembio/config.yaml
Your profile appears as follows:
current-profile: default
profiles:
default:
api-url: https://cloud-api.usw2.elembio.io
api-key: ebp_s6iyTXunEXAMPLE
Override the config location with ELEMBIO_CONFIG_DIR or ELEMBIO_CONFIG.
Environment variables
Set credentials without a config file. Environment variables take precedence over the config file:
export ELEMBIO_API_KEY=ebp_s6iyTXunEXAMPLE
export ELEMBIO_API_URL=https://cloud-api.usw2.elembio.io
Create a new profile
To create a new profile, append the --profile flag on login:
elembio login --profile <named_profile>
Runs
The runs group operates on runs and their output files. All subcommands accept the global options.
| Command | Purpose |
|---|---|
elembio runs list | List runs |
elembio runs get <run> | Get one run by ID or name |
elembio runs files <run> | List files in a run |
elembio runs download <run> | Download run files |
elembio runs download-manifest <run> | Download the run planning manifest CSV |
runs list
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--filter | string (repeatable) | No | — | Filter expression, for example status:completed |
--page-size | integer | No | 100 | Results per page |
--max-items | integer | No | 100 | Maximum results across pages |
Repeat --filter once per term, or pass multiple space-separated terms in a single quoted flag. Both forms are equivalent and ANDed together:
# One term per flag (matches the Core concepts examples)
elembio runs list --filter status:completed --filter type:sequencing
# Equivalent: multiple terms in a single quoted flag
elembio runs list --filter "status:completed type:sequencing"
runs download
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
-d, --output-dir | path | No | — | Destination directory |
--include | string | No | — | Glob pattern of files to include |
--exclude | string | No | — | Glob pattern of files to exclude |
-p, --parallel | integer | No | 4 | Concurrent downloads |
--dry-run | boolean | No | false | Show what would download without transferring |
elembio runs download My_Example_Run --output-dir ./my-run --dry-run
Executions
The executions group operates on analysis executions and their outputs. All subcommands accept the global options.
| Command | Purpose |
|---|---|
elembio executions list | List executions |
elembio executions get <execution> | Get one execution |
elembio executions files <execution> | List execution output files |
elembio executions download <execution> | Download execution files |
elembio executions logs <execution> | Print execution logs |
list, download, and files accept the same flags as the runs list and runs download equivalents; only the filter keywords differ.
executions logs
Logs write to standard streams so they compose with shell redirection: standard output carries the log, standard error carries diagnostics.
elembio executions logs exec_6a21f3c4ae4c10fc610d8e92 > execution.log
Instruments
The instruments group is read-only. All subcommands accept the global options.
| Command | Purpose |
|---|---|
elembio instruments list | List instruments |
elembio instruments get <serial-number> | Get one instrument by serial number |
elembio instruments list -o wide
elembio instruments get AV242106
Storage
The storage group operates on storage connections and their files. All subcommands accept the global options.
| Command | Purpose |
|---|---|
elembio storage list | List storage connections |
elembio storage get <connection> | Get one connection by ID or name |
elembio storage files <connection> | List files in a connection |
elembio storage download <connection> [file ...] | Download files, or print temporary S3 credentials |
elembio storage list
elembio storage files my-connection --prefix runs/
storage download
Download files from a storage connection, or print temporary S3 credentials for direct access with the AWS CLI or SDKs. Pass one or more file paths to download specific files; without them, all files under the connection (or under --prefix) are downloaded.
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--mode | string | No | all | Download mode: all (everything), sync (only missing or changed files, compared by size), or credentials (print temporary S3 credentials) |
--prefix | string | No | — | Storage-absolute prefix to filter files by (for example, runs/run-456/) |
-d, --output-dir | path | No | — | Local directory for downloads |
--include | string (repeatable) | No | — | Glob pattern for files to include |
--exclude | string (repeatable) | No | — | Glob pattern for files to exclude |
-p, --parallel | integer | No | 4 | Number of parallel downloads |
--dry-run | boolean | No | false | List files without downloading |
--overwrite | boolean | No | false | Overwrite existing files |
--skip-existing | boolean | No | false | Skip files that exist locally with matching size |
--retries | integer | No | 3 | Number of retry attempts per file |
--delete | boolean | No | false | Delete local files not present in remote (only with --mode sync) |
--force | boolean | No | false | Force re-download of all files even if size matches (only with --mode sync) |
-o, --output | string | No | env | Output format for --mode credentials: env (auto-detects PowerShell), json, or yaml |
Download (default --mode all)
# All files under a prefix, by connection ID or name
elembio storage download stc_62cd9b81be1cf6503368b4e6 --prefix runs/run-456/outputs/
elembio storage download "Production S3" --prefix data/ --output-dir ./local-data
# Only matching files under a prefix
elembio storage download "Production S3" --prefix results/ --include "*.vcf"
# Specific files (positional)
elembio storage download "Production S3" data/samples/sample1.vcf
elembio storage download "Production S3" data/a.bam data/b.bam
# Preview without downloading
elembio storage download "Production S3" --prefix data/ --dry-run
Sync mode (--mode sync)
Download only files that are missing locally or whose size differs from the remote.
elembio storage download "Production S3" --mode sync --prefix data/
elembio storage download "Production S3" --mode sync --delete --prefix data/ # also remove local files no longer in remote
elembio storage download "Production S3" --mode sync --force --prefix data/ # re-download even when size matches
elembio storage download "Production S3" --mode sync --dry-run --prefix data/ # preview the sync actions
Credentials mode (--mode credentials)
Print temporary, scoped S3 credentials instead of downloading, for use with the AWS CLI or SDKs.
elembio storage download "Production S3" --mode credentials --prefix data/
elembio storage download "Production S3" --mode credentials -o json
elembio storage download "Production S3" --mode credentials -o yaml
# Export the credentials into your shell and use the AWS CLI directly (bash or zsh)
eval $(elembio storage download stc_62cd9b81be1cf6503368b4e6 --mode credentials)
aws s3 sync s3://bucket/storage/stc_62cd9b81be1cf6503368b4e6/ ./stc_62cd9b81be1cf6503368b4e6/
Mount
elembio mount creates and manages read-only FUSE mounts of run, execution, or storage data. Files stream on demand so you can browse large datasets without downloading them first. Mounts authenticate with short-lived, scoped storage credentials from the storage connection.
By default, create commands run in the foreground until you press Ctrl+C. Pass --detach to run the mount in the background, or use elembio mount unmount <mountpoint> from another terminal to release it.
FUSE mount support is experimental and not supported for Windows.
| Command | Purpose |
|---|---|
elembio mount run <run> <mountpoint> | Mount run files |
elembio mount execution <execution> <mountpoint> | Mount execution output files |
elembio mount storage <connection> <mountpoint> | Mount storage connection files |
elembio mount list | List live and stale ElemBio mounts on this host |
elembio mount unmount <mountpoint> | Release a mount (rm is an alias) |
# Mount a sequencing run in the foreground
elembio mount run seq_507f1f77bcf86cd799439011 ./mnt
# Mount in the background
elembio mount run seq_507f1f77bcf86cd799439011 ./mnt --detach
# Inspect mounts, then release
elembio mount list
elembio mount unmount ./mnt
# Force-release a stale mount
elembio mount unmount --force ./mnt
Updates
Inspect the installed version, self-update, and generate shell completion.
| Command | Purpose |
|---|---|
elembio version | Show the installed CLI version |
elembio update | Update the CLI to the latest release |
elembio completion <shell> | Generate a shell completion script for bash, zsh, fish, or powershell |