⏯️ Actions¶
Meerschaum actions (commands) are designed with a verb-noun syntax and recognize both singular and plural nouns (e.g. sync pipe
is the same as sync pipes
).
To see all of the available commands, run help
or show actions
.
To get help for specific actions, add the flag -h
to any command, or preface the command with help
when inside the shell (e.g. help show pipes
).
Commands may be run directly on the command line with mrsm
, or in an interactive shell, which you can start with the command mrsm
.
Below are all of the Meerschaum commands and descriptions.
Action | Sub-Actions | Description | Flags | Examples | |
---|---|---|---|---|---|
api | {None} | Send commands to an API instance. Depreciated ― replaced by the instance command |
• positional arguments May include the label to the API connector (e.g. 'main') followed by a list of commands. • All other arguments are passed to the API instance. |
api delete pipes -y api main delete pipes -y |
|
start, boot, init | Start the web API server. Alias for the command start api. |
• -p, --port The port to bind to. Defaults to 8000. • --host The host interface to bind to. Defaults to 0.0.0.0. • -w, --workers How many threads to use for the server. Defaults to the number of cores. |
• --no-dash, --nodash Do not start the web dashboard. • --no-auth, --noauth Do not require authentication. • --production, --gunicorn Run with web server via gunicorn. |
api start -p 8001 --no-dash | |
bootstrap | config | Delete and regenerate the default Meerschaum configuration. Not used often; mostly meant for development |
• -y, --yes • -f, --force |
bootstrap config -y |
|
connectors | Launch the wizard for creating a new connector. Useful when adding new database or API connections |
• -y, --yes • -f, --force |
bootstrap connectors | ||
pipes | Launch the wizard for creating new pipes. The recommended first action once you start up the stack. Here is more information about bootstrapping pipes |
• -c, -C, --connector-keys The connector keys of the new pipes. Multiple values are allowed. • -m, -M, --metric-keys The metric keys of the new pipes. Multiple values are allowed. • -l, -L, --location-keys The location keys of the new pipes. The string 'None' will be parsed as None. Multiple values are allowed. |
• -i, --instance, --mrsm-instance The connector keys string to the instance for the new pipes (defaults to 'sql:main'). • -y, --yes • -f, --force • --noask |
bootstrap pipes bootstrap pipes -c sql:main sql:foo -m bar |
|
clear | {None} | Clear the screen. | None | clear | |
pipes | Delete rows (clear the pipe) within a given date range. | • --begin Only remove rows newer than this datetime. • --end Only remove rows older than this datetime (not including end). |
• -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags Only select pipes with these tags |
clear pipes -c plugin:foo \ --begin 2022-01-01 --end 2022-02-01 |
|
copy | connectors | Create new connectors from existing ones. NOTE: Not implemented! |
• -c, -C, --connector-keys | copy connectors sql:main copy connectors -c sql:main |
|
pipes | Create new pipes from existing ones. Useful for migrating pipes between instances. |
• -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• -y, --yes • -f, --force • --noask • --debug |
copy pipes -i sql:main -m foo | |
debug | {None} | Toggle debug mode. Only available in the Meerschaum shell. |
None | debug | |
delete | config | Delete configuration files. May specify which config files to delete. |
• -y, --yes • -f, --force • --noask • --debug |
delete config delete config plugins system |
|
connectors | Remove connectors from the configuration file. | • positional arguments The connector keys. • -c, -C, --connector-keys |
• -y, --yes • -f, --force • --noask • --debug |
delete connectors sql:foo delete connectors -c sql:foo |
|
jobs | Remove background jobs. If the jobs are running, it will ask to stop them first. |
• positional arguments Names of jobs. |
• -y, --yes • -f, --force • --noask • --debug |
delete jobs -y delete jobs sad_tram -y |
|
pipes | Drop pipes and remove their registration from the instance. | • -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• -y, --yes • -f, --force • --noask • --debug |
delete pipes -c plugin:foo plugin:bar -y delete pipes -i sql:mydb |
|
plugins | Delete the plugins' registrations from the repository. | • positional arguments Names of plugins (without 'plugin:'). • -r, --repo, --repository The API instance keys of the plugins repository. |
• -y, --yes • -f, --force • --noask • --debug |
delete plugins foo bar -r api:mrsm | |
users | Delete users from a Meerschaum instance. | • positional arguments List of usernames. • -i, --instance, --mrsm-instance |
• -y, --yes • -f, --force • --noask • --debug |
delete users foo -i sql:db | |
drop | pipes | Drop the pipes' tables but keep the registration. | • -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• -y, --yes • -f, --force • --noask • --debug |
drop pipes -m weather -y |
tables | NOTE: Not implemented! | None | drop tables foo | ||
edit | config | Open configuration files for editing. May specify which files to open, defaults to 'meerschaum'. |
• positional arguments List of files to edit (without extensions). |
edit config edit config plugins system shell |
|
pipes {definition} | Open YAML files to edit the parameters of pipes. Add the word "definition" to open a SQL file (SQL pipes only). |
• -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• positional arguments "definition" |
edit pipes -c sql:foo edit pipes definition -c sql:foo |
|
users | Edit the attributes of users, e.g. to make a user an administrator or to change a password. |
• positional arguments List of usernames. • -i, --instance, --mrsm-instance |
• -y, --yes • -f, --force • --noask • --debug |
edit users bob -i sql:main edit users alice bob |
|
help | {None} |
Print help text about actions. Preface any command with 'help'. Only available in the shell. The flag -h works both in the shell and on the command line. |
• positional arguments The command to seek help for. |
help delete pipes | |
install | packages | Install Python packages into the Meerschaum virtual environment. |
• positional arguments List of packages. • -A, --sub-args Additional arguments to pass to pip. |
• --debug | install packages pandas numpy |
plugins | Install Meerschaum plugins from a repository. | • positional arguments List of plugins. • -r, --repo, --repository The keys to the Meerschaum API repository. |
• -f, --force • --debug |
install plugins noaa color install plugins foo -r api:bar |
|
required | Install a plugins' required packages into its virtual environment. |
• positional arguments List of plugins. • -r, --repo, --repository The keys to the Meerschaum API repository. |
• -f, --force • --debug |
install required noaa install required foo -r api:bar |
|
login | {None} | Log into a Meerschaum API instance and save the credentials. |
• positional arguments Connector keys for an API instance. • -c, -C, --connector-keys |
• -y, --yes • --noask • --debug |
login api:main api:foo api:bar |
python | {None} | Launch a Python REPL with Meerschaum already imported. Python code may be include as a positional argument. |
• positional arguments Python code to execute. • --debug |
python python 'print("foo")' |
|
register | pipes |
Register new pipes on a Meerschaum instance. Connector and metric keys are required. Registering pipes from plugins with a register function will set the pipes' parameters to the function's output. |
• -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys |
• --debug | register pipes -c plugin:noaa -m weather |
plugins | Publish a plugin onto a Meerschaum repository. | • positional arguments List of plugins. • -r, --repo, --repository |
• -y, --yes • -f, --force • --debug |
register plugins myplugin1 myplugin2 register plugins noaa -r api:foo |
|
users | Create new users on a Meerschaum instance. | • positional arguments List of users. • -i, --instance, --mrsm-instance |
• --debug | register users alice bob register users bob -i sql:foo |
|
reload | {None} | Reload the current Meerschaum process and plugins. Useful when developing plugins. |
• --debug | reload | |
setup | plugins | Execute the setup function for Meerschaum plugins. | • positional arguments List of plugins. • -r, --repo, --repository |
setup plugins noaa setup plugins foo -r api:bar |
|
show | actions | Print a list of available Meerschaum actions. If global Unicode settings are False, only use ASCII (for almost all show commands). |
• --nopretty | show actions | |
arguments | Print the provided command line arguments. | All arguments. See mrsm -h for available flags. |
show arguments foo --begin 2022-01-01 | ||
columns | Print tables of pipes' columns. | • -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• --nopretty | show columns -m foo | |
config | Print the configuration dictionary. |
• positional arguments Configuration keys to print. |
• --nopretty | show config show config formatting emoji |
|
connectors | Print the attributes for the registered connectors. | • positional arguments Keys for a specific connector. |
• --nopretty | show connectors show connector sql:main |
|
data | Print previews of the contents of pipes. | • -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• --nopretty | show data show data -m weather |
|
gui | Start the desktop terminal. Alias for start gui. |
• -p, --port The port for the webterm server. |
• --debug | show gui | |
help | Print the help text for the Meerschaum flags. The same text is printed for mrsm -h. |
None |
show help | ||
jobs | Print a table with information about background jobs. | • positional arguments Names of jobs to print (all if omitted). |
• --nopretty | show jobs show jobs nice_cat |
|
logs | Print the newest lines in the log file as they are printed. --nopretty will print the entire contents of the files. |
• positional arguments Names of jobs to print (all if omitted). |
• --nopretty | show logs show logs golden_trolley --nopretty |
|
modules | Print all of the currently imported modules. | None | show modules | ||
packages | Show the optional Meerschaum dependencies. | • positional arguments Dependency groups to print. |
• --nopretty | show packages show packages api |
|
pipes | Print a stylized tree of available Meerschaum pipes. Respects global Unicode and ANSI settings. |
• -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• --nopretty • --debug |
show pipes show pipes -c plugin:noaa |
|
plugins | Print all of the installed plugins. If the command is "show plugins all", print all of the plugins on the repository. If the command is "show plugins [username]," print all of the plugins on the repository from that user. |
• positional arguments None, "all", or a username • -r, --repo, --repository |
• --nopretty • --debug |
show plugins show plugins all show plugins foo -r api:bar |
|
rowcounts | Print the row counts for pipes. If 'show rowcounts remote', print the row counts for the remote definitions (only for SQL pipes). |
• -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• positional arguments None or 'remote' • -w, --workers How many worker threads to use when calculating rowcounts. |
show rowcounts show rowcounts -c plugin:foo show rowcounts remote |
|
users | Print the registered users on a Meerschaum instance. | • -i, --instance, --mrsm-instance • --debug |
show users show users -i sql:db |
||
version | Print the running Meerschaum version. | • --nopretty | show version show version --nopretty |
||
sql | {None} | Open an interactive CLI, read a table, or execute a query. | • positional arguments sql {label} {method} {query / table} |
• --nopretty • --gui Open the resulting dataframe in a graphical editor. |
# Open a CLI for sql:main sql # Open a CLI for sql:local sql local # Read the table 'foo' sql foo # Read query on 'sql:main' sql "SELECT * FROM foo WHERE id = 1" # Execute a query on 'sql:local' # ('exec' is optional) sql local exec \ "INSERT INTO table (id) VALUES (1)" |
stack | See commands. |
Manage the Meerschaum stack. Alias for docker-compose. Meerschaum flags are ignored. |
See docker-compose documentation. | stack up -d db stack ps stack down -v |
|
start | api |
Start the web API server. | • -p, --port The port to bind to. Defaults to 8000. • --host The host interface to bind to. Defaults to 0.0.0.0. • -w, --workers How many threads to use for the server. Defaults to the number of cores. |
• --no-dash, --nodash Do not start the web dashboard. • --no-auth, --noauth Do not require authentication. • --production, --gunicorn Run with web server via gunicorn. |
start api -p 8001 --no-dash |
gui | Start the desktop terminal. | • -p, --port The port for the webterm server. |
• --debug | start gui | |
jobs | Start existing jobs or create new jobs. You can also create new jobs by adding -d to any command (except stack). |
• positional arguments The names of jobs or commands for a new job. • --name The name of a new or existing job. |
• All other flags are passed to new jobs. | start jobs start api start jobs happy_seal start jobs --name happy_seal start api -d --name my_job |
|
webterm | Start the web terminal. Useful for sharing a single Meerschaum instance with a team. NOTE: This can be a huge security concern! |
• -p, --port The port to bind to. Defaults to 8765. • --host The host interface to bind to. Defaults to 127.0.0.1. |
• -f, --force Find the next available port. • --nopretty |
start webterm start webterm -f -h 0.0.0.0 |
|
stop | jobs | Stop running jobs that were started with -d or start jobs. | • positional arguments Names of jobs. Defaults to all. |
• -y, --yes • -f, --force • --noask • --debug • --nopretty |
stop jobs -y stop jobs happy_bear |
sync | pipes | Fetch new data and update your pipes. This will execute sync() or fetch() for plugins and SQL queries for SQL pipes. The shell interface will print a progress bar and spinner to indicate that a sync is running. |
• --loop Continuously sync pipes. • --min-seconds How many seconds to sleep between laps. Defaults to 1. • --timeout, --timeout-seconds Maximum number of seconds before cancelling a pipe's syncing job. Defaults to 300. • --begin Fetch data newer than this datetime. • --end Fetch data older than this datetime. • -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
• -w, --workers How many threads to use to process the queue. • --chunksize Specify the chunksize for syncing and retrieving data. Defaults to 900. • --async, --unblock Do not wait for a pipe to finish syncing before continuing. • --cache When syncing pipes, sync to a local database for later analysis. • --debug |
sync pipes sync pipes --loop -c plugin:foo sync pipes --timeout 900 sync pipes --chunksize 2000 sync pipes -w 1 sync pipes --async sync pipes --begin 2022-01-01\ --end 2022-02-01-01 |
uninstall | packages | Uninstall Python packages from the Meerschaum virtual environment. |
• positional arguments List of packages. • -A, --sub-args Additional arguments to pass to pip. |
• --debug | uninstall packages rich pandas |
plugins | Uninstall local Meerschaum plugins. | • positional arguments List of plugins. |
• -y, --yes • --noask • -f, --force • --debug |
uninstall plugins noaa | |
upgrade | meerschaum, mrsm | Upgrade to the latest release of Meerschaum, and pull latest images for the stack. | • positional argument A dependency group (e.g. 'full' will install meerschaum[full]). |
• -y, --yes • --noask • -f, --force • --debug |
upgrade mrsm upgrade meerschaum full |
packages | Upgrade the packages in a dependency group (default 'full'). | • positional argument A dependency group. |
• -y, --yes • --noask • -f, --force • --debug |
upgrade packages upgrade packages docs |
|
plugins | Upgrade installed plugins to the latest versions. If no names are provided, upgrade all plugins. |
• positional arguments Plugins to upgrade. Default is all. |
• -y, --yes • --noask • -f, --force • --debug |
upgrade plugins upgrade plugins foo -y |
|
verify | packages | Verify the versions of installed packages. | • --debug | verify packages | |
pipes | Verify the contents of pipes using iterative backtracking. NOTE: Not implemented! See my thesis research for potential strategies. |
• -i, --instance, --mrsm-instance • -c, -C, --connector-keys • -m, -M, --metric-keys • -l, -L, --location-keys • -t, --tags |
verify pipes |