Metadata-Version: 2.4
Name: odoorun
Version: 1.1.0
Summary: A modern CLI for running and managing Odoo projects.
Project-URL: Homepage, https://github.com/khalid99io/odoorun
Project-URL: Repository, https://github.com/khalid99io/odoorun
Project-URL: Issues, https://github.com/khalid99io/odoorun/issues
Author-email: "Khalid A. Dev" <khalid.a.dev@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,developer-tools,odoo,odoo-development,postgresql
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.8
Provides-Extra: dev
Requires-Dist: build>=1.3.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

# odoorun

[![PyPI](https://img.shields.io/pypi/v/odoorun.svg)](https://pypi.org/project/odoorun/)
[![Python](https://img.shields.io/pypi/pyversions/odoorun.svg)](https://pypi.org/project/odoorun/)
[![CI](https://github.com/khalid99io/odoorun/actions/workflows/ci.yml/badge.svg)](https://github.com/khalid99io/odoorun/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`odoorun` is a portable command-line launcher and inspection tool for Odoo
development projects. It discovers the appropriate Odoo executable, prepares
addon paths, forwards ordinary Odoo options, completes database and module
names, and provides read-only database/addon inspection commands.

No symlink, alias, or machine-specific path is required. Run
`odoorun completion install` once to enable Bash auto-completion.

## Features

- Run a project-local `odoo-bin`, a linked-venv `odoo`, or `odoo` on `PATH`.
- Run from a project root or any nested directory.
- Configure standard and custom addon paths automatically.
- Complete PostgreSQL database names after `-d`/`--database`.
- Complete module names after `-u`/`--update` and `-i`/`--init`.
- Complete odoorun commands, options, and fixed option values.
- List Odoo databases and detect their versions.
- List core/custom addon manifests and optionally show database module state.
- Forward Odoo 19 native module and database management commands.
- Produce human-readable tables, tab-separated text, or JSON.

## Requirements

- Python 3.10 or newer.
- `psql` for database completion, `db list`, and database-aware `addon list`.

Launching Odoo and listing addons from the filesystem do not require `psql`.

## Installation

Install the published package as an isolated command:

```bash
uv tool install odoorun
```

Or install with pip:

```bash
python -m pip install odoorun
```

Install the latest source directly from GitHub:

```bash
uv tool install git+https://github.com/khalid99io/odoorun.git
```

Install or refresh a local development checkout:

```bash
uv tool install --force .
```

## Quick start

Run Odoo with ordinary Odoo options:

```bash
odoorun -d my_database --dev=all
odoorun -d my_database -u sale_management
```

Add custom directories to an Odoo source checkout. Relative `-a` paths are
resolved from the checkout's parent directory:

```bash
odoorun -a custom-addons,enterprise -d my_database
```

Use Odoo's native addon preference unchanged:

```bash
odoorun --addons-path="addons,custom-addons" -d my_database
```

Use native Odoo 19 module and database commands:

```bash
odoorun module uninstall -d my_database obsolete_module
odoorun module upgrade -d my_database sale stock
odoorun db dump my_database backup.zip
```

The short `o` command is optional. If you configure `alias o=odoorun`, the
examples below can use `o`; otherwise use `odoorun` directly.

## How executable discovery works

odoorun selects the first available executor in this order:

1. An executable `odoo-bin` in the current directory or a parent directory.
2. An Odoo executor in the linked or configured project venv, such as
   `~/venvs/<project>/bin/odoo`.
3. An `odoo` command available on `PATH`.

For source checkouts, the built-in `addons` directory is passed automatically.
For linked-venv projects, `--addons-path=odoo/addons` is added unless the user
provides `--addons`, `--addons-path`, or an equivalent value explicitly.

If the project and venv names differ, configure discovery with:

```bash
export ODOORUN_VENV_NAME=my-project-venv
export ODOORUN_VENV_ROOT="$HOME/venvs"
```

odoorun invokes the venv executable directly, so activating the venv is not
required for the Odoo child process. A child process cannot alter the parent
shell prompt; prompt decoration remains a shell responsibility.

## Command reference

### Native Odoo commands

Arguments outside odoorun's inspection/setup commands are forwarded to the
discovered Odoo executable. This includes Odoo 19's native module commands:

```bash
odoorun module install -d my_database module_a module_b
odoorun module upgrade -d my_database module_a module_b
odoorun module uninstall -d my_database module_a module_b
```

> [!CAUTION]
> Uninstalling an Odoo module can delete its records and may uninstall
> dependent modules. Test against a duplicated database and create a backup
> before running the command on important data.

It also includes Odoo 19's native database operations:

```bash
odoorun db init my_database
odoorun db dump my_database backup.zip
odoorun db load restored_database backup.zip
odoorun db duplicate source_database target_database
odoorun db rename old_name new_name
odoorun db drop my_database
```

`odoorun db list` remains odoorun's richer read-only inspection command.
Every other `db` subcommand is delegated to Odoo. Native command availability
and exact options therefore depend on the discovered Odoo version.

### Odoo passthrough

```text
odoorun [ODOO_OPTIONS]
```

Arguments whose first item is not an odoorun tool command are passed to the
discovered Odoo executable. The `-a` option is odoorun's source-checkout
convenience and is converted into the effective native `--addons-path`.

### `odoorun doctor`

```text
odoorun doctor
```

Displays the working directory, discovered Odoo executable, and whether `psql`
is available. It does not modify the project or start Odoo.

### `odoorun completion`

```text
odoorun completion [bash|install]
```

- `bash` prints the generated Bash integration script.
- `install` idempotently adds `source <(odoorun completion bash)` to `~/.bashrc`.

Run the installer once and open a new Bash terminal:

```bash
odoorun completion install
```

Command and option completion is available for `odoorun` and `o`:

```bash
o d<Tab>                         # db, doctor
o db <Tab>                       # list, init, dump, load, duplicate, rename, drop
o addon list --s<Tab>            # --source, --state
o addon list --source c<Tab>     # core, custom
o addon list --state in<Tab>     # installed
o db list --format j<Tab>        # json
o module un<Tab>                 # uninstall
o module uninstall -d demo sale_<Tab>
o module force-demo -d demo sale_<Tab>
```

Database and module completion is also registered for direct Odoo commands:
`odoo`, `odoo-bin`, and `./odoo-bin`.

Database examples:

```bash
o -d demo<Tab>
odoorun --database=demo<Tab>
```

Module examples, including comma-separated values:

```bash
o -d my_database -u sale_m<Tab>,bas<Tab>
o -d my_database -i custom_m<Tab>
```

Database completion uses `psql` and respects PostgreSQL environment variables
such as `PGHOST`, `PGPORT`, `PGUSER`, `PGDATABASE`, and `PGPASSWORD`. Module
completion finds directories containing `__manifest__.py` or `__openerp__.py`
in source, project, explicit, and linked-venv addon roots.

### `odoorun db list`

```text
odoorun db list [OPTIONS]
```

Options:

- `--odoo-version VERSION`: keep Odoo databases whose installed `base` module
  version starts with `VERSION`, such as `19` or `19.0`.
- `--all`: include regular PostgreSQL and inaccessible databases.
- `--format table|plain|json`: select the output format; default is `table`.
- `--no-header`: hide headings in table/plain output.

Examples:

```bash
odoorun db list
odoorun db list --odoo-version 19
odoorun db list --all --format json
```

By default, only databases recognized as Odoo databases are shown. Detection
uses `ir_module_module`, and the displayed Odoo version comes from the installed
`base` module.

### `odoorun addon list`

```text
odoorun addon list [OPTIONS]
```

Options:

- `-d, --database DATABASE`: query `ir_module_module` and annotate filesystem
  addons with their state/version in that database.
- `--source all|core|custom`: filter by addon-root origin.
- `--state all|installed|uninstalled|upgrade`: filter by database state;
  non-`all` values require `-d`.
- `--installed`: shortcut for `--state installed`; requires `-d`.
- `--custom`: shortcut for `--source custom`.
- `--core`: shortcut for `--source core`.
- `--addons-path PATHS`: override discovery with a native comma-separated Odoo
  addon path.
- `-a PATHS`: add comma-separated custom directories to source-checkout
  discovery.
- `--format table|plain|json`: select the output format; default is `table`.
- `--no-header`: hide headings in table/plain output.

Examples:

```bash
odoorun addon list
odoorun addon list --source core
odoorun addon list --custom
odoorun addon list -d my_database
odoorun addon list -d my_database --installed --custom
odoorun addon list --addons-path="addons,../enterprise"
```

Addon discovery always starts from filesystem directories. Supplying `-d`
does not search addons inside a database; it only adds database state/version
information and enables state filtering.

### `odoorun --version`

Print the installed odoorun version and exit:

```bash
odoorun --version
```

Every tool command has focused help:

```bash
odoorun completion --help
odoorun db list --help
odoorun addon list --help
```

## PostgreSQL connection behavior

Database features execute read-only queries through `psql`. Standard libpq
configuration is respected, including environment variables, service files,
and `.pgpass`. Passwords are not accepted as odoorun command-line options.

## Compatibility

The launcher is intentionally decoupled from Odoo's Python package: odoorun
discovers and invokes the target project's executable rather than importing
Odoo itself. This allows the tool to run source checkouts and virtual
environments independently of the Python environment where odoorun is
installed.

| Capability | Availability |
| --- | --- |
| Odoo executable and addon-path discovery | Version-independent |
| Odoo argument passthrough | Version-independent |
| `doctor`, completion, `db list`, `addon list` | Provided by odoorun |
| Native `module` and extended `db` subcommands | Odoo 19 or newer |

## Development

Install development dependencies and run the full local checks:

```bash
uv sync --extra dev
uv run ruff format --check src tests
uv run ruff check src tests
uv run python -m unittest discover -s tests -v
uv run python -m compileall -q src tests
uv build
```

The GitHub CI workflow lints, tests, compiles, and builds the project. The test
matrix covers Python 3.10 through 3.14.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and
[CHANGELOG.md](CHANGELOG.md) for release history.

## License and publishing

odoorun is released under the MIT License. The source repository is:

https://github.com/khalid99io/odoorun

PyPI releases use the GitHub Actions Trusted Publisher workflow. Before a new
release, update the version in `pyproject.toml`, verify CI, and push a matching
version tag.
