Commands

Below is a concise reference of all available commands and key options.

For a complete description of all configuration file options, see Configuration File.

Common options

-c, --configfile PATH: configuration file (default: seiscat.conf).
Event file input (initdb, updatedb):
- -f, --fromfile FILE [FILE ...]: read events from one or more files. Accepts multiple filenames. Tries CSV format first, then falls back to ObsPy format auto-detection (QuakeML, SC3ML, NLLOC, etc.).
- CSV field and delimiter auto-detection: When reading CSV files, the tool automatically attempts to detect column meanings based on common name patterns (e.g., recognizes longitude, lon, as longitude, or evid, event_id, etc., as event ID). It also tries to infer the correct delimiter (comma, semicolon, tab, space) by analyzing the file. This “best effort” approach handles most CSV formats without additional configuration.
- -d, --delimiter DELIM: Override CSV delimiter auto-detection. Use \t for tab, " " for space, or any other character. Only used for CSV files.
- -n, --column_names NAME [NAME ...]: Override auto-detected column names by explicitly specifying the sequence of column meanings (e.g., -n time lat lon depth mag). Only used for CSV files.
- -x, --missing-value VALUE [VALUE ...]: Treat one or more values/strings as missing values in CSV input. Single-value example: --missing-value -999. Multiple-value example: --missing-value -999 N/A. Only used for CSV files.
- -z, --depth_units {m,km}: Specify depth units if auto-detection fails or to override the detected value. Only used for CSV files.
- -C, --crop: when reading from file, crop events to the geographic, depth, magnitude, and event-type selection criteria from the config. Has no effect when importing from FDSN (criteria are already applied at query time).
Selection and ordering (where supported: see per-command):
- -w, --where "KEY OP VALUE [AND|OR KEY OP VALUE ...]": filter events.
- --where-help: display detailed help for the --where syntax with examples (formatted with syntax highlighting).
- -a, --allversions: consider all versions of each event.
- --sortby FIELD: sort output by any database field (default: time). Common fields: time, lat, lon, depth, mag, evid. Supports tab-completion of available field names.
- -r, --reverse: reverse output order.

Filtering with `--where`

Use comparisons like =, <, >, <=, >=, != and combine clauses with AND/OR (case-insensitive). Quote the whole expression to avoid shell interpretation.

For missing values (SQL NULL), use either SQL syntax or the shorthand None form:

mag IS NULL (equivalent to mag=None or mag==None)
mag IS NOT NULL (equivalent to mag!=None)

A bare field name is also accepted and uses SQL truthiness. For numeric fields this means “non-null and non-zero”:

mag is equivalent to mag IS NOT NULL AND mag != 0
mag is not equivalent to mag!=None (because mag!=None keeps zero magnitudes)

For detailed help with the --where syntax, use --where-help, e.g.:

seiscat print --where-help

This displays a formatted guide with field names, operators, and examples.

Examples:

seiscat print -w "depth < 10.0 AND mag >= 3.0"
seiscat print -w "depth < 10.0 OR depth > 100.0"
seiscat print -w "evid = aa1234bb"
seiscat print -w "mag IS NULL"
seiscat print -w "mag==None"
seiscat print -w "mag!=None"
seiscat export catalog.csv -w "time >= '2023-01-01' AND time < '2024-01-01'"
seiscat plot -w "mag >= 4.0"

Sorting with `--sortby`

Control the order of catalog output by sorting on any database field. By default, events are sorted by time (oldest first). Use --reverse to reverse the sort order.

Common sort fields:

time: origin time (default)
mag: magnitude
depth: depth
lat, lon: latitude, longitude
evid: event ID (alphabetical)

You can sort by any field in your database, including custom extra fields defined in your configuration.

Examples:

seiscat print --sortby mag             # Sort by magnitude (smallest first)
seiscat print --sortby mag --reverse   # Largest magnitude first
seiscat print --sortby depth           # Sort by depth (shallowest first)
seiscat export catalog.csv --sortby lat  # Sort by latitude
seiscat plot --sortby time --reverse   # Plot with latest events on top

