bomshell 3.0.1

Installation

Using uv (recommended):

$ uv tool install bomshell

Using pip:

$ pip install bomshell

Config

bomshell is configured using CLI options and a .bomshell settings file. To see the valid knobs that can be tuned use the knobs command:

$ bomshell knobs

To create a fresh .bomshell config file:

$ bomshell knobs > ~/.bomshell

Initial Setup

Fetch the spatial data (shapefiles) from BOM:

$ bomshell spatial fetch

This downloads all shapefile components (.dbf, .shp, .shx, .prj) to ~/.cache/bomshell/spatial_cache/.

Build the local SQLite database (optional, for database queries):

$ bomshell spatial build

Interactive Maps

Generate interactive HTML maps of BOM spatial data. Maps open automatically in your browser.

Point data (markers on map):

# Radar locations across Australia
$ bomshell spatial map -s radar_location

# All 1,475 weather observation points
$ bomshell spatial map -s point_places

# Radar coverage areas
$ bomshell spatial map -s radar_coverage

Polygon data (district/zone boundaries with hover highlighting):

# Weather forecast districts
$ bomshell spatial map -s forecast_districts

# Fire weather districts
$ bomshell spatial map -s fire_districts

# Marine forecast zones
$ bomshell spatial map -s marine_zones

# Rainfall districts
$ bomshell spatial map -s rainfall_districts

# Metropolitan areas
$ bomshell spatial map -s metros

# Tropical cyclone warning areas
$ bomshell spatial map -s cyclone_areas

# High seas forecast areas
$ bomshell spatial map -s high_sea_areas

# Ocean wind warning areas
$ bomshell spatial map -s ocean_wind_warning

Combined maps (multiple layers with toggle control):

# Radar locations over forecast districts
$ bomshell spatial map -s forecast_districts -s radar_location

# Fire districts with weather stations
$ bomshell spatial map -s fire_districts -s point_places

# Multiple polygon layers
$ bomshell spatial map -s forecast_districts -s marine_zones -s radar_location

Combined maps include a layer control (top-right) to toggle each layer on/off.

Map options:

# Save to custom location
$ bomshell spatial map -s radar_location -o ~/maps/radars.html

# Don't open browser automatically
$ bomshell spatial map -s forecast_districts --no-open

Maps are saved to ~/.cache/bomshell/ by default.

Data Export

Export spatial data to tables or CSV:

# View as formatted table
$ bomshell spatial tabledump -s radar_coverage -f fancy_grid

# Export to CSV
$ bomshell spatial csvdump -s point_places > places.csv

Available table formats: fancy_grid, grid, html, jira, latex, pipe, plain, psql, rst, simple, tsv, and more.

Sample Usage

All bomshell command line options are available from the --help option:

$ bomshell --help
Usage: bomshell [OPTIONS] COMMAND [ARGS]...

  Retrieve weather data from the Australian Bureau of Meteorology

Options:
  --version              Show the version and exit.
  -v, --verbose          Level of verbosity of logs
  -c, --cache-path PATH  BOM data cache path
  --help                 Show this message and exit.

Commands:
  knobs    Print all known settings and their current defaults
  spatial  Spatial database management

$ bomshell spatial --help
Usage: bomshell spatial [OPTIONS] COMMAND [ARGS]...

  Spatial database management

Options:
  -o, --overwrite / --no-overwrite
                                  Overwrite existing spatial data
  --ftp-timeout INTEGER           FTP Timeout in seconds
  --help                          Show this message and exit.

Commands:
  build      Build the local spatial database
  csvdump    Dump spatial data to csv
  fetch      Fetch spatial data
  map        Generate an interactive map of spatial data
  sync       Sync the local spatial data, overwriting existing files
  tabledump  Dump spatial data to table

Available Spatial Types

Development

# Clone and install
$ git clone https://github.com/sthysel/bomshell
$ cd bomshell
$ uv sync --all-extras

# Run tests
$ just test

# Run linting
$ just lint

# See all available commands
$ just