Crate bhtune_cli 

bhtune-cli — the headless adapter.

Builds the bhtune binary: a scriptable, no-GUI way to run an MRFT tune and inspect its history, intended for scheduled/unattended use (cron, CI, batch tuning campaigns) as well as interactive terminal use.

• args — the clap derive Cli/Command definitions and the wrapper enums adapting bhtune-core’s domain enums to clap::ValueEnum (required by Rust’s orphan rule).
• config — CLI > env > TOML config file > platform default precedence for the database path, opcda-bridge gateway address, default OPC server, and the user-supplied template catalog path (template-user-catalog).
• db — opens the database and seeds the built-in and (if configured) user-catalog DCS/PLC templates on every startup, and runs the history-retention sweep if a policy is configured.
• retention — turns history-retention’s “N days” policy into a cutoff and a logged deletion sweep, shared by db::open’s startup call, bhtune-server’s periodic timer, and bhtune history prune.
• driver — constructs the selected Driver implementation.
• timing — supplies live or fixed-step timestamps to the clock-free MRFT engine.
• commands — one module per subcommand family: tune/simulate, template, history, export, opc.
• output — the --output table|json format shared by history list/history show and tune/simulate’s final summary, plus error formatting.
• logging — tracing/tracing-subscriber structured logging (cli-logging), initialized once in run, never touching stdout so it can never interleave with --output json’s single-object contract.

main.rs stays a one-line delegator to run; [run_with_cli] is the actual entry point, kept separate so tests can exercise it against an already-parsed args::Cli without needing to control std::env::args() — mirroring opcda-bridge-client’s run/run_with_cli split. Logging is initialized in run, not [run_with_cli], for the same reason: it keeps tracing setup (and its process-global, only-succeeds-once subscriber installation) entirely out of run_with_cli’s own large, injection-based test suite – see logging’s test module doc comment.

Non-interactive/scheduled use (cron, CI, batch campaigns) is tune/simulate’s --yes/--write-pid <level> flags (bypassing the interactive write-back prompt) plus the global [tuning] timing configuration, which mandatorily bounds unattended runs and caps individual driver operations, and this module’s distinguished exit codes (EXIT_ABORTED, EXIT_TIMED_OUT, EXIT_POOR_QUALITY, EXIT_ACTUATION_FAILED, EXIT_WRITE_BACK_FAILED, EXIT_RESTORE_INCOMPLETE), so a scheduler can tell “aborted”, “timed out”, “the plant data couldn’t be trusted”, “test ran but the write-back failed”, “the loop may not have been fully restored”, and “never ran at all” apart without parsing stdout. See AGENTS.md’s cli-automation/cli-safety sections.

Modules

args

Command-line argument definitions (clap derive) and the small wrapper enums that adapt bhtune-core’s domain enums to clap::ValueEnum.

cancel

A single, process-wide Ctrl+C listener shared by every await point in a tune, replacing the pre-safety-cancellation design of constructing tokio::signal::ctrl_c() fresh on every polling-loop iteration (see AGENTS.md’s safety-cancellation). Registering the signal exactly once, as early in the process as possible, closes the gap where a Ctrl+C delivered while no listener happens to be alive is silently swallowed – tokio installs a process-wide SIGINT handler the first time ctrl_c() is polled and never reverts to the OS default, so a lost signal isn’t merely unhandled, it’s gone.

commands

One module per subcommand family.

config

Global bhtune configuration, including the shared [tuning] timing policy and the CLI flag > env var > TOML config file > built-in default precedence used by settings that expose command-line or environment overrides.

db

Opens the CLI’s database, seeds the built-in and user-catalog DCS/PLC templates, and runs the history-retention sweep – all on every startup.

driver

Constructs the selected bhtune_driver::Driver implementation from a TuneArgs.

logging

Structured logging (cli-logging), matching opcda-bridge-gateway’s own tracing stack and log.* configuration conventions (level/directory/format/rotation, resolved with the same CLI flag > env var > config file > default precedence as every other bhtune setting) – see crate::config::LogConfig/resolve_log_settings.

output

Output format selection for the handful of commands that support --output json (history list/history show and tune/simulate’s final summary line — see AGENTS.md’s cli-automation section for why exactly these three).

retention

history-retention: age-based deletion of old tune runs.

Constants

EXIT_ABORTED

A tune/simulate run was aborted (Ctrl+C) before it finished; the loop was restored to its pre-test mode. Distinct from EXIT_FAILURE so a scheduler can tell “someone intentionally stopped this” apart from “this broke”.

EXIT_ACTUATION_FAILED

A live OPC DA tune was aborted because an accepted MV command could not be confirmed at the controller before its deadline or before a replacement relay command was required. The ordinary restore path still ran; EXIT_RESTORE_INCOMPLETE takes precedence if that restore could not itself be confirmed.

EXIT_FAILURE

A setup problem (bad flags, an unreadable config file, a database error, an unexpected driver error) prevented the command from running to completion at all. Equal to ExitCode::FAILURE.

EXIT_POOR_QUALITY

A tune/simulate run was aborted because a driver reported a non-Good OPC quality for a tuning-critical reading (finding 5 of the live-plant safety review): an initial reading, the transition-to-manual setpoint capture, or an in-flight PV poll sample, and (for the in-flight case) the global Config > OPC quality policy rejected Uncertain, or the quality was Bad rather than merely Uncertain. The loop was restored to its pre-test mode, exactly like EXIT_ABORTED/EXIT_TIMED_OUT. Distinct from both so a scheduler’s alerting can tell “the plant data itself couldn’t be trusted” apart from a user-initiated stop or a run that simply took too long. See commands::tune::TuneOutcome::PoorQuality and AGENTS.md’s safety-quality section.

EXIT_RESTORE_INCOMPLETE

A tune/simulate run ended (via normal completion, Ctrl+C, or a timeout) without being able to confirm the loop was fully restored to its pre-test mode/MV/setpoint – either a second Ctrl+C was received while the restore was in flight, or [tuning].restore_timeout_secs elapsed first. Distinct from every other exit code because it means the loop may have been left mutated with no further attempt made to fix it: an operator must check it by hand, using the tag/value named in the warning printed to stderr. See commands::tune::TuneOutcome::RestoreIncomplete and AGENTS.md’s safety-cancellation section.

EXIT_SUCCESS

Process exited normally, and if this was tune/simulate, any PID write-back either succeeded or was cleanly skipped. Equal to ExitCode::SUCCESS.

EXIT_TIMED_OUT

A tune/simulate run was aborted because [tuning].timeout_secs elapsed before the engine reported completion; the loop was restored to its pre-test mode, exactly like EXIT_ABORTED. Distinct from it so a scheduler’s alerting can tell “this run had to be killed for running too long” (possibly a stuck relay, a misconfigured tag mapping, or a stalled driver read – worth investigating) apart from “an operator stopped it on purpose” (routine). See commands::tune::TuneOutcome::TimedOut and AGENTS.md’s cli-safety section.

EXIT_WRITE_BACK_FAILED

A tune/simulate run completed the MRFT test itself, but writing the selected PID constants back to the DCS failed (the write was rejected, errored, or its confirmation readback didn’t match). Distinct from both EXIT_SUCCESS (nothing to report) and EXIT_FAILURE (the test itself never produced a result) so an unattended --write-pid/--yes run can tell “the test ran fine but the loop was NOT updated” apart from either of those. See commands::tune::TuneOutcome and AGENTS.md’s cli-automation section.

Functions

run

Parses real CLI arguments, initializes structured logging, and runs, returning a process exit code.