Note: When plotting with seiscat plot, the sort order determines which events are drawn on top. Using --sortby time (default) ensures the most recent events appear on top of older ones. You can change this behavior to emphasize other characteristics (e.g., --sortby mag to draw larger magnitude events on top).

seiscat initdb

Initialize the database (from configured sources or an event file).

seiscat initdb                           # from config (e.g., FDSN)
seiscat initdb -f catalog.csv            # from CSV
seiscat initdb -f catalog.csv -x -999    # one missing-value marker
seiscat initdb -f catalog.csv -x -999 N/A  # two missing-value markers
seiscat initdb -f catalog.csv -z km      # explicit depth units
seiscat initdb -f catalog.xml            # QuakeML (ObsPy auto-detect)
seiscat initdb -f events.quakeml         # QuakeML (ObsPy auto-detect)
seiscat initdb -f events.sc3ml           # SC3ML format
seiscat initdb -f catalog.csv -C         # crop to config criteria
seiscat initdb -f catalog.csv --csv-extra-columns  # import extra CSV cols

Options: --configfile, event file input options, --missing-value, --depth_units, --crop, --csv-extra-columns.

--csv-extra-columns imports non-standard CSV columns as additional database columns (TEXT) and fills them row-by-row. This option is supported for seiscat initdb only.

seiscat updatedb

Update an existing database (honors recheck_period in the config). Can also read new events from an event file.

seiscat updatedb
seiscat updatedb -f catalog.csv
seiscat updatedb -f events.xml
seiscat updatedb -f catalog.csv -C

Options: --configfile, event file input options, --missing-value, --depth_units, --crop.

seiscat cropdb

Crop an existing database to the selection criteria defined in the configuration file. A backup file (<db_file>.bak) is created first.

seiscat cropdb
seiscat cropdb -c custom.conf

Options: --configfile.

seiscat editdb

Edit, replicate, or delete events in place. It can also modify table columns (add/delete/rename).

# Edit a specific event (version autodetected unless specified)
seiscat editdb EVID [EVENT_VERSION] -s key=value [-s key=value ...]

# Increment numeric fields
seiscat editdb EVID -i depth=3.0 -i mag=-0.5

# Replicate or delete
seiscat editdb EVID --replicate
seiscat editdb EVID --delete --force

# Edit table columns (global operations)
seiscat editdb --add-column quality:TEXT
seiscat editdb --rename-column quality=quality_flag
seiscat editdb --delete-column quality_flag

Options: --configfile, --where (to target multiple events), --set KEY=VALUE (repeatable), --increment KEY=INCREMENT (repeatable), --replicate, --delete, --add-column NAME[:TYPE], --rename-column OLD=NEW, --delete-column NAME, --force.

Default columns (evid, ver, time, lat, lon, depth, mag, mag_type, event_type) are protected from rename/delete. User-defined columns (from extra_field_* config options or added later) are not protected and can be renamed/deleted.

seiscat fetchdata

Fetch full event details (QuakeML), waveform data, or both. Optional local SDS archive for waveforms.

# Download event details (QuakeML)
seiscat fetchdata --event [EVID]

# Download waveform data + StationXML
seiscat fetchdata --data [--sds /path/to/SDS] [EVID]

# Download both
seiscat fetchdata --both [--sds /path/to/SDS] [EVID]

Options: --configfile, --where, --allversions, --sds SDS_DIR, one of --event | --data | --both (required), --overwrite_existing (only for event details).

seiscat print

Print the catalog to the console in various formats.

seiscat print                        # default table format
seiscat print -f stats               # Summary statistics
seiscat print --max-col-width 24     # Truncate wide columns in pager
seiscat print EVID                   # Print a specific event
seiscat print -w "mag >= 3.0"        # Filter and print
seiscat print --sortby mag -r        # Sort by magnitude (largest first)

Options: --configfile, --where, --allversions, --sortby, --reverse, --format {table,stats}, --max-col-width N.

Interactive Pager

When outputting a table to a terminal, seiscat print displays the catalog using an interactive pager with the following features:

