Watcher CLI
Every data-hub-watcher command, subcommand, and flag in one place: init, watch, upload, config, service, and self-update.
The complete data-hub-watcher command surface. For task-oriented walkthroughs see
Installing a watcher,
Run as a Windows service, and
Upgrading the watcher.
Global flags
These apply to every command:
| Flag | Description |
|---|---|
--config PATH | Override the config file path. Equivalent to the DATA_HUB_CONFIG_PATH env var. |
--verbose | Enable debug-level logging on stderr. |
--version | Print the installed watcher version and exit. |
--help | Show help for the command or subcommand. |
init
Interactive setup wizard. Prompts for environment, API key, instrument, watch
directory, file patterns, run detection, stability period, and upload mode; then
registers the watcher and writes ~/.data-hub/config.yaml and
~/.data-hub/.env.<environment>.
| Flag | Description |
|---|---|
--show-key | Echo the API key as you type/paste it (useful when a terminal mangles hidden input). |
The key is validated (must start with dhub_) and normalized to strip zero-width
and non-breaking-space characters that Windows clipboards inject. See
Installing a watcher → Setup.
watch
Start the file-monitoring loop: detect stable files, group them into runs, report
runs, upload (auto mode) or poll the queue (manual mode), and send heartbeats every
60 seconds. Press Ctrl+C to stop.
| Flag | Description |
|---|---|
--dry-run | Validate config, check API reachability and instrument status, and preview which files would be picked up, without starting the monitor. |
upload
One-shot upload outside the watch loop.
data-hub-watcher upload --file /path/to/file.csv --run-id RUN001 # upload a specific file
data-hub-watcher upload # process the server-side queue (manual mode)
data-hub-watcher upload --dry-run # preview without uploading| Flag | Description |
|---|---|
--file PATH | The file to upload. |
--run-id ID | The run to attach the file to. |
--dry-run | Preview without uploading. |
config
Manage the YAML config. Changes that affect the server are synced automatically.
| Subcommand | Description |
|---|---|
config show | Pretty-print the current config. |
config validate | Validate the config file offline. |
config set-environment ENV | Switch the active environment (staging, production, preview). |
config edit | Re-prompt each field with current values as defaults. |
config open | Open the config in your editor, then re-validate. |
config path | Print the resolved config file path. |
config set-environment (and config edit when the environment changes) accept:
| Flag | Description |
|---|---|
--api-base-url URL | Required when switching to preview. |
--api-key KEY | Otherwise read from the env file or prompted. |
--show-key | Echo the key as entered. |
--no-register | Fail instead of registering a new watcher if none is stored for the target environment. |
See the Configuration reference → Switching environments.
service (Windows only)
Requires the windows-service extra. Manage the watcher as a Windows service.
| Subcommand | Description |
|---|---|
service install | Register the service. |
service uninstall | Remove the service. |
service start | Start the service. |
service stop | Stop the service. |
service status | Show service status. |
service reinstall | Stop, uninstall, install, and start in one go. |
service install and service reinstall accept --env-path PATH to override which
.env file the service loads. Full details in
Run as a Windows service.
self-update
Check the API for a newer published version and upgrade in place.
data-hub-watcher self-update # check + upgrade if needed
data-hub-watcher self-update --check # report status only, no upgrade
data-hub-watcher self-update --force # re-run the upgrade even if versions match| Flag | Description |
|---|---|
--check | Report status only; don't upgrade. |
--force | Re-run the upgrade subprocess even if the installed version already matches. |
The upgrade flow depends on your install method; see Upgrading the watcher.
Architecture
How Data Hub fits together: the watcher, S3 storage, the Lambda processor, the API and web app, and the data flow from instrument to dashboard.
Watcher configuration
Every config.yaml field, the ~/.data-hub file layout, environment variables, run-detection presets, upload modes, and the initial-scan behavior.