Skip to content

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.


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:

Terminal window
publish search:max_results '{"default":500}'
publish search:timeout_ms '{"default":250}'
sleep 1
detent get search:max_results
# 500
detent get search:timeout_ms
# 250

Each 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());

A feature flag or kill switch is a knob whose values are 0 and 1. Turn a new checkout path on:

Terminal window
publish checkout:new_path '{"default":1}'
sleep 1
detent get checkout:new_path
# 1

And off again, if anything goes wrong:

Terminal window
publish checkout:new_path '{"default":0}'
sleep 1
detent get checkout:new_path
# 0

In 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();
}

A null value deletes the key from its namespace:

Terminal window
publish search:timeout_ms null
sleep 1
detent 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.


From the shell, --default supplies a value for one read when the knob can’t be read at all:

Terminal window
detent get checkout:unpublished_feature --default 0
# 0

This 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.