Addons¶

Manage addon symlinks, inventories, and third-party downloads.

Modules:

Name	Description
`add`	Create root-level symlinks for specific addons found in any tracked submodule.
`analyze`	Print a structured summary of an Odoo module.
`compare`	Compare a provided addon list against the local root addons.
`diff`	Show modified Odoo addons between a base ref and HEAD.
`download`	Download addons from a GitHub repository branch.
`list`	List all addons discovered across submodules with their metadata.
`materialize`	Replace addon symlinks with a real copy of the addon directory.
`refactor`	oops addons refactor — apply section headers and docstring skeletons to custom modules.

oops addons add¶

Create root-level symlinks for specific addons found in any tracked submodule.

Searches all submodules for addons matching the provided names and creates symlinks at the repository root. Skips addons that are already present.

Usage:

oops addons add [OPTIONS] ADDONS_LIST

Options:

Name	Type	Description	Default
`--no-commit`	boolean	If set, created symlinks will not be committed.	`False`
`--help`	boolean	Show this message and exit.	`False`

Examples:

Add mass_editing and web_notify from any tracked submodule:

oops addons add mass_editing,web_notify

Stage the symlinks without committing:

oops addons add sale_management --no-commit

oops addons analyze¶

Print a structured summary of an Odoo module.

EXPERIMENTAL — This command is part of the KB pipeline. Its interface may change without notice between releases.

Reads the project KB and the module's source to produce a human- readable (or JSON) overview: manifest header, depends, per-class field and method breakdown, plus counts of declared data files and assets.

This command is read-only. It rebuilds the project KB if stale (same semantics as oops addons refactor) but performs no source rewriting, no git operations, and no manifest edits.

Usage:

oops addons analyze [OPTIONS] MODULE_PATHS...

Options:

Name	Type	Description	Default
`--kb`	file	Use an explicit KB file instead of the project KB.	None
`--refresh`	boolean	Force a project KB rebuild before analysis.	`False`
`--format`	choice (`text` \| `json`)	Output format. 'json' is suited for downstream LLM agent consumption.	`text`
`--verbose`, `-v`	boolean	Enable verbose KB logging.	`False`
`--help`	boolean	Show this message and exit.	`False`

Experimental

This command is part of the KB pipeline. Its interface may change without notice between releases. The same warning is printed at runtime.

Examples:

Print a text summary of a single module:

oops addons analyze plant_nursery

Emit JSON for downstream tooling:

oops addons analyze plant_nursery --format json | jq '.models[0]'

Analyse several modules in one invocation:

oops addons analyze plant_nursery plant_orders

Force a KB rebuild before analysing:

oops addons analyze plant_nursery --refresh

oops addons compare¶

Compare a provided addon list against the local root addons.

Prints addons missing locally (prefixed with -) and extra local addons not in the list (prefixed with +). With --delete, extra local symlinks are removed.

Usage:

oops addons compare [OPTIONS] ADDONS_LIST

Options:

Name	Type	Description	Default
`--delete`	boolean	Remove extra local symlinks not in the provided list.	`False`
`--no-commit`	boolean	Do not commit changes	`False`
`--help`	boolean	Show this message and exit.	`False`

Examples:

Check which addons from a list are missing or extra in the repo root:

oops addons compare "sale,purchase,account"

Remove extra local symlinks not in the provided list:

oops addons compare "sale,purchase" --delete

Compare against a file and skip the commit:

oops addons compare "$(cat addons.txt)" --delete --no-commit

oops addons diff¶

Show modified Odoo addons between a base ref and HEAD.

By default compares against the latest tag, or the penultimate tag when HEAD is already at the latest tag. The base can be overridden with --tag, --ref, or --commits. With --save, writes a migration script file.

Usage:

oops addons diff [OPTIONS]

Options:

Name	Type	Description	Default
`--tag`	text	Compare against this specific tag.	None
`--ref`	text	Compare against any ref or SHA.	None
`--commits`	integer	Compare against HEAD~N.	None
`-s`, `--save`	boolean	Write the command in the migration file.	`False`
`--no-commit`	boolean	Do not commit changes	`False`
`--help`	boolean	Show this message and exit.	`False`

Examples:

Show modified addons since the latest tag:

oops addons diff

Compare against a specific tag:

oops addons diff --tag v1.2.0

Compare against the last 5 commits:

oops addons diff --commits 5

Write the migration script to migrate.sh and commit:

oops addons diff --save

Write the migration script without committing:

oops addons diff --save --no-commit

oops addons download¶

Download addons from a GitHub repository branch.

Clones the repository over SSH (depth=1) into a temporary directory, discovers addon directories, and copies them into the current project. Downloaded addons are added to .gitignore (unless --no-exclude is passed).

Usage:

oops addons download [OPTIONS] URL BRANCH

Options:

Name	Type	Description	Default
`--addons`	text	Comma-separated addon names to copy (copies all if omitted).	None
`--exclude` / `--no-exclude`	boolean	Add downloaded addons to .gitignore.	`True`
`--help`	boolean	Show this message and exit.	`False`

