Docs / CLI reference

CLI reference.

The installer ships a single binary. Both datasus and datasus-etl resolve to the same entry point — use whichever you prefer.

Global flags

Available on every subcommand:

--help       Show help and exit
--version    Print version and exit
-y, --yes    Skip interactive confirmations (legacy migration, overwrites)

datasus pipeline

End-to-end: download → convert → transform → export.

datasus pipeline \
  --source sihsus \
  --start-date 2023-01-01 \
  --end-date   2023-12-31 \
  --uf SP,RJ,MG \
  --data-dir ./data

Required

-s, --source — subsystem id (sihsus or sim).
--start-date — ISO date. Earliest month to include (inclusive).

Common options

--end-date — ISO date, defaults to today.
--uf — comma-separated state codes. Omit for all states.
-d, --data-dir — base directory. Resolves to <dir>/datasus_db/<subsystem>/.

datasus update

Same flags as pipeline, but only downloads files newer than what is already on disk. Useful for cron jobs.

datasus status

Reports what is already downloaded and processed, per UF and per month.

datasus status -s sihsus -d ./data

datasus db

Opens the DuckDB interactive shell connected to the parquet store. All tables and views are pre-registered — type .tables to list.

datasus ui

Starts the local web interface at http://127.0.0.1:8787 and opens your default browser.

datasus ui                              # default
datasus ui --port 8080 --no-open        # custom port, no browser
datasus ui --host 0.0.0.0               # expose on LAN (careful!)

Exit codes

0 — success.
1 — generic error (network, filesystem, parse).
2 — user-facing failure in the folder-picker subprocess (no tkinter).
130 — interrupted by Ctrl+C.