HydroSwift CLI Examples¶

Hands-on guide to the HydroSwift CLI (hyswift)

Tip: If hyswift is not found on your PATH, use the module form instead:

python -m hydroswift <flags>

---

Table of Contents¶

1. Installation Check & Help
2. Utility Commands
3. General Usage
4. WRIS Data : Single Variable Downloads
5. WRIS Data : Multiple Variables
6. WRIS Data : Available Variables
7. Date Range Control
8. Output Format & Directory Control
9. Inline Plotting during Download
10. Merge-Only Mode (Post-Processing)
11. Plot-Only Mode (Post-Processing)
12. CWC Data : Water Level Downloads
13. CWC Data : For selected Stations
14. CWC Data with a Basin Filter
15. CWC Data : Multiple Basins & Stations Intersection
16. CWC Station Metadata Refresh
17. Full Download Example
18. Quick Reference Table
19. Troubleshooting & Common Mistakes

1. Installation Check & Help¶

Verify that hyswift is available and view the full help text. Read Installation.md for instructions on how to install hydroswift CLI

In [1]:

!hyswift --version

!hyswift --version

HydroSwift 1.0.0

The alternative if the console script is not on the PATH:

In [2]:

!python -m hydroswift --version

!python -m hydroswift --version

HydroSwift 1.0.0

In [3]:

!hyswift -h

!hyswift -h

usage: hyswift [-h] [--version] [-b BASIN] [--cwc]
               [--cwc-station CWC_STATION [CWC_STATION ...]]
               [--cwc-basin CWC_BASIN_FILTER [CWC_BASIN_FILTER ...]]
               [--cwc-refresh] [-q] [-wl] [-atm] [-rf] [-temp] [-rh] [-solar]
               [-sed] [-gwl] [--overwrite] [--merge] [--merge-only]
               [--delay DELAY] [--start-date START_DATE] [--end-date END_DATE]
               [--metadata] [--input-dir INPUT_DIR] [--plot] [--plot-svg]
               [--plot-moving-average-window PLOT_MOVING_AVERAGE_WINDOW]
               [--plot-only] [--output-dir OUTPUT_DIR] [--format {csv,xlsx}]
               [--quiet] [--list] [--cite] [--coffee]

HydroSwift - Fast, unified workflows for hydrological data

Download hydrological datasets from India-WRIS and CWC.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

Source selection:
  -b, --basin BASIN     WRIS basin name or number:
                          [1] Brahmani and Baitarni
                          [2] Cauvery
                          [3] East flowing rivers between Mahanadi and Pennar
                          [4] East flowing rivers between Pennar and Kanyakumari
                          [5] Godavari
                          [6] Krishna
                          [7] Mahanadi
                          [8] Mahi
                          [9] Minor rivers draining into Myanmar and Bangladesh
                          [10] Narmada
                          [11] Pennar
                          [12] Sabarmati
                          [13] Subernarekha
                          [14] Tapi
                          [15] West flowing rivers from Tadri to Kanyakumari
                          [16] West flowing rivers from Tapi to Tadri
                          [17] West flowing rivers of Kutch and Saurashtra including Luni
  --cwc                 Use CWC source (Python equivalent: hydroswift.cwc.download(...))
  --cwc-station, --station CWC_STATION [CWC_STATION ...]
                        CWC station code(s) (Python equivalent: station=[...])
  --cwc-basin CWC_BASIN_FILTER [CWC_BASIN_FILTER ...]
                        CWC basin filter(s) (Python equivalent: basin=[...])
  --cwc-refresh         Refresh CWC station metadata from the live API before download.

WRIS variables:
  -q, --discharge       Discharge
  -wl, --water-level    Water level
  -atm, --atm-pressure  Atmospheric pressure
  -rf, --rainfall       Rainfall
  -temp, --temperature  Temperature
  -rh, --humidity       Relative humidity
  -solar, --solar-radiation
                        Solar radiation
  -sed, --sediment      Suspended sediment
  -gwl, --groundwater-level
                        Groundwater level