Examples:

Download all addons from a branch:

oops addons download https://github.com/OCA/server-ux.git 18.0

Download only specific addons:

oops addons download https://github.com/OCA/server-ux.git 18.0 --addons mass_editing

oops addons list¶

List all addons discovered across submodules with their metadata.

Displays a table with addon name, symlink flag, submodule, upstream branch, PR flag, version, and author. Output can be formatted as text, JSON, or CSV.

Usage:

oops addons list [OPTIONS]

Options:

Name	Type	Description	Default
`--format`	choice (`text` \| `json` \| `csv`)	Output format	`text`
`--init` / `--no-init`	boolean	Run 'git submodule update --init' for submodules whose path is missing on disk	`False`
`--name`, `-n`	text	Limit to these submodule names (as in .gitmodules)	None
`--symlinks-only`	boolean	Show only addons that are symlinked at the repo root	`False`
`--all`	boolean	List all addons, including those not in submodules (i.e. in the root of the repo)	`False`
`--help`	boolean	Show this message and exit.	`False`

Examples:

Display the addon table:

oops addons list

Export as JSON for scripting:

oops addons list --format json

Limit to a single submodule:

oops addons list -n apikcloud/apik-addons

oops addons materialize¶

Replace addon symlinks with a real copy of the addon directory.

Useful when you need to modify a third-party addon locally. The symlink is removed and its target directory is copied in place. Only symlinks are processed; real directories are skipped.

By default all symlinks found at the repository root are processed. Use --include to restrict to a subset, or --exclude to skip specific addons.

Usage:

oops addons materialize [OPTIONS]

Options:

Name	Type	Description	Default
`--include`	text	Comma-separated list of addon names to materialize (default: all symlinks).	None
`--exclude`	text	Comma-separated list of addon names to skip.	None
`--dry-run`	boolean	Show what would happen, do nothing.	`False`
`--no-commit`	boolean	Do not commit changes	`False`
`--help`	boolean	Show this message and exit.	`False`

Examples:

Preview all symlinks that would be materialized:

oops addons materialize --dry-run

Materialize all symlinks at the repository root:

oops addons materialize

Materialize only specific addons:

oops addons materialize --include my_addon,other_addon

Materialize all symlinks except specific ones:

oops addons materialize --exclude legacy_addon

Materialize without committing:

oops addons materialize --no-commit

oops addons refactor¶

oops addons refactor — apply section headers and docstring skeletons to custom modules.

EXPERIMENTAL — This command is part of the KB pipeline. Its interface may change without notice between releases.

Operates on one or more modules in a single run. Reads the project KB, classifies every field and method in every model file, then rewrites each file in-place. By default a dedicated git branch is created and one commit per module is produced. Use --no-branch to stay on the current branch and --no-commit to skip committing (edits are staged but not committed).

What the tool does¶

Normalises section headers to the canonical # === SECTION === # format.
Reorganises fields and methods into the section order defined in CONVENTIONS.md.
Generates minimal Google-style docstring skeletons for every method that does not already have one.
Inserts a class docstring skeleton on every new model class.
Creates a git branch (refactor/doc-<module> for one module, refactor/doc-multi for several) and produces one commit per module whose body lists every rewritten file.

What the tool does NOT do¶

It never modifies method bodies.
It never infers business intent.
It never completes # TODO: markers.
It never touches non-model Python files, XML, CSV, or manifest.py.

Usage:

oops addons refactor [OPTIONS] MODULE_PATHS...

Options:

Name	Type	Description	Default
`--kb`	file	Path to the project KB database. When set, --refresh is ignored and no auto-rebuild happens.	None
`--branch` / `--no-branch`	boolean	Create a dedicated git branch before rewriting (use --no-commit to disable commits).	`True`
`--no-commit`	boolean	Do not commit changes.	`False`
`--dry-run`	boolean	Print what would be changed without writing any file.	`False`
`--refresh`	boolean	Force a project KB rebuild before running, even if the KB looks fresh.	`False`
`--verbose`, `-v`	boolean	N/A	`False`
`--help`	boolean	Show this message and exit.	`False`

Experimental

This command is part of the KB pipeline. Its interface may change without notice between releases. The same warning is printed at runtime.

Examples:

Rewrite a single module on a dedicated refactor/doc-<module> branch with one commit:

oops addons refactor my_module

Rewrite several modules in one run (one commit per module on refactor/doc-multi):

oops addons refactor my_module other_module

Preview the changes without writing any file:

oops addons refactor my_module --dry-run

Stay on the current branch and skip the commit (edits are staged):

oops addons refactor my_module --no-branch --no-commit

Force a project KB rebuild before running:

oops addons refactor my_module --refresh

Use an external KB database (skips the project-KB freshness check and --refresh):

oops addons refactor my_module --kb /path/to/project_kb.db