CLI Reference
This page provides documentation for our command line tools.
opensampl
CLI utility for openSAMPL
Usage:
opensampl [OPTIONS] COMMAND [ARGS]...
Options:
--env-file PATH Path to the file with configuration settings defined
--help Show this message and exit.
collect
Collect and send data to the database
Usage:
opensampl collect [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
ntp
Collect data readings for NtpProbe
Can collect data to a directory (using --output-dir), straight into the database (--load), or both
Usage:
opensampl collect ntp [OPTIONS]
Options:
--output-dir PATH When provided, will save collected data as a file to
provided directory. Filename will be automatically
generated as
NTP_{ip_address}_{probe_id}_{vendor}_{timestamp}.txt
--load / --no-load Whether to load collected data directly to the
database
--count INTEGER RANGE Samples to collect when interval > 0 [x>=1]
--host TEXT Host or IP address for Probe (default '127.0.0.1')
--probe-id TEXT stable probe_id slug (e.g. local-chrony)
--port INTEGER UDP port for remote mode (use high ports for lab
mocks)
--mode [remote|local] Collect remote or local NTP. Default is 'local'.
--interval FLOAT RANGE Seconds between samples; 0 = single sample and exit
[x>=0.0]
--timeout FLOAT UDP request timeout for remote mode(seconds)
default: 3.0
--collection-ip TEXT Override for the IP address of device collecting
readings. Will attempt to resolve a local network IP
using socket and fall back to '127.0.0.1'
--collection-id TEXT Override for the Probe ID of the device collecting
readings. Will attempt to resolve using
socket.gethostname and fall back to 'collection-
host'
--help Show this message and exit.
config
View and manage environment variables used by openSAMPL
Usage:
opensampl config [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
file
Show the path to the env file used by openSAMPL
Usage:
opensampl config file [OPTIONS]
Options:
--help Show this message and exit.
set
Set the value of an environment variable.
Note that this will only work if the variable is set in the .env file, if it is a true environment variable the change will not persist.
Examples
opensampl config set BACKEND_URL http://localhost:8000
Usage:
opensampl config set [OPTIONS] NAME VALUE
Options:
--help Show this message and exit.
show
Display current environment variable configurations.
Examples
opensampl config show # Show all variables and their values
opensampl config show --explain # Show all variables with descriptions
opensampl config show --var BACKEND_URL # Show specific variable
opensampl config show -e -v BACKEND_URL # Show specific variable with description
Usage:
opensampl config show [OPTIONS]
Options:
-e, --explain Include descriptions of the variables
-v, --var TEXT Specify a single variable to display
--help Show this message and exit.
create
Create a new probe type with scaffolding, based on a config file.
Usage:
opensampl create [OPTIONS] CONFIG_PATH
Options:
-u, --update-db Update the database with the new probe type
-c, --collect-mixin include shell for collect mixin
--help Show this message and exit.
init
Initialize the database.
Creates all tables as defined in the opensampl.db.orm file.
This is not required if you are using opensampl-server, as that is done as part of that initialization of the db.
Usage:
opensampl init [OPTIONS]
Options:
--help Show this message and exit.
load
Load data into database
Usage:
opensampl load [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
adva
Processes a file or directory to load AdvaProbe metadata and/or time series data.
By default, both metadata and time series data are processed. If you specify either --metadata or --time-data, only the selected operation(s) will be performed.
Usage:
opensampl load adva [OPTIONS] FILEPATH
Options:
-m, --metadata Load probe metadata from provided file
-t, --time-data Load time series data from provided file
-a, --archive-path DIRECTORY Override default archive directory path for
processed files. Default: ./archive
-n, --no-archive Do not archive processed files when flag
provided
-w, --max-workers INTEGER Maximum number of worker threads when
processing directories
-c, --chunk-size INTEGER How many records to send at a time. If None,
sends all at once. default: None
-p, --show-progress If flag provided, show the tqdm progress bar
when processing directories. For best
experience, set LOG_LEVEL=ERROR when using
this option.
--help Show this message and exit.
microchiptp4100
Processes a file or directory to load MicrochipTP4100Probe metadata and/or time series data.
By default, both metadata and time series data are processed. If you specify either --metadata or --time-data, only the selected operation(s) will be performed.
Usage:
opensampl load microchiptp4100 [OPTIONS] FILEPATH
Options:
-m, --metadata Load probe metadata from provided file
-t, --time-data Load time series data from provided file
-a, --archive-path DIRECTORY Override default archive directory path for
processed files. Default: ./archive
-n, --no-archive Do not archive processed files when flag
provided
-w, --max-workers INTEGER Maximum number of worker threads when
processing directories
-c, --chunk-size INTEGER How many records to send at a time. If None,
sends all at once. default: None
-p, --show-progress If flag provided, show the tqdm progress bar
when processing directories. For best
experience, set LOG_LEVEL=ERROR when using
this option.
--help Show this message and exit.
microchiptwst
Processes a file or directory to load MicrochipTWSTProbe metadata and/or time series data.
By default, both metadata and time series data are processed. If you specify either --metadata or --time-data, only the selected operation(s) will be performed.
Usage:
opensampl load microchiptwst [OPTIONS] FILEPATH
Options:
-m, --metadata Load probe metadata from provided file
-t, --time-data Load time series data from provided file
-a, --archive-path DIRECTORY Override default archive directory path for
processed files. Default: ./archive
-n, --no-archive Do not archive processed files when flag
provided
-w, --max-workers INTEGER Maximum number of worker threads when
processing directories
-c, --chunk-size INTEGER How many records to send at a time. If None,
sends all at once. default: None
-p, --show-progress If flag provided, show the tqdm progress bar
when processing directories. For best
experience, set LOG_LEVEL=ERROR when using
this option.
--help Show this message and exit.
ntp
Processes a file or directory to load NtpProbe metadata and/or time series data.
By default, both metadata and time series data are processed. If you specify either --metadata or --time-data, only the selected operation(s) will be performed.
Usage:
opensampl load ntp [OPTIONS] FILEPATH
Options:
-m, --metadata Load probe metadata from provided file
-t, --time-data Load time series data from provided file
-a, --archive-path DIRECTORY Override default archive directory path for
processed files. Default: ./archive
-n, --no-archive Do not archive processed files when flag
provided
-w, --max-workers INTEGER Maximum number of worker threads when
processing directories
-c, --chunk-size INTEGER How many records to send at a time. If None,
sends all at once. default: None
-p, --show-progress If flag provided, show the tqdm progress bar
when processing directories. For best
experience, set LOG_LEVEL=ERROR when using
this option.
--help Show this message and exit.
random
Generate and send random test data to the database
Usage:
opensampl load random [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
adva
Generate random test data for AdvaProbe
Usage:
opensampl load random adva [OPTIONS]
Options:
-c, --config PATH YAML configuration file for random data
generation settings
--num-probes INTEGER Number of probes to generate data for
[default: 1]
--duration FLOAT Duration of data in hours [default: 1.0]
--seed INTEGER Random seed for reproducible results
--sample-interval FLOAT Sample interval in seconds [default: 1]
--base-value FLOAT Base value for time offset measurements
[default: random.uniform(-1e-6, 1e-6)]
--noise-amplitude FLOAT Noise amplitude/standard deviation for time
offset measurements [default:
random.uniform(1e-9, 1e-8)]
--drift-rate FLOAT Linear drift rate per second for time offset
measurements [default: random.uniform(-1e-12,
1e-12)]
--outlier-probability FLOAT Probability of outliers per sample [default:
0.01]
--outlier-multiplier FLOAT Multiplier for outlier noise amplitude
[default: 10.0]
--probe-ip TEXT The ip_address you want the random data to show
up under. Randomly generated for each probe if
left empty
--probe-id TEXT The probe_id you want the random data to show
up under. Randomly generated for each probe if
left empty; incremented if multiple probes
--help Show this message and exit.
microchiptp4100
Generate random test data for MicrochipTP4100Probe
Usage:
opensampl load random microchiptp4100 [OPTIONS]
Options:
-c, --config PATH YAML configuration file for random data
generation settings
--num-probes INTEGER Number of probes to generate data for
[default: 1]
--duration FLOAT Duration of data in hours [default: 1.0]
--seed INTEGER Random seed for reproducible results
--sample-interval FLOAT Sample interval in seconds [default: 1]
--base-value FLOAT Base value for time offset measurements
[default: random.uniform(-5e-7, 5e-7)]
--noise-amplitude FLOAT Noise amplitude/standard deviation for time
offset measurements [default:
random.uniform(1e-8, 5e-8)]
--drift-rate FLOAT Linear drift rate per second for time offset
measurements [default: random.uniform(-1e-10,
1e-10)]
--outlier-probability FLOAT Probability of outliers per sample [default:
0.01]
--outlier-multiplier FLOAT Multiplier for outlier noise amplitude
[default: 10.0]
--probe-ip TEXT The ip_address you want the random data to show
up under. Randomly generated for each probe if
left empty
--probe-id TEXT The probe_id you want the random data to show
up under. Randomly generated for each probe if
left empty; incremented if multiple probes
--help Show this message and exit.
microchiptwst
Generate random test data for MicrochipTWSTProbe
Usage:
opensampl load random microchiptwst [OPTIONS]
Options:
--num-channels INTEGER Number of remote channels to generate data for
[default: 4]
--ebno-base-value FLOAT Base value for Eb/No measurements [default:
random.uniform(-1e-8, 1e-8)]
--ebno-noise-amplitude FLOAT Noise amplitude/standard deviation for Eb/No
measurements [default: random.uniform(1e-10,
1e-9)]
--ebno-drift-rate FLOAT Linear drift rate per second for Eb/No
measurements [default:
random.uniform(-1e-12, 1e-12)]
-c, --config PATH YAML configuration file for random data
generation settings
--num-probes INTEGER Number of probes to generate data for
[default: 1]
--duration FLOAT Duration of data in hours [default: 1.0]
--seed INTEGER Random seed for reproducible results
--sample-interval FLOAT Sample interval in seconds [default: 1]
--base-value FLOAT Base value for time offset measurements
[default: random.uniform(-1e-8, 1e-8)]
--noise-amplitude FLOAT Noise amplitude/standard deviation for time
offset measurements [default:
random.uniform(1e-10, 1e-9)]
--drift-rate FLOAT Linear drift rate per second for time offset
measurements [default:
random.uniform(-1e-12, 1e-12)]
--outlier-probability FLOAT Probability of outliers per sample [default:
0.01]
--outlier-multiplier FLOAT Multiplier for outlier noise amplitude
[default: 10.0]
--probe-ip TEXT The ip_address you want the random data to
show up under. Randomly generated for each
probe if left empty
--help Show this message and exit.
ntp
Generate random test data for NtpProbe
Usage:
opensampl load random ntp [OPTIONS]
Options:
-c, --config PATH YAML configuration file for random data
generation settings
--num-probes INTEGER Number of probes to generate data for
[default: 1]
--duration FLOAT Duration of data in hours [default: 1.0]
--seed INTEGER Random seed for reproducible results
--sample-interval FLOAT Sample interval in seconds [default: 1]
--base-value FLOAT Base value for time offset measurements
[default: random.uniform(-1e-4, 1e-4)]
--noise-amplitude FLOAT Noise amplitude/standard deviation for time
offset measurements [default:
random.uniform(1e-9, 1e-7)]
--drift-rate FLOAT Linear drift rate per second for time offset
measurements [default: random.uniform(-1e-12,
1e-12)]
--outlier-probability FLOAT Probability of outliers per sample [default:
0.01]
--outlier-multiplier FLOAT Multiplier for outlier noise amplitude
[default: 10.0]
--probe-ip TEXT The ip_address you want the random data to show
up under. Randomly generated for each probe if
left empty
--help Show this message and exit.
table
Perform a Table load into the database.
Load data directly into a database table. Format can be yaml or json. Can be a list of dictionaries or a single
dictionary.
You do not have to specify schema, is assumed to be castdb.
\n\n The --if-exists option controls how to handle conflicts:\n - update: Only update fields that are provided and non-default (default)\n - error: Raise an error if entry exists\n - replace: Replace all non-primary-key fields with new values\n - ignore: Skip if entry exists\n
Example:\n
cli.py table load locations data.json\n
cli.py table load probe_metadata metadata.yaml\n
Usage:
opensampl load table [OPTIONS] {defaults|locations|metric_type|reference_type|
test_metadata|probe_metadata|reference|adva_metadata|micr
ochip_tp4100_metadata|microchip_twst_metadata|ntp_metadat
a|probe_data} FILEPATH
Options:
-i, --if-exists [update|error|replace|ignore]
How to handle conflicts with existing
entries
--help Show this message and exit.