Settings and Flags
The two everyday uses of Detent are changing a number and flipping a switch.
These examples continue from the Quick-start, in the
same shell and directory, with the authority and the agent running and the
publish helper defined.
Change a Numeric Setting
Section titled “Change a Numeric Setting”Every knob holds one signed 64-bit integer. Use it for limits, batch sizes, timeouts in milliseconds, or anything else you’d otherwise hard-code:
publish search:max_results '{"default":500}'publish search:timeout_ms '{"default":250}'sleep 1detent get search:max_results# 500detent get search:timeout_ms# 250Each transaction replaces the whole definition of the key it names and leaves every other knob alone, so a publish only lists the knob it changes.
In C++, read a knob with get, or with get_as<T> for a checked
conversion that fails instead of truncating:
std::int64_t max_results = client.get_or_panic("search:max_results");
auto timeout = client.get_as<std::uint32_t>("search:timeout_ms");if (!timeout) log(timeout.error().what());Toggle a Feature
Section titled “Toggle a Feature”A feature flag or kill switch is a knob whose values are 0 and 1. Turn a new checkout path on:
publish checkout:new_path '{"default":1}'sleep 1detent get checkout:new_path# 1And off again, if anything goes wrong:
publish checkout:new_path '{"default":0}'sleep 1detent get checkout:new_path# 0In C++, compare the value, or read it with get_as<bool>, which takes only 0
and 1:
if (client.get_or_panic("checkout:new_path") == 1) { new_checkout();} else { old_checkout();}Remove a Knob
Section titled “Remove a Knob”A null value deletes the key from its namespace:
publish search:timeout_ms nullsleep 1detent get search:timeout_ms# ERR MissingKnob: search:timeout_ms (scoped lookup failed)A client whose baked defaults contain search:timeout_ms falls back to that
baked value. A client without one now gets a MissingKnob error for it, so
remove knob reads from code before removing their definitions.
Fall Back for a Single Read
Section titled “Fall Back for a Single Read”From the shell, --default supplies a value for one read when the knob can’t
be read at all:
detent get checkout:unpublished_feature --default 0# 0This doesn’t publish or create anything. It’s a per-call fallback for scripts that must keep going. The C++ library deliberately has no equivalent; see Errors and Failures for why.