Download behavior:
  --overwrite           Overwrite existing files
  --merge               Merge station files into GeoPackages
  --merge-only          Only merge existing output (Python equivalent: hydroswift.merge_only(...))
  --delay DELAY         Delay between WRIS API requests (seconds)
  --start-date START_DATE
                        Start date (YYYY-MM-DD)
  --end-date END_DATE   End date (YYYY-MM-DD)

Output options:
  --metadata            Save station metadata as CSV
  --input-dir INPUT_DIR
                        Input directory for --merge-only / --plot-only
  --plot                Generate plots after download
  --plot-svg            Also export publication-ready SVG files when plotting
  --plot-moving-average-window PLOT_MOVING_AVERAGE_WINDOW
                        Optional moving-average window (number of samples) overlay for plots
  --plot-only           Generate plots from existing output
  --output-dir OUTPUT_DIR
                        Output directory (default: output)
  --format {csv,xlsx}   Output file format

Misc:
  --quiet               Suppress console output
  --list                List available WRIS basins and CWC station count
  --cite                Show citation information
  --coffee              Take a virtual coffee break ☕

2. Utility Commands¶

2a. List available basins and CWC station count¶

In [4]:

!hyswift --list

!hyswift --list

Available WRIS Basins:
  [1] Brahmani and Baitarni
  [2] Cauvery
  [3] East flowing rivers between Mahanadi and Pennar
  [4] East flowing rivers between Pennar and Kanyakumari
  [5] Godavari
  [6] Krishna
  [7] Mahanadi
  [8] Mahi
  [9] Minor rivers draining into Myanmar and Bangladesh
  [10] Narmada
  [11] Pennar
  [12] Sabarmati
  [13] Subernarekha
  [14] Tapi
  [15] West flowing rivers from Tadri to Kanyakumari
  [16] West flowing rivers from Tapi to Tadri
  [17] West flowing rivers of Kutch and Saurashtra including Luni

CWC Stations:
  Total known stations: 1284
  Tip: use --cwc-station <CODE1 CODE2 ...> to download selected stations

2b. Citation information¶

Use this to get the recommended citation when using HydroSwift in research or reports.

In [ ]:

# !hyswift --cite

# !hyswift --cite

2c. Coffee break 🍵¶

In [6]:

!hyswift --coffee

