CLI reference | DLH.io Documentation

Every command line flag of dlh_agent_sql_server.exe: the normal run, --diagnose, --config-check, --clear-credentials-cache, --install-driver and --version, with exit codes and sample output.

The agent is a single executable. Run it with no arguments to perform a synchronization run; add one of the flags below for maintenance and diagnostics. All flags work identically from the EXE and from a source checkout (python dlh_agent_sql_server.py <flag>).

cd "C:\Program Files\DLH\dlh-agent-sql-server"
.\dlh_agent_sql_server.exe                              # synchronization run
.\dlh_agent_sql_server.exe --diagnose                   # read-only health check
.\dlh_agent_sql_server.exe --diagnose --json            # same, machine-readable
.\dlh_agent_sql_server.exe --config-check               # compare YAML to current template
.\dlh_agent_sql_server.exe --clear-credentials-cache    # force a live bootstrap next run
.\dlh_agent_sql_server.exe --install-driver             # ODBC driver instructions
.\dlh_agent_sql_server.exe --version

Flag	Purpose	Touches state or data?
(none)	Full synchronization run using `dlh_agent_config.yaml` next to the EXE	Yes: extracts, writes, advances CT/CDC pointers, uploads, notifies
`--diagnose [--json] [--offline] [--config PATH]`	Read-only health check of host, configuration, state store and connectivity	No
`--config-check [--config PATH]`	Compare the configuration file against the current template	No
`--clear-credentials-cache`	Delete the local encrypted bootstrap cache	Deletes the cache only
`--install-driver [--auto]`	Show or perform the Microsoft ODBC Driver for SQL Server installation	Installs a system driver with `--auto`
`--version`, `-v`	Print agent version, Python version and platform	No

Configuration file location

A synchronization run always reads dlh_agent_config.yaml from the directory containing the executable, so Task Scheduler and RMM jobs must set the working directory (or call the EXE by absolute path from its own folder). --config PATH is accepted by --diagnose and --config-check only, to inspect a file that is not yet in place.

Synchronization run

With no flags the agent executes the full pipeline: banner and version, configuration load and validation, credential decryption and platform bootstrap, tier banner, state store telemetry, preflight checks, per-table extraction and writes, uploads, run summary, lifecycle actions, log shipping and run report. The process exit code is 0 when the run completed (even with table-level errors, which are reported through notifications and the run report) and non-zero on a fatal error.

The run log is written to logs\dlh_agent_<YYYYMMDD>_<run id>.log and, when a log store is available, shipped to object storage. See Monitoring and logs for how to read it.

--diagnose

A health check a customer or RMM job can run at any time, including while a scheduled run is in progress. It never extracts data, never moves CT/CDC pointers, never writes to the destination, never sends notifications or run reports and never rewrites the YAML files.

================================================================
  DLH.io AGENT DIAGNOSTICS (read-only)
================================================================

================================================================
  SYSTEM
================================================================
  [PASS] Python runtime: Python 3.12.4 on Windows-10-10.0.20348
  [PASS] System memory: 15.9 GB total, 9.8 GB available (max_memory_percent 85)
  [PASS] Disk: state db: 212.4 GB free on C:\
  [PASS] Disk: output: 212.4 GB free on C:\
  [WARN] Disk: temp: 1.6 GB free on D:\. Below 2.0 GB; free space soon.

================================================================
  CONFIGURATION
================================================================
  [PASS] Config file: 'dlh_agent_config.yaml' parsed.
  [PASS] Config schema: Configuration validated against schema.
  [PASS] Credentials file: 'dlh_sql_server_credentials.yaml' parsed (username set).
  [PASS] Encrypted password (.sec): 'dlh_sql_server_credentials.sec' present.
  [PASS] Encryption key: 'dlh_agent_secret.key' present.
  [PASS] DLH API key: dlh_ref.api_key present (encrypted).
  [PASS] Output format (delta) dependencies: Required packages installed.

================================================================
  STATE STORE (DuckDB) - opened read-only
================================================================
  [PASS] State database (DuckDB): 'dlh_agent_state.duckdb' 48.2 MB, 312 table(s) tracked
  [PASS] Last successful run: 1788202802 at 2026-08-31 15:07:16
  [WARN] Tables with failed last run: 1 (SalesDb.dbo.Location)
  [WARN] Pending schema drift: 1 table(s) recorded for remediation on the next run

================================================================
  CONNECTIVITY (SQL Server, DLH platform, storage)