Vertical navigation: Use ↓ to move down, ↑ to move up
Page navigation: Space/f for next page, b for previous page, g for home, G for end
Horizontal scrolling: If the table is wider than your terminal, use ← and → to scroll left and right
Row selection: The first row is highlighted; use arrow keys to move the selection
Event details popup: Press Enter on the selected row to open a popup with all event fields listed line by line
- In the popup, use ↓ for next event and ↑ for previous event
- While moving with ↓/↑, the selected table row behind the popup is updated and auto-scrolled when needed
- Use j/k to scroll inside the popup when details exceed the visible area
- Main table bindings remain active in popup mode: ←/→ (horizontal scroll), c (copy evid), Space/f (page down), b (page up), g (home), G (end)
- Press q, Esc, or Enter to close the popup
Column truncation: Use --max-col-width N to limit the width of each table column in the interactive pager. Longer values are shown with ..., while pressing Enter on a row still reveals the full values in the details popup. Use --max-col-width 0 to disable truncation.
Copy event ID: Press c to copy the event ID (evid) of the currently selected row to the system clipboard. A popup will confirm the copy operation.
Status bar: Shows the number of visible events and total event count
Interactive sorting:
- Press s to open a popup menu to select a column to sort by
- In the sort popup: use ↑/↓ to navigate, 1–9 (or higher for more columns) to quickly select a column, Enter/Space to confirm, or q/Esc to dismiss without sorting
- Press 1–9 to quickly sort by the corresponding column number
- Press 0 to restore the default sort order
- Press the same column again to toggle sort direction (ascending/descending)
- The status bar shows the current sort field and direction (↑ for ascending, ↓ for descending)
Quit: Press q or Esc to exit

To disable the pager and output plain text (useful for piping to a file or other commands), redirect the output:

seiscat print > catalog.txt          # Save to file (no pager)
seiscat print | head -10             # Pipe to another command (no pager)

See also seiscat export for exporting to files in specific formats.

seiscat export

Export the catalog to a file in CSV, GeoJSON, or KML format.

seiscat export catalog.csv           # Export to CSV (format inferred)
seiscat export catalog.json          # Export to GeoJSON
seiscat export catalog.kml           # Export to KML
seiscat export -f csv out.txt        # Explicit format (CSV)
seiscat export -f json data.json     # Explicit format (GeoJSON)
seiscat export -f kml map.kml        # Explicit format (KML)
seiscat export catalog.csv -w "mag >= 3.0"  # Export filtered events
seiscat export catalog.kml -s 8.0    # KML with custom marker size
seiscat export catalog.csv --sortby depth  # Export sorted by depth

Options: --configfile, --where, --allversions, --sortby, --reverse, --format {csv,json,kml} (optional; if omitted, format is inferred from the output file extension), --scale FLOAT (KML only; scale factor for marker size, default: 5.0).

seiscat plot

Plot a catalog map using Cartopy, Folium, or Plotly.

Cartopy and Plotly backends require optional dependencies installed with pip install seiscat[cartopy] or pip install seiscat[plotly].

seiscat plot -b cartopy              # Static map (default)
seiscat plot -b folium               # Interactive leaflet map
seiscat plot -b plotly -t            # Interactive Plotly with time slider
seiscat plot --scale 8               # Marker size scale
seiscat plot --colorby depth         # Color markers by a numeric field
seiscat plot --colorby depth --colormap inferno
seiscat plot --colorby depth --threshold 10
seiscat plot --colorby time --threshold 2026-04-08T12:00:00Z
seiscat plot --sortby mag -r         # Largest magnitudes drawn on top

Options: --configfile, --where, --allversions, --sortby, --reverse, -b/--backend {cartopy,folium,plotly}, --scale FLOAT, --time_slider (Plotly only), --colorby FIELD, --colormap NAME (Matplotlib colormap name; defaults to viridis), --threshold VALUE (Cartopy + --colorby only).

--threshold sets the value above which markers have a black outline. Default is None, meaning all markers have an outline. When used with --colorby time, VALUE can be either epoch seconds or an ISO datetime string (for example, 2026-04-08T12:00:00Z). When defined, the threshold is shown as a horizontal black line on the colorbar.

A list of Matplotlib colormaps is available at this link: Matplotlib colormaps.

seiscat timeline

Plot a timeline of the catalog either as attribute-vs-time scatter or event-count-vs-time histogram.

Backends:

matplotlib: static figure on screen or file
plotly: interactive web figure on screen or HTML file
terminal: text chart of event counts over time

# Attribute vs time (default: magnitude)
seiscat timeline
seiscat timeline -A depth

# Color markers by a second numeric attribute
seiscat timeline -A depth --colorby mag
seiscat timeline -A depth --colorby mag --colormap plasma

# Use time as Y axis and/or colorbar attribute
seiscat timeline -A time
seiscat timeline -A mag --colorby time

# Event count histogram with auto/custom bins
seiscat timeline -C
seiscat timeline -C -B 20
seiscat timeline -C -B 7d
seiscat timeline -C -B 1m

# Cumulative count over raw event times (no bins)
seiscat timeline --cumulative
seiscat timeline -C --cumulative

# Dual-axis: histogram with cumulative overlay
seiscat timeline -C -B 20 --cumulative
seiscat timeline -C -b plotly -B 1w --cumulative

# Backend and output examples
seiscat timeline -A mag -b matplotlib -o timeline.png
seiscat timeline -A mag -b plotly -o timeline.html
seiscat timeline -C -b terminal

Options: --configfile, --where, --allversions, --attribute FIELD (default: mag), --count, --colorby FIELD (attribute mode only), --colormap NAME (attribute mode only; Matplotlib colormap name), -B/--bins SPEC (count mode only), -U/--cumulative (standalone cumulative mode or with --count), --backend {matplotlib,plotly,terminal}, --out-file FILE.

A list of Matplotlib colormaps is available at this link: Matplotlib colormaps.

Bin specification for -B/--bins:

integer N: use N equal-width bins
duration string: Nd (days), Nw (weeks), Nm (months), Ny (years)
omitted: automatic bin width
ignored when --cumulative is used without --count

Cumulative count behavior:

With --cumulative only: plots raw cumulative count over chronological time (no binning)
With --count only: plots histogram of binned event counts
With both --count and --cumulative: shows histogram on left y-axis and cumulative
line from raw chronological events on right y-axis

Time formatting behavior:

If --attribute time is used, Y-axis labels are formatted as time.
If --colorby time is used, colorbar labels are formatted as time.
This applies to both matplotlib and plotly backends.

seiscat get

Get the value of a specific event attribute. If EVID is omitted, values are shown for all selected events.

seiscat get key [EVID] [EVENT_VERSION]

Options: --configfile.

seiscat set

Set the value of a specific event attribute.

seiscat set key value EVID [EVENT_VERSION]

Options: --configfile.

seiscat run

Run a user-defined command for each selected event. All event columns are exposed as environment variables (e.g., $evid, $time). Supports concurrent execution safely against the database.

seiscat run "/path/to/script.sh"              # All selected events
seiscat run "python myproc.py" AA123456        # Only this event
seiscat run "./proc.sh" -w "mag >= 3.0" -r -a
seiscat run "./process.sh" --sortby mag        # Process by magnitude order

Options: --configfile, --where, --allversions, --sortby, --reverse.

seiscat sampleconfig

Write a sample configuration file to the current directory.

seiscat sampleconfig

For a complete description of all configuration options, see Configuration File.

seiscat samplescript

Write a sample script usable with seiscat run.

seiscat samplescript

seiscat logo

Print the SeisCat logo.

seiscat logo

seiscat self

Manage SeisCat self-maintenance tasks (status, updates, completion, uninstall, logo).

seiscat self status
seiscat self update
seiscat self update --git
seiscat self completion status
seiscat self completion install
seiscat self uninstall --yes
seiscat self logo

seiscat self status reports:

installed version, installer backend, and update state
shell completion status
optional plotting module availability for cartopy, plotly, pandas, and folium

Commands

Common options

Filtering with --where

Sorting with --sortby

seiscat initdb

seiscat updatedb

seiscat cropdb

seiscat editdb

seiscat fetchdata

seiscat print

seiscat export

seiscat plot

seiscat timeline

seiscat get

seiscat set

seiscat run

seiscat sampleconfig

seiscat samplescript

seiscat logo

seiscat self

Filtering with `--where`

Sorting with `--sortby`