!hyswift --coffee

      ( (
       ) )
    ........
    |      |]
    \      /
     `----'
     TIME FOR A COFFEE BREAK

3. General Usage¶

hyswift  <source-selection>  <dataset-flags>  [options]

Component	WRIS	CWC
Source selection	-b / --basin	--cwc, --cwc-station, --cwc-basin
Dataset selection	-q, -rf, -temp, etc.	(water level only — always implied)
Date range	--start-date, --end-date	same
Output options	--output-dir, --format, --overwrite	same
Post-processing	--plot, --merge	same

A minimal WRIS command looks like:

hyswift -b Godavari -q
#       ^basin      ^discharge flag

4. WRIS Data : Single Variable Downloads¶

You must provide -b/--basin and at least one dataset flag. Basin can be a name or a WRIS numeric ID.

Download discharge for Godavari (using basin name)¶

In [ ]:

!hyswift -b Godavari -q

!hyswift -b Godavari -q

Python API equivalent:

hydroswift.wris.download(basin='Godavari', variable='discharge')

Download discharge using the WRIS numeric basin ID (Godavari = 5)¶

In [ ]:

!hyswift -b 5 -q

!hyswift -b 5 -q

Python API equivalent:

hydroswift.wris.download(basin=5, variable='discharge')

Download sediment data for Krishna¶

In [ ]:

!hyswift -b Krishna -sed

!hyswift -b Krishna -sed

Python API equivalent:

hydroswift.wris.download(basin='Krishna', variable='sediment')

Download groundwater level for Narmada¶

In [ ]:

!hyswift -b Narmada --groundwater-level

!hyswift -b Narmada --groundwater-level

Python API equivalent:

hydroswift.wris.download(basin='Narmada', variable='groundwater_level')

5. WRIS Data : Multiple Variables¶

Stack multiple dataset flags to download several variables in one command.

Discharge + Rainfall + Temperature for Krishna¶

In [ ]:

!hyswift -b Krishna -q -rf -temp

!hyswift -b Krishna -q -rf -temp

Python API equivalent:

hydroswift.wris.download(basin='Krishna', variable=['discharge', 'rainfall', 'temperature'])

Water level + Sediment for Godavari (long flag style)¶

In [ ]:

!hyswift -b Godavari --water-level --sediment

!hyswift -b Godavari --water-level --sediment

Python API equivalent:

hydroswift.wris.download(basin='Godavari', variable=['water_level', 'sediment'])

Multiple variables for multiple basins¶

The CLI handles one basin per command. For multi-basin downloads, use the Python API's wris.download(basin=[...]).

In [ ]:

# Basin 5 (Godavari) — discharge + solar
!hyswift -b 5 -q -solar

# Basin 6 (Krishna) — discharge + rainfall
!hyswift -b 6 -q -rf

# Basin 5 (Godavari) — discharge + solar !hyswift -b 5 -q -solar # Basin 6 (Krishna) — discharge + rainfall !hyswift -b 6 -q -rf

Note: For multi-basin workflows, the Python API is more ergonomic:

hydroswift.wris.download(basin=['Godavari', 'Krishna'], variable=['discharge', 'rainfall'])

6. WRIS Data : Available Variables¶

WRIS dataset flags supported by the CLI for downloading and processing time series data:

Short flag	Long flag	Variable
-q	--discharge	Discharge
-wl	--water-level	Water Level
-atm	--atm-pressure	Atmospheric Pressure
-rf	--rainfall	Rainfall
-temp	--temperature	Temperature
-rh	--humidity	Relative Humidity
-solar	--solar-radiation	Solar Radiation
-sed	--sediment	Sediment
-gwl	--groundwater-level	Groundwater Level

Short and long forms are interchangeable:

In [ ]:

# These two commands are identical:
# !hyswift -b Godavari -q -rf
# !hyswift -b Godavari --discharge --rainfall

!hyswift -b Godavari --discharge --rainfall

# These two commands are identical: # !hyswift -b Godavari -q -rf # !hyswift -b Godavari --discharge --rainfall !hyswift -b Godavari --discharge --rainfall

7. Date Range Control¶

Use --start-date and --end-date in YYYY-MM-DD format. If omitted, HydroSwift uses 1950-01-01 as the start date and today as the end date.

Download discharge for Krishna between 2020 and 2022¶

In [ ]:

!hyswift -b 6 -q --start-date 2020-01-01 --end-date 2022-12-31

!hyswift -b 6 -q --start-date 2020-01-01 --end-date 2022-12-31

Python API equivalent:

hydroswift.wris.download(basin=6, variable='discharge', start_date='2020-01-01', end_date='2022-12-31')

Download recent 1-year rainfall for Godavari¶

In [ ]:

!hyswift -b Godavari -rf --start-date 2024-01-01 --end-date 2024-12-31

!hyswift -b Godavari -rf --start-date 2024-01-01 --end-date 2024-12-31

Python API equivalent:

hydroswift.wris.download(basin='Godavari', variable='rainfall', start_date='2024-01-01', end_date='2024-12-31')

CWC download with date range¶

In [ ]:

!hyswift --cwc-basin Krishna --start-date 2024-04-01 --end-date 2024-06-30

!hyswift --cwc-basin Krishna --start-date 2024-04-01 --end-date 2024-06-30

Python API equivalent:

hydroswift.cwc.download(basin=['Krishna'], start_date='2024-04-01', end_date='2024-06-30')

8. Output Format & Directory Control¶

Control where files are saved and in which format (csv or xlsx).

Save to a custom directory in CSV format¶

In [ ]:

!hyswift -b 5 -q --output-dir data/wris_output --format csv

!hyswift -b 5 -q --output-dir data/wris_output --format csv

Python API equivalent:

hydroswift.wris.download(basin=5, variable='discharge', output_dir='data/wris_output', format='csv')

Save as Excel (.xlsx) and overwrite existing files¶

In [ ]:

!hyswift -b Krishna -q -rf --format xlsx --overwrite --output-dir data/krishna

!hyswift -b Krishna -q -rf --format xlsx --overwrite --output-dir data/krishna

Python API equivalent:

hydroswift.wris.download(basin='Krishna', variable=['discharge', 'rainfall'],
                         format='xlsx', overwrite=True, output_dir='data/krishna')

Download quietly (suppress log output)¶

In [ ]:

!hyswift -b Godavari -q --quiet --output-dir data/quiet_run

!hyswift -b Godavari -q --quiet --output-dir data/quiet_run

Python API equivalent:

hydroswift.wris.download(basin='Godavari', variable='discharge', quiet=True, output_dir='data/quiet_run')

Retrieve station metadata alongside download¶

In [ ]:

!hyswift -b Krishna -q --metadata --output-dir data/with_metadata

!hyswift -b Krishna -q --metadata --output-dir data/with_metadata

9. Inline Plotting during Download¶

Add --plot to generate PNG time-series plots alongside the download. Use --plot-svg for SVG output. The --plot-moving-average-window N flag adds a moving-average overlay.

Download and plot discharge¶

In [ ]:

!hyswift -b 5 -q --plot --output-dir data/plotted

!hyswift -b 5 -q --plot --output-dir data/plotted

Python API equivalent:

hydroswift.wris.download(basin=5, variable='discharge', plot=True, output_dir='data/plotted')

Download, plot as SVG, and add 30-day moving average¶

In [ ]:

!hyswift -b Krishna -q -rf --plot --plot-svg --plot-moving-average-window 30 --output-dir data/krishna_plots

!hyswift -b Krishna -q -rf --plot --plot-svg --plot-moving-average-window 30 --output-dir data/krishna_plots

Python API equivalent:

hydroswift.wris.download(basin='Krishna', variable=['discharge', 'rainfall'],
                         plot=True, output_dir='data/krishna_plots')
# (SVG + moving average are available via plot_only() post-processing)

10. Merge-Only Mode (Post-Processing)¶

--merge-only reads previously downloaded CSV/XLSX files from --input-dir and generates a merged GeoPackage (.gpkg) without re-downloading anything.

⚠️ Requires --input-dir pointing to a folder containing existing HydroSwift outputs.

Merge WRIS outputs from a previous download¶

In [ ]:

!hyswift --merge-only --input-dir output

!hyswift --merge-only --input-dir output

Python API equivalent:

hydroswift.merge_only(input_dir='output')

Merge with a custom output directory¶

In [ ]:

!hyswift --merge-only --input-dir data/wris_output --output-dir data/merged

!hyswift --merge-only --input-dir data/wris_output --output-dir data/merged

Python API equivalent:

hydroswift.merge_only(input_dir='data/wris_output', output_dir='data/merged')

Download without merging, then merge separately¶

In [ ]:

# Step 1 — download only (no merge)
!hyswift -b Godavari -q -sed --output-dir data/godavari_raw

# Step 1 — download only (no merge) !hyswift -b Godavari -q -sed --output-dir data/godavari_raw

In [ ]:

# Step 2 — merge the saved files into a GeoPackage
!hyswift --merge-only --input-dir data/godavari_raw --output-dir data/godavari_merged

# Step 2 — merge the saved files into a GeoPackage !hyswift --merge-only --input-dir data/godavari_raw --output-dir data/godavari_merged

Python API equivalent (step 2):

hydroswift.merge_only(mode='wris', input_dir='data/godavari_raw', output_dir='data/godavari_merged')

11. Plot-Only Mode (Post-Processing)¶

--plot-only reads existing files from --input-dir and generates time-series plots without re-downloading. This is useful when you disabled --plot during download.

Generate plots from an existing output directory¶

In [ ]:

!hyswift --plot-only --input-dir output

!hyswift --plot-only --input-dir output

Python API equivalent:

hydroswift.plot_only(input_dir='output')

Plot as SVG with a 30-day moving average window¶

In [ ]:

!hyswift --plot-only --input-dir output --plot-svg --plot-moving-average-window 30

!hyswift --plot-only --input-dir output --plot-svg --plot-moving-average-window 30

Python API equivalent:

hydroswift.plot_only(mode='wris', input_dir='output', plot_svg=True, moving_average=True, window=30)

Plot-only for CWC data¶

In [ ]:

!hyswift --plot-only --input-dir data/cwc_output --output-dir data/cwc_plots

!hyswift --plot-only --input-dir data/cwc_output --output-dir data/cwc_plots

Python API equivalent:

hydroswift.plot_only(mode='cwc', input_dir='data/cwc_output', output_dir='data/cwc_plots')

12. CWC Data : Water Level Downloads¶

CWC provides near real-time water level data at gauge stations. CWC mode does not support multi-variable WRIS-style flags as water level only valid variable.

Enter CWC mode with any of:

• --cwc interactive / default CWC download
• --cwc-station CODE [CODE ...]
• --station CODE [CODE ...] (alias)
• --cwc-basin NAME [NAME ...]

Trigger a general CWC download¶

In [ ]:

!hyswift --cwc

!hyswift --cwc

Python API equivalent:

hydroswift.cwc.download()

13. CWC Data : For selected Stations¶

Target individual gauge stations by their CWC station code (e.g., 040-CDJAPR).

Download water level for a single CWC station¶

In [ ]:

!hyswift --cwc-station 032-LGDHYD

!hyswift --cwc-station 032-LGDHYD

Python API equivalent:

hydroswift.cwc.download(station=['032-LGDHYD'])

Download water level for multiple CWC stations¶

In [ ]:

!hyswift --cwc-station 040-CDJAPR 032-LGDHYD

!hyswift --cwc-station 040-CDJAPR 032-LGDHYD

Python API equivalent:

hydroswift.cwc.download(station=['040-CDJAPR', '032-LGDHYD'])

Using the --station alias¶

In [ ]:

!hyswift --station 040-CDJAPR 032-LGDHYD

!hyswift --station 040-CDJAPR 032-LGDHYD

Both --station and --cwc-station are identical — --station is just a shorter alias.

CWC station download with date range and custom output¶

In [ ]:

!hyswift --cwc-station 032-LGDHYD --start-date 2024-01-01 --end-date 2024-06-30 --output-dir data/cwc_station

!hyswift --cwc-station 032-LGDHYD --start-date 2024-01-01 --end-date 2024-06-30 --output-dir data/cwc_station

Python API equivalent:

hydroswift.cwc.download(station=['032-LGDHYD'], start_date='2024-01-01',
                        end_date='2024-06-30', output_dir='data/cwc_station')

14. CWC Data with a Basin Filter¶

Use --cwc-basin to download all CWC gauge stations within a river basin.

Download water level for all CWC stations in Krishna basin¶

In [ ]:

!hyswift --cwc-basin Krishna

!hyswift --cwc-basin Krishna

Python API equivalent:

hydroswift.cwc.download(basin=['Krishna'])

Download water level for all CWC stations in Godavari basin, save as Excel¶

In [ ]:

!hyswift --cwc-basin Godavari --format xlsx --output-dir data/godavari_cwc

!hyswift --cwc-basin Godavari --format xlsx --output-dir data/godavari_cwc

Python API equivalent:

hydroswift.cwc.download(basin=['Godavari'], format='xlsx', output_dir='data/godavari_cwc')

15. CWC Data : Multiple Basins & Stations Intersection¶

You can pass multiple basin names to --cwc-basin. If both --cwc-basin and --cwc-station are provided, HydroSwift downloads only stations that appear in both.

Multiple CWC basins¶

In [ ]:

!hyswift --cwc-basin Krishna Godavari

!hyswift --cwc-basin Krishna Godavari

Python API equivalent:

hydroswift.cwc.download(basin=['Krishna', 'Godavari'])

Intersection: basin filter + specific station¶

In [ ]:

!hyswift --cwc-basin Krishna --station 032-LGDHYD

!hyswift --cwc-basin Krishna --station 032-LGDHYD

This downloads data for 032-LGDHYD only if it belongs to the Krishna basin.

Python API equivalent:

hydroswift.cwc.download(basin=['Krishna'], station=['032-LGDHYD'])

16. CWC Station Metadata Refresh¶

HydroSwift ships a packaged metadata file for CWC stations. Use --cwc-refresh to re-fetch the latest station list from the live CWC API before downloading.

In [ ]:

!hyswift --cwc-basin Narmada --cwc-refresh

!hyswift --cwc-basin Narmada --cwc-refresh

Python API equivalent:

hydroswift.cwc.download(basin=['Narmada'], refresh=True)

17. Full Download Example¶

Combine download + plot + merge in a single command, or chain CLI commands for a complete end-to-end pipeline.

WRIS download + merge + plot in one command¶

In [ ]:

!hyswift -b Krishna -q -rf -temp --start-date 2022-01-01 --end-date 2024-12-31 --output-dir data/krishna_full --format csv --overwrite --merge --plot

!hyswift -b Krishna -q -rf -temp --start-date 2022-01-01 --end-date 2024-12-31 --output-dir data/krishna_full --format csv --overwrite --merge --plot

Python API equivalent:

hydroswift.wris.download(
    basin='Krishna',
    variable=['discharge', 'rainfall', 'temperature'],
    start_date='2022-01-01',
    end_date='2024-12-31',
    output_dir='data/krishna_full',
    format='csv',
    overwrite=True,
    merge=True,
    plot=True,
)

CWC download + merge + plot¶

In [ ]:

!hyswift --cwc-basin Godavari --start-date 2024-01-01 --end-date 2024-06-30 --output-dir data/cwc_pipeline --merge --plot --format csv --overwrite

!hyswift --cwc-basin Godavari --start-date 2024-01-01 --end-date 2024-06-30 --output-dir data/cwc_pipeline --merge --plot --format csv --overwrite

Python API equivalent:

hydroswift.cwc.download(
    basin=['Godavari'],
    start_date='2024-01-01',
    end_date='2024-06-30',
    output_dir='data/cwc_pipeline',
    merge=True,
    plot=True,
    format='csv',
    overwrite=True,
)

Chaining using shell commands (separate download → merge → plot)¶

In [ ]:

# Step 1: Download without merging or plotting
!hyswift -b Narmada -q -wl --start-date 2023-01-01 --end-date 2023-12-31 --output-dir data/narmada_raw --quiet

# Step 1: Download without merging or plotting !hyswift -b Narmada -q -wl --start-date 2023-01-01 --end-date 2023-12-31 --output-dir data/narmada_raw --quiet

In [ ]:

# Step 2: Merge downloaded files into a GeoPackage
!hyswift --merge-only --input-dir data/narmada_raw --output-dir data/narmada_merged

# Step 2: Merge downloaded files into a GeoPackage !hyswift --merge-only --input-dir data/narmada_raw --output-dir data/narmada_merged

In [ ]:

# Step 3: Plot with SVG + 7-day moving average
!hyswift --plot-only --input-dir data/narmada_raw --output-dir data/narmada_plots --plot-svg --plot-moving-average-window 7

# Step 3: Plot with SVG + 7-day moving average !hyswift --plot-only --input-dir data/narmada_raw --output-dir data/narmada_plots --plot-svg --plot-moving-average-window 7

18. Quick Reference Table¶

Task	CLI Command	Python API
Check version	hyswift --version	hydroswift.__version__
Show help	hyswift -h	hydroswift.cli_help()
List basins	hyswift --list	hydroswift.wris.basins()
Cite HydroSwift	hyswift --cite	hydroswift.cite()
Coffee	hyswift --coffee	hydroswift.coffee()
Download WRIS discharge	hyswift -b Godavari -q	hydroswift.wris.download(basin='Godavari', variable='discharge')
Download multiple WRIS vars	hyswift -b Krishna -q -rf -temp	hydroswift.wris.download(basin='Krishna', variable=['discharge','rainfall','temperature'])
Set date range	hyswift -b 6 -q --start-date 2020-01-01 --end-date 2022-01-01	wris.download(basin=6, variable='discharge', start_date=..., end_date=...)
Custom output dir + format	hyswift -b 5 -q --output-dir out --format xlsx	wris.download(..., output_dir='out', format='xlsx')
Overwrite files	hyswift -b 5 -q --overwrite	wris.download(..., overwrite=True)
Suppress logs	hyswift -b 5 -q --quiet	wris.download(..., quiet=True)
Download + plot inline	hyswift -b 5 -q --plot	wris.download(..., plot=True)
Download + merge inline	hyswift -b 5 -q --merge	wris.download(..., merge=True)
Merge existing files	hyswift --merge-only --input-dir output	hydroswift.merge_only(input_dir='output')
Plot existing files	hyswift --plot-only --input-dir output	hydroswift.plot_only(input_dir='output')
Plot SVG + moving avg	hyswift --plot-only --input-dir out --plot-svg --plot-moving-average-window 30	hydroswift.plot_only(..., plot_svg=True, window=30)
CWC all stations in basin	hyswift --cwc-basin Krishna	hydroswift.cwc.download(basin=['Krishna'])
CWC specific station	hyswift --cwc-station 032-LGDHYD	hydroswift.cwc.download(station=['032-LGDHYD'])
CWC multiple basins	hyswift --cwc-basin Krishna Godavari	hydroswift.cwc.download(basin=['Krishna', 'Godavari'])
CWC refresh metadata	hyswift --cwc-basin Narmada --cwc-refresh	hydroswift.cwc.download(basin=['Narmada'], refresh=True)
Discover WRIS stations	(not directly available as a table)	hydroswift.wris.stations(basin=..., variable=...)
Table-driven download	(not available in CLI)	hydroswift.fetch(table, ...)

19. Troubleshooting & Common Mistakes¶

❌ hyswift not found¶

The console script may not be on your PATH. Use the module form:

python -m hydroswift <flags>

In [ ]:

!python -m hydroswift -h

!python -m hydroswift -h

❌ 'No dataset selected' in WRIS mode¶

You must provide at least one WRIS dataset flag alongside -b:

# WRONG — no dataset flag
hyswift -b Godavari

# CORRECT
hyswift -b Godavari -q

❌ --merge-only or --plot-only fails with 'No input'¶

These post-processing modes require --input-dir pointing to a directory that already contains HydroSwift output files:

# WRONG
hyswift --merge-only

# CORRECT
hyswift --merge-only --input-dir output

❌ Mixing WRIS variable flags with CWC mode¶

CWC mode only supports water level. Do not add WRIS flags like -q or -rf to CWC commands:

# WRONG — mixing WRIS dataset flags into a CWC command
hyswift --cwc-basin Krishna -q

# CORRECT — CWC is water level only
hyswift --cwc-basin Krishna

❌ Want table-driven or multi-basin workflows from the CLI¶

The CLI does not expose the hydroswift.fetch(table) or multi-basin wris.download(basin=[...]) pattern as a single command. For those workflows, use the Python API instead:

import hydroswift
stations = hydroswift.wris.stations(basin=['Godavari', 'Krishna'], variable='discharge')
hydroswift.fetch(stations, output_dir='output', start_date='2024-01-01', merge=True)

---

📚 Also see..¶

• CLI_USAGE_GUIDE.md — complete flag reference
• PUBLIC_API_AND_CLI.md — API ↔ CLI mapping table
• PYTHON_API_GUIDE.md — full Python API documentation
• hydroswift_python_examples.ipynb — Python API notebook