================================================================
  [PASS] Password decryption: Encrypted SQL Server password decrypted in memory.
  [PASS] ODBC driver: ODBC Driver 18 for SQL Server
  [PASS] SQL Server connectivity: sql01.corp.local:1433 (SalesDb, HrDb)
  [PASS] Change tracking: enabled on SalesDb (retention 2 days)
  [PASS] DLH platform bootstrap: CUSTOMER tier, storage AZURE_BLOB (sales-raw)
  [PASS] Storage access: container reachable
  [PASS] Webhook notifications: 1 of 1 webhook(s) resolvable (URLs not shown).

================================================================
  SUMMARY
================================================================
  ...
  ----------------------------------------------------------------
  21 passed, 3 warning(s), 0 failure(s)
  RESULT: PASS with warnings - review the [WARN] items above.

Output above is illustrative; check names and wording vary with your configuration (for example CDC instead of Change tracking, S3 instead of Azure, no state store section on a fresh install).

Status	Meaning
`PASS`	Check succeeded.
`WARN`	Not fatal for the next run but needs attention (low disk, failed tables, pending drift, unresolved webhook variable, cache-only bootstrap).
`FAIL`	A required check failed; the next scheduled run will fail the same way.
`INFO`	Informational, for example notifications disabled or a fresh state database.

Option	Effect
`--json`	Print a single JSON document instead of text (system, config, state_store, checks, summary, exit_code). Attach it to support requests; secrets are never included.
`--offline`	Skip every network check (DLH platform, SQL Server, storage, webhooks). Useful on a host that is being staged before firewall rules exist.
`--config PATH`	Diagnose a specific configuration file instead of the one next to the EXE.

Exit codes:

Code	Meaning
`0`	No required check failed (warnings allowed).
`1`	At least one `FAIL`.
`2`	The diagnostic itself crashed; the JSON output carries the error and captured output.

Disk thresholds are fixed: below 2 GB free is a WARN, below 200 MB is a FAIL. A locked DuckDB file reports a WARN that tells you whether another agent process currently holds it (a run in progress) or the lock is stale from a crash.

--config-check

Compares your dlh_agent_config.yaml with the template shipped in the installed version and prints:

Your configuration version versus the current agent version and how many minor versions behind you are.
Missing fields grouped as required, recommended (safe defaults) and optional features you have not configured, with the template default where it is not a secret.
Unrecognized fields (typos, deprecated keys, or keys from a newer template).
The template changelog entries since your configuration version.

DLH.io Agent for SQL Server -- Config Check
==================================================
  Your config version:    1.7.0
  Current agent version:  1.9.4
  Versions behind:        2 minor version(s)

MISSING FIELDS (recommended - have safe defaults but you should review):
  ~ data_retrieval.on_schema_drift_action  (default: fail)
  ~ data_retrieval.on_schema_drift_action_handling  (default: fail_once)

AVAILABLE FEATURES (optional - not configured):
  - dlh_notifications.webhooks
  - post_completion_actions.dbdeux_jobs

CHANGELOG SINCE v1.7.0:
  v1.8.0 (...): ...

Run it after every upgrade and after editing the YAML by hand. It exits 0 regardless of findings; read the report. Use --config PATH to check a file before copying it into place.

--clear-credentials-cache

Deletes the encrypted bootstrap cache under %PROGRAMDATA%\DLH\dlh-agent-sql-server. The next run performs a live bootstrap against the DLH.io platform instead of reusing cached storage credentials and tier information. Use it when:

Your account was upgraded from Trial to Customer and you want the new tier immediately.
The platform storage target for the connection was changed.
An API key was rotated and the agent still reports the old validation result.
Support asks you to rule out a stale cache.

Nothing else is touched: SQL Server credentials, the DuckDB state database and output remain in place. Requires write access to the cache folder (run from an elevated prompt or as the service account).

--install-driver

Without --auto, prints the platform, the ODBC drivers currently installed and step by step instructions (download link and silent install command) for the Microsoft ODBC Driver for SQL Server. With --auto, downloads and installs the driver without prompting, suitable for RMM deployment scripts. Requires administrator rights. The agent prefers ODBC Driver 18 and falls back to 17; you can pin a specific installed driver with connection_information.odbc_driver.

--version

DLH.io Agent for SQL Server v1.9.4
Python 3.12.4 (...)
Platform: win32

The version is read from agent_version in dlh_agent_config.yaml when present. Include this output in any support request together with the --diagnose --json report.

Exit codes at a glance

Command	0	1	2
run	Completed (table-level errors possible, see notifications)	Fatal error
`--diagnose`	No required check failed	At least one FAIL	Diagnostic crashed
`--config-check`	Always (read the report)
`--clear-credentials-cache`	Cache cleared	Could not clear cache
`--install-driver`	Instructions printed or install attempted
`--version`	Always

For scheduling and RMM integration of these commands see Operations.

Page Contents