Configuration

oduit supports several config shapes for compatibility, but the preferred user facing format is sectioned TOML.

Recommended Format

Local or environment configs should look like this:

[binaries]
python_bin = "./venv/bin/python"
odoo_bin = "./odoo/odoo-bin"
coverage_bin = "./venv/bin/coverage"

 [odoo_params]
 addons_path = "./addons,./enterprise"
 db_name = "project_dev"
 db_user = "odoo"
 db_host = "localhost"
 http_port = 8069
 write_protect_db = false
 agent_write_protect_db = false
  needs_mutation_flag = false
  agent_needs_mutation_flag = false

Recommended setup for existing Odoo projects

If you already have an odoo.conf file, prefer importing it instead of rewriting the config by hand:

oduit init dev --from-conf ./odoo.conf
oduit --env dev print-config
oduit --env dev doctor

For a project-local config, write .oduit.toml directly:

oduit init dev --from-conf ./odoo.conf --local
oduit print-config

Use --dry-run to preview the generated TOML without writing a file. The generated config may include secrets imported from odoo.conf.

Runtime DB mutation policy is controlled by explicit flags:

write_protect_db blocks runtime DB mutation for every caller
needs_mutation_flag requires --allow-mutation for human runtime DB mutation
agent_write_protect_db blocks runtime DB mutation for agent commands
agent_needs_mutation_flag requires --allow-mutation for agent runtime DB mutation

Plain test runs stay read-only. Only runtime flows that install, update, uninstall, create a database, or explicitly trigger runtime actions consult these flags.

The legacy risk-level key is no longer supported and now raises a config error.

Supported Locations

local project config: .oduit.toml
named environment config: ~/.config/oduit/<env>.toml
compatibility support: ~/.config/oduit/<env>.yaml

Compatibility Notes

oduit still accepts:

flat config files with keys at the root level
YAML environment files

Those shapes are compatibility support, not the preferred format for new docs or new projects.

Canonical Normalized Shape

Internally, oduit now treats the sectioned shape as the canonical normalized configuration:

[binaries]
python_bin = "./venv/bin/python"
odoo_bin = "./odoo/odoo-bin"
coverage_bin = "./venv/bin/coverage"

[odoo_params]
addons_path = "./addons,./enterprise"
db_name = "project_dev"

oduit agent resolve-config exposes both the compatibility effective_config view and the canonical normalized_config view, plus config_shape metadata with a shape_version.

Legacy flat config files remain supported, but resolve-config now reports a deprecation warning when they are detected so agents can migrate toward the sectioned TOML shape.

Canonical Normalized Shape

Internally, oduit now treats the sectioned shape as the canonical normalized configuration:

[binaries]
python_bin = "./venv/bin/python"
odoo_bin = "./odoo/odoo-bin"
coverage_bin = "./venv/bin/coverage"

[odoo_params]
addons_path = "./addons,./enterprise"
db_name = "project_dev"

oduit agent resolve-config exposes both the compatibility effective_config view and the canonical normalized_config view, plus config_shape metadata with a shape_version.

Legacy flat config files remain supported, but resolve-config now reports a deprecation warning when they are detected so agents can migrate toward the sectioned TOML shape.

Operation sets are not environment configuration

Environment configuration stays in .oduit.toml or ~/.config/oduit/<env>.toml. Operation sets live beside the active config and store reusable execution plans for install, update, or test operations.

For local project config:

.oduit.toml
.oduit/
  sets/
    base.toml

For named environments:

~/.config/oduit/dev.toml
~/.config/oduit/sets/base.toml

Use oduit set inspect, oduit set apply, and oduit set list to work with sets. Save addon lists into sets with --save-set and --set-kind. Reorder install/update sets with install-order --from-set.

Short names resolve from the active config set store, then .oduit/sets/, then ~/.config/oduit/sets/.

Paths in [test].test_files resolve relative to the set file, not necessarily cwd.

Execution controls

Operation sets may define execution controls inside their matching section. verify_state enables database state verification after install/update steps. retry_missing retries addons that are still not installed after verification. one_by_one executes addon operations individually. retry_failed_tests applies to test tags and files in test sets. stop_on_error controls whether execution stops on the first failure. skip_installed (install only) skips already-installed addons. require_installed (update only) fails precheck for uninstalled addons.

Equivalent CLI options: --verify-state, --retry-missing, --one-by-one. CLI options override set-file keys for each invocation. Important Keys ————–

Binary keys:

python_bin
odoo_bin
coverage_bin

Common Odoo keys:

addons_path
db_name
db_host
db_port
db_user
db_password
write_protect_db
agent_write_protect_db
needs_mutation_flag
agent_needs_mutation_flag
config_file
without_demo
log_level
http_port
workers

Documentation workflow settings

Use this section to constrain addon technical documentation writes and scans:

[documentation]
allowed_addon_dirs = ["./addons"]

allowed_addon_dirs values are resolved relative to the project base: .oduit.toml directory when present, then git root, then current working directory.

This keeps technical-next and technical-status focused on your project addons and avoids selecting native/third-party addon roots by default.

Legacy flat-key compatibility remains supported through documentation_allowed_addon_dirs.

Python Usage

from oduit import ConfigLoader

loader = ConfigLoader()
dev_config = loader.load_config("dev")

if loader.has_local_config():
    local_config = loader.load_local_config()

envs = loader.get_available_environments()

Import Existing Odoo Configuration

For the full migration workflow, including validation steps and no-pytest smoke checks, see Migrating from odoo.conf.

Diagnostics

Use doctor to validate that your config, binaries, addons paths, version, and database settings all line up:

oduit doctor
oduit --env dev doctor