odoo-agent-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{odoo_agent_cli-0.3.0 → odoo_agent_cli-0.5.0}/.gitignore

@@ -11,3 +11,6 @@ build/
 htmlcov/
 .env
 .DS_Store
+
+# mkdocs build output
+site/

{odoo_agent_cli-0.3.0 → odoo_agent_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: odoo-agent-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Odoo JSON-RPC CLI and Python client built for AI agents and scripts.
 Project-URL: Homepage, https://github.com/Organize-IT/odoo-cli
 Project-URL: Issues, https://github.com/Organize-IT/odoo-cli/issues
@@ -53,14 +53,22 @@ export ODOO_URL=https://mycompany.odoo.com ODOO_DB=mycompany \
        ODOO_LOGIN=bot@mycompany.com ODOO_API_KEY=...   # API key or password
 
 odoo info                                  # version, uid, connection source
-odoo models --like invoice                 # find the right technical name
+odoo alias                                 # business names for models, and presets
+odoo models --like invoice                 # or find the technical name yourself
 odoo fields account.move --stored          # what you can filter and order on
-odoo count account.move -w move_type=out_invoice -w payment_state=not_paid
-odoo search account.move -w move_type=out_invoice -w invoice_date_due<2026-09-01 \
+odoo count invoices -w overdue
+odoo search invoices -w overdue \
      --fields name,partner_id,amount_residual --order "invoice_date_due" --limit 20
+odoo group invoices -w unpaid --by partner_id --sum amount_residual
 ```
 
-Prefer named connections? They live in a `0600` TOML file:
+`invoices` is `account.move` filtered on `move_type = out_invoice`, and `overdue` is
+`payment_state = not_paid` past its due date. Both expand to an ordinary domain before
+anything is sent, and the technical names keep working. Full documentation:
+[Organize-IT.github.io/odoo-cli](https://github.com/Organize-IT/odoo-cli/tree/main/docs).
+
+Prefer named connections? They live in a TOML file written owner-only where the platform
+can enforce that — `odoo profile path --check` says whether it can:
 
 ```bash
 odoo profile add acme --url https://acme.odoo.com --db acme --login bot@acme.com \
@@ -77,7 +85,10 @@ First match wins, and the CLI never prompts:
 3. a profile named `default`
 
 Nothing found: exit code 3 with a message listing those three ways. A profile stores the key
-(`--api-key`) or points to an env var (`--api-key-env`). `odoo profile path` shows the file.
+(`--api-key`) or points to an env var (`--api-key-env`). `odoo profile path` shows the file,
+`--check` reports what its permissions are actually worth: mode 600 means owner-only on
+POSIX and nothing at all on Windows, where `chmod` only toggles a read-only attribute. On
+such a platform, prefer `--api-key-env` and keep the key in your secret manager.
 
 ## Output contract
 
@@ -89,6 +100,7 @@ Nothing found: exit code 3 with a message listing those three ways. A profile st
 | bad arguments | | `{"error": ...}` | 2 |
 | connection, auth, no profile | | `{"error": ...}` | 3 |
 | refused by a guard | | `{"error": ...}` | 4 |
+| query repaired to run | rows | `{"error": ...}` | 5 |
 | write executed | result | `{"write": {"model", "method", "ids", "fields"}}` | 0 |
 
 Data is never humanised: many2one fields stay `[id, "name"]`, empty values stay `false`.
@@ -102,6 +114,7 @@ Values of fields named like `password`, `api_key`, `secret` are `[redacted]` unl
 | `--company ID`, `--lang CODE`, `--context JSON` | Odoo context merged into every call |
 | `--insecure` | skip TLS verification (self-signed on-prem) |
 | `--no-redact`, `--include-sensitive` | lift the two output/model guards |
+| `--no-validate` | skip the field-name check against the model schema |
 | `--debug` | one JSON line per RPC on stderr (method, id, duration, retries) |
 | `--verbose` | include Odoo's server traceback in error output |
 
@@ -122,13 +135,76 @@ Values of fields named like `password`, `api_key`, `secret` are `[redacted]` unl
 
 Values: `true/false/null`, integers, floats, JSON lists or objects, quoted strings, else text.
 
+A bare word is looked up as a preset for the model: `-w overdue`, `-w unpaid`, `-w draft`,
+`-w confirmed`, `-w archived`. `odoo alias MODEL --presets` lists the ones that apply. A bare
+word that is not a preset exits 2 listing the ones that are.
+
+## Your own names
+
+The shipped table covers what most tenants call things. A profile file adds the rest, and a
+user entry replaces a built-in of the same name — your tenant knows its vocabulary better than
+this tool does:
+
+```toml
+[aliases.subscriptions]
+model = "sale.subscription"
+domain = [["stage_category", "=", "progress"]]
+help = "Running subscriptions"
+
+[aliases.invoices]                     # replaces the built-in
+model = "account.move"
+domain = [["move_type", "=", "out_invoice"], ["company_id", "=", 3]]
+
+[presets.mine]
+domain = [["user_id", "=", 7]]
+models = ["crm.lead", "sale.order"]
+```
+
+`odoo alias` marks each entry `builtin` or `config`. A malformed table fails the command with
+exit 2 instead of being skipped: a filter you believe is applied and is not is exactly what
+this mechanism exists to avoid. Dynamic dates work too — `@today`, `@month-start`, `@year-start`.
+
+## Names and typos
+
+Read commands accept an alias in place of a technical model name (`invoices`, `customers`,
+`quotes`, `pickings`, ...); `odoo alias` prints the table and needs no connection. Write
+commands refuse an alias that carries a filter, so a vendor bill cannot be filed as a
+customer invoice by accident.
+
+Field names are checked against the model schema before the call, which costs nothing after
+the first lookup:
+
+```console
+$ odoo search partners -w mobil=+32
+{"error": {"code": "unknown_field", "message": "res.partner has no field 'mobil'. Did you mean 'mobile'? (also: phone)"}}
+$ echo $?
+2
+```
+
+`fields_get` is read once per model and cached under `~/.cache/odoo-cli` for 24 hours
+(`odoo cache path|list|clear`, `ODOO_CACHE_DIR`, `ODOO_SCHEMA_TTL`). Dotted paths are
+followed across relations. A computed non-stored field used in `-w` or `--order` warns on
+stderr rather than failing. Validation only rejects a name it has positively read from the
+server: when the schema is unreadable it stays quiet, so it can never refuse wrongly.
+`--no-validate` or `ODOO_NO_VALIDATE=1` turns it off.
+
+## Aggregates
+
+```bash
+odoo group invoices -w overdue --by partner_id --sum amount_residual \
+     --order "amount_residual desc" --limit 10
+odoo group invoices --by invoice_date:month --sum amount_total
+```
+
+`read_group` under the hood: counts and totals per group without pulling the records.
+
 ## Writes
 
 Off by default. Enable per connection with `allow_writes = true` on the profile
 (`odoo profile add ... --allow-writes`) or `ODOO_ALLOW_WRITES=1`.
 
 ```bash
-odoo create crm.lead -v name="Website inquiry" -v partner_id=42 --dry-run   # shows payload, exit 0
+odoo create crm.lead -v name="Website inquiry" -v partner_id=42 --dry-run   # payload only, exit 0
 odoo create crm.lead -v name="Website inquiry" -v partner_id=42             # prints the new id
 odoo write res.partner 42,43 -v active=false
 odoo unlink res.partner 99 --yes                                            # --yes required
@@ -146,8 +222,9 @@ are refused unless `--include-sensitive`.
   many2one shapes) and recipes.
 - The same text ships as an [Agent Skill](https://github.com/Organize-IT/odoo-cli/blob/main/SKILL.md):
   `npx skills add Organize-IT/odoo-cli`.
-- `odoo search ... --lenient-fields` removes fields Odoo rejects and retries, with a warning on
-  stderr. Exploration only.
+- `odoo search ... --lenient-fields` removes fields Odoo rejects and retries. It prints the
+  rows, then exits **5**: they answer a wider question than the one you asked. Exploration
+  stays comfortable; a script that checks its exit codes cannot be fooled by it.
 
 ## Library
 
@@ -190,8 +267,11 @@ repair loop in `odoocli.lenient`.
 
 ```bash
 uv sync --group dev
+uvx pre-commit install               # ruff, mypy and hygiene hooks on commit
 uv run pytest                        # unit tests, mocked JSON-RPC
 uv run ruff check && uv run mypy
+uv run pytest --cov --cov-report=term-missing   # gated at 93% in CI
+uv run --group docs mkdocs serve     # the documentation site
 
 ODOO_VERSION=17.0 scripts/start-odoo.sh                     # throwaway Odoo in Docker
 ODOO_URL=http://localhost:8069 ODOO_DB=test ODOO_LOGIN=admin ODOO_API_KEY=admin \
@@ -199,9 +279,14 @@ ODOO_ALLOW_WRITES=1 uv run pytest -m integration -o addopts=""
 docker compose -f docker/odoo-compose.yml down -v
 ```
 
-CI runs the unit suite on every PR and the integration matrix (Odoo 17.0, 18.0, 19.0) on
-`main`, tags and manual dispatch. Releases are published to PyPI on `v*` tags through
-trusted publishing.
+CI runs the unit suite on Python 3.11-3.13 and builds the docs on every PR; the integration
+matrix (Odoo 17.0, 18.0, 19.0) runs on `main`, tags and manual dispatch. Releases are
+published to PyPI on `v*` tags through trusted publishing, with every action pinned to a
+commit digest.
+
+`AGENTS.md` is the specification: layering, the contracts that may not change silently, and
+the definition of done. [docs/decisions/](docs/decisions/) records the decisions with a real
+trade-off behind them. Read both before changing anything.
 
 ## License
 

{odoo_agent_cli-0.3.0 → odoo_agent_cli-0.5.0}/README.md

@@ -26,14 +26,22 @@ export ODOO_URL=https://mycompany.odoo.com ODOO_DB=mycompany \
        ODOO_LOGIN=bot@mycompany.com ODOO_API_KEY=...   # API key or password
 
 odoo info                                  # version, uid, connection source
-odoo models --like invoice                 # find the right technical name
+odoo alias                                 # business names for models, and presets
+odoo models --like invoice                 # or find the technical name yourself
 odoo fields account.move --stored          # what you can filter and order on
-odoo count account.move -w move_type=out_invoice -w payment_state=not_paid
-odoo search account.move -w move_type=out_invoice -w invoice_date_due<2026-09-01 \
+odoo count invoices -w overdue
+odoo search invoices -w overdue \
      --fields name,partner_id,amount_residual --order "invoice_date_due" --limit 20
+odoo group invoices -w unpaid --by partner_id --sum amount_residual
 ```
 
-Prefer named connections? They live in a `0600` TOML file:
+`invoices` is `account.move` filtered on `move_type = out_invoice`, and `overdue` is
+`payment_state = not_paid` past its due date. Both expand to an ordinary domain before
+anything is sent, and the technical names keep working. Full documentation:
+[Organize-IT.github.io/odoo-cli](https://github.com/Organize-IT/odoo-cli/tree/main/docs).
+
+Prefer named connections? They live in a TOML file written owner-only where the platform
+can enforce that — `odoo profile path --check` says whether it can:
 
 ```bash
 odoo profile add acme --url https://acme.odoo.com --db acme --login bot@acme.com \
@@ -50,7 +58,10 @@ First match wins, and the CLI never prompts:
 3. a profile named `default`
 
 Nothing found: exit code 3 with a message listing those three ways. A profile stores the key
-(`--api-key`) or points to an env var (`--api-key-env`). `odoo profile path` shows the file.
+(`--api-key`) or points to an env var (`--api-key-env`). `odoo profile path` shows the file,
+`--check` reports what its permissions are actually worth: mode 600 means owner-only on
+POSIX and nothing at all on Windows, where `chmod` only toggles a read-only attribute. On
+such a platform, prefer `--api-key-env` and keep the key in your secret manager.
 
 ## Output contract
 
@@ -62,6 +73,7 @@ Nothing found: exit code 3 with a message listing those three ways. A profile st
 | bad arguments | | `{"error": ...}` | 2 |
 | connection, auth, no profile | | `{"error": ...}` | 3 |
 | refused by a guard | | `{"error": ...}` | 4 |
+| query repaired to run | rows | `{"error": ...}` | 5 |
 | write executed | result | `{"write": {"model", "method", "ids", "fields"}}` | 0 |
 
 Data is never humanised: many2one fields stay `[id, "name"]`, empty values stay `false`.
@@ -75,6 +87,7 @@ Values of fields named like `password`, `api_key`, `secret` are `[redacted]` unl
 | `--company ID`, `--lang CODE`, `--context JSON` | Odoo context merged into every call |
 | `--insecure` | skip TLS verification (self-signed on-prem) |
 | `--no-redact`, `--include-sensitive` | lift the two output/model guards |
+| `--no-validate` | skip the field-name check against the model schema |
 | `--debug` | one JSON line per RPC on stderr (method, id, duration, retries) |
 | `--verbose` | include Odoo's server traceback in error output |
 
@@ -95,13 +108,76 @@ Values of fields named like `password`, `api_key`, `secret` are `[redacted]` unl
 
 Values: `true/false/null`, integers, floats, JSON lists or objects, quoted strings, else text.
 
+A bare word is looked up as a preset for the model: `-w overdue`, `-w unpaid`, `-w draft`,
+`-w confirmed`, `-w archived`. `odoo alias MODEL --presets` lists the ones that apply. A bare
+word that is not a preset exits 2 listing the ones that are.
+
+## Your own names
+
+The shipped table covers what most tenants call things. A profile file adds the rest, and a
+user entry replaces a built-in of the same name — your tenant knows its vocabulary better than
+this tool does:
+
+```toml
+[aliases.subscriptions]
+model = "sale.subscription"
+domain = [["stage_category", "=", "progress"]]
+help = "Running subscriptions"
+
+[aliases.invoices]                     # replaces the built-in
+model = "account.move"
+domain = [["move_type", "=", "out_invoice"], ["company_id", "=", 3]]
+
+[presets.mine]
+domain = [["user_id", "=", 7]]
+models = ["crm.lead", "sale.order"]
+```
+
+`odoo alias` marks each entry `builtin` or `config`. A malformed table fails the command with
+exit 2 instead of being skipped: a filter you believe is applied and is not is exactly what
+this mechanism exists to avoid. Dynamic dates work too — `@today`, `@month-start`, `@year-start`.
+
+## Names and typos
+
+Read commands accept an alias in place of a technical model name (`invoices`, `customers`,
+`quotes`, `pickings`, ...); `odoo alias` prints the table and needs no connection. Write
+commands refuse an alias that carries a filter, so a vendor bill cannot be filed as a
+customer invoice by accident.
+
+Field names are checked against the model schema before the call, which costs nothing after
+the first lookup:
+
+```console
+$ odoo search partners -w mobil=+32
+{"error": {"code": "unknown_field", "message": "res.partner has no field 'mobil'. Did you mean 'mobile'? (also: phone)"}}
+$ echo $?
+2
+```
+
+`fields_get` is read once per model and cached under `~/.cache/odoo-cli` for 24 hours
+(`odoo cache path|list|clear`, `ODOO_CACHE_DIR`, `ODOO_SCHEMA_TTL`). Dotted paths are
+followed across relations. A computed non-stored field used in `-w` or `--order` warns on
+stderr rather than failing. Validation only rejects a name it has positively read from the
+server: when the schema is unreadable it stays quiet, so it can never refuse wrongly.
+`--no-validate` or `ODOO_NO_VALIDATE=1` turns it off.
+
+## Aggregates
+
+```bash
+odoo group invoices -w overdue --by partner_id --sum amount_residual \
+     --order "amount_residual desc" --limit 10
+odoo group invoices --by invoice_date:month --sum amount_total
+```
+
+`read_group` under the hood: counts and totals per group without pulling the records.
+
 ## Writes
 
 Off by default. Enable per connection with `allow_writes = true` on the profile
 (`odoo profile add ... --allow-writes`) or `ODOO_ALLOW_WRITES=1`.
 
 ```bash
-odoo create crm.lead -v name="Website inquiry" -v partner_id=42 --dry-run   # shows payload, exit 0
+odoo create crm.lead -v name="Website inquiry" -v partner_id=42 --dry-run   # payload only, exit 0
 odoo create crm.lead -v name="Website inquiry" -v partner_id=42             # prints the new id
 odoo write res.partner 42,43 -v active=false
 odoo unlink res.partner 99 --yes                                            # --yes required
@@ -119,8 +195,9 @@ are refused unless `--include-sensitive`.
   many2one shapes) and recipes.
 - The same text ships as an [Agent Skill](https://github.com/Organize-IT/odoo-cli/blob/main/SKILL.md):
   `npx skills add Organize-IT/odoo-cli`.
-- `odoo search ... --lenient-fields` removes fields Odoo rejects and retries, with a warning on
-  stderr. Exploration only.
+- `odoo search ... --lenient-fields` removes fields Odoo rejects and retries. It prints the
+  rows, then exits **5**: they answer a wider question than the one you asked. Exploration
+  stays comfortable; a script that checks its exit codes cannot be fooled by it.
 
 ## Library
 
@@ -163,8 +240,11 @@ repair loop in `odoocli.lenient`.
 
 ```bash
 uv sync --group dev
+uvx pre-commit install               # ruff, mypy and hygiene hooks on commit
 uv run pytest                        # unit tests, mocked JSON-RPC
 uv run ruff check && uv run mypy
+uv run pytest --cov --cov-report=term-missing   # gated at 93% in CI
+uv run --group docs mkdocs serve     # the documentation site
 
 ODOO_VERSION=17.0 scripts/start-odoo.sh                     # throwaway Odoo in Docker
 ODOO_URL=http://localhost:8069 ODOO_DB=test ODOO_LOGIN=admin ODOO_API_KEY=admin \
@@ -172,9 +252,14 @@ ODOO_ALLOW_WRITES=1 uv run pytest -m integration -o addopts=""
 docker compose -f docker/odoo-compose.yml down -v
 ```
 
-CI runs the unit suite on every PR and the integration matrix (Odoo 17.0, 18.0, 19.0) on
-`main`, tags and manual dispatch. Releases are published to PyPI on `v*` tags through
-trusted publishing.
+CI runs the unit suite on Python 3.11-3.13 and builds the docs on every PR; the integration
+matrix (Odoo 17.0, 18.0, 19.0) runs on `main`, tags and manual dispatch. Releases are
+published to PyPI on `v*` tags through trusted publishing, with every action pinned to a
+commit digest.
+
+`AGENTS.md` is the specification: layering, the contracts that may not change silently, and
+the definition of done. [docs/decisions/](docs/decisions/) records the decisions with a real
+trade-off behind them. Read both before changing anything.
 
 ## License
 

{odoo_agent_cli-0.3.0 → odoo_agent_cli-0.5.0}/SKILL.md

@@ -18,6 +18,8 @@ Resolution order, first match wins:
 3. A profile named `default`
 
 Nothing resolved: exit code 3 and a message listing these three ways. The CLI never prompts.
+`odoo profile path --check` says whether the stored key is really owner-only on this
+platform; on Windows it is not, so prefer `--api-key-env` there.
 `ODOO_API_KEY` accepts an Odoo API key (preferred) or the user's password.
 Check a connection with `odoo info`. Self-signed on-prem server: `--insecure`
 (or `odoo profile add ... --no-verify-ssl`).
@@ -36,6 +38,52 @@ work on every command:
 --context '{"tz": "Europe/Brussels"}'   any other key, merged with the flags above
 ```
 
+## Business names instead of technical ones
+
+Read commands accept an alias in place of a model name, and a preset name in place of a
+condition. Both expand to an ordinary domain before anything is sent, so the result has
+exactly the same shape.
+
+```
+odoo alias                    every alias, its model and its filter (no connection needed)
+odoo alias invoices --presets the presets that apply to that model
+```
+
+```
+odoo search invoices -w overdue      same as
+odoo search account.move -w move_type=out_invoice -w payment_state=not_paid \
+                         -w invoice_date_due<TODAY
+```
+
+Aliases include `partners`, `customers`, `suppliers`, `invoices`, `bills`, `credit-notes`,
+`orders`, `quotes`, `opportunities`, `products`, `pickings`, `users`, `employees`, `tasks`.
+Presets include `overdue`, `unpaid`, `paid`, `draft`, `posted`, `cancelled`, `confirmed`,
+`this-month`, `this-year`, `ready`, `done`, and `archived` / `active` on any model.
+
+Write commands refuse an alias that carries a filter (exit 2, `alias_not_writable`): use the
+technical name and set the discriminator field yourself, so a vendor bill cannot be filed as
+a customer invoice by accident.
+
+## Field names are checked before the call
+
+A misspelled field costs no round trip. The CLI reads the model schema once with
+`fields_get`, caches it for 24 hours, and checks every name used in `-w`, `--fields`,
+`--order`, `-v` and `--by`:
+
+```
+$ odoo search partners -w mobil=+32
+{"error": {"code": "unknown_field", "message": "res.partner has no field 'mobil'.
+ Did you mean 'mobile'? (also: phone)"}}      exit 2, nothing was sent
+```
+
+Dotted paths are followed across relations, and the error names the model where the path
+actually broke. Using a computed non-stored field in `-w` or `--order` produces a
+`field_not_stored` warning on stderr and the call still goes out.
+
+Validation only ever rejects a name it has positively read from the server: if the schema
+cannot be read, it stays quiet. Turn it off with `--no-validate` or `ODOO_NO_VALIDATE=1`.
+Refresh it after a module install or an Odoo upgrade with `odoo cache clear`.
+
 ## Output contract
 
 - Piped or captured: raw Odoo JSON, exactly what `search_read`, `read` or `fields_get` return.
@@ -45,7 +93,8 @@ work on every command:
 - Errors: one JSON object on stderr, `{"error": {"code": ..., "message": ..., "odoo": {...}}}`.
 - Warnings and write logs: one JSON object per line on stderr.
 - Exit codes: `0` ok, `1` Odoo raised, `2` bad usage, `3` connection or authentication,
-  `4` refused by a guard (writes disabled, missing `--yes`, sensitive model).
+  `4` refused by a guard (writes disabled, missing `--yes`, sensitive model), `5` the query
+  was repaired to make it run, so the rows answer a wider question than the one you asked.
 - Values of fields named like `password`, `api_key`, `secret` are replaced by `[redacted]`
   unless `--no-redact`.
 
@@ -59,8 +108,16 @@ odoo search MODEL [-w COND]... [--domain JSON] [--fields a,b] [--limit N] [--off
                   [--order "x desc"] [--all] [--ids-only] [--lenient-fields]
 odoo count MODEL [-w COND]... [--domain JSON]
 odoo read MODEL ID [ID...] [--fields a,b]
+odoo group MODEL --by FIELD[,FIELD] [--sum a,b] [--avg a,b] [-w COND]... [--limit N]
+odoo alias [NAME] [--presets]               aliases and presets, offline
+odoo cache path|list|clear                  the schema cache
 ```
 
+`MODEL` accepts an alias on every read command. `odoo group` runs `read_group`, so you
+get counts and totals per group without pulling the records:
+`odoo group invoices -w overdue --by partner_id --sum amount_residual`.
+Grouping keys accept a date granularity: `--by invoice_date:month`.
+
 Conditions (`-w`, repeatable, AND-ed together, combined with `--domain`):
 
 ```
@@ -84,7 +141,8 @@ odoo unlink MODEL IDS --yes [--dry-run]
 odoo call MODEL METHOD [--ids 1,2] [--args JSON] [--kwargs JSON] [--yes] [--dry-run]
 ```
 
-- `--dry-run` prints the exact payload and exits 0 without calling Odoo. Use it first.
+- `--dry-run` prints the exact payload and exits 0 without writing anything. It does read
+  the model schema to check your field names, so a typo is caught there too. Use it first.
 - `unlink` and any `call` to a non read-only method need `--yes` (or `ODOO_ASSUME_YES=1`).
 - `call` on read-only methods (`name_search`, `read_group`, `default_get`, ...) needs
   neither `allow_writes` nor `--yes`.
@@ -103,8 +161,9 @@ One2many and many2many fields take Odoo commands, written as JSON in `-v` or `--
 
 ## Working method that avoids most failures
 
-1. Unknown model? `odoo fields MODEL` first. It shows `type`, `required`, `store`, `relation`
-   and `selection` values.
+1. Unknown model? Try `odoo alias` first, then `odoo models --like word`. Then
+   `odoo fields MODEL`, which shows `type`, `required`, `store`, `relation` and `selection`
+   values.
 2. Only filter or order on fields with `store: true`. Computed non-stored fields
    (`qty_available`, `amount_to_invoice`, ...) can be read but not searched; Odoo answers
    "Cannot convert ... to SQL". Read them and filter client-side.
@@ -117,9 +176,11 @@ One2many and many2many fields take Odoo commands, written as JSON in `-v` or `--
 6. Dates are strings, `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` in UTC.
 7. Field names drift between Odoo 17, 18 and 19 (for example `account.account.company_id`
    became `company_ids`). If a field is rejected, `odoo fields` is the truth.
-   `--lenient-fields` on `search` removes rejected fields and retries, with a warning on
-   stderr; only use it for exploration, never in a script that relies on the result.
-8. Never guess a model name: `odoo models --like invoice`.
+   `--lenient-fields` on `search` removes rejected fields and retries. It prints the rows and
+   then exits 5, because they answer a wider question than the one you asked. Use it to
+   explore; if you keep it in a script, check the exit code.
+8. Never guess a model name: `odoo alias`, then `odoo models --like invoice`. A dotless
+   name close to a known alias is reported as a typo instead of being sent.
 9. Sensitive models (`ir.config_parameter`, `ir.mail_server`, `res.users.apikeys`, `ir.cron`,
    `ir.actions.server`, ...) are refused unless `--include-sensitive`.
 10. A record you know exists but cannot find is usually archived (`--include-archived`) or in
@@ -131,6 +192,10 @@ One2many and many2many fields take Odoo commands, written as JSON in `-v` or `--
 ## Recipes
 
 ```
+odoo search customers -w country_id.code=BE --fields name,email,vat --limit 20
+odoo count invoices -w overdue
+odoo group invoices -w overdue --by partner_id --sum amount_residual --order "amount_residual desc" --limit 10
+odoo group invoices --by invoice_date:month --sum amount_total
 odoo search res.partner -w is_company=true -w country_id.code=BE --fields name,email,vat --limit 20
 odoo search sale.order -w state=sale -w date_order>=2026-01-01 --fields name,partner_id,amount_total --order "amount_total desc"
 odoo count account.move -w move_type=out_invoice -w payment_state=not_paid -w invoice_date_due<2026-09-01

{odoo_agent_cli-0.3.0 → odoo_agent_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "odoo-agent-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Odoo JSON-RPC CLI and Python client built for AI agents and scripts."
 readme = "README.md"
 license = "MIT"
@@ -44,6 +44,13 @@ dev = [
   "respx>=0.21",
   "ruff>=0.6",
   "mypy>=1.11",
+  "pytest-cov>=5",
+  "hypothesis>=6.168.0",
+]
+docs = [
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.26",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -76,6 +83,15 @@ warn_unreachable = true
 module = ["respx", "respx.*"]
 ignore_missing_imports = true
 
+[tool.coverage.run]
+source = ["odoocli"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 93
+exclude_also = ["if TYPE_CHECKING:", "raise AssertionError\\(\"unreachable\"\\)"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]