Skip to content

⏯️ 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