odoo-agent-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{odoo_agent_cli-0.2.0 → odoo_agent_cli-0.4.0}/.gitignore

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

{odoo_agent_cli-0.2.0 → odoo_agent_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: odoo-agent-cli
-Version: 0.2.0
+Version: 0.4.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,13 +53,20 @@ 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
 ```
 
+`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 `0600` TOML file:
 
 ```bash
@@ -102,6 +109,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 +130,51 @@ 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.
+
+## 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
@@ -190,8 +236,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 +248,13 @@ 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. Read it before changing anything.
 
 ## License
 

{odoo_agent_cli-0.2.0 → odoo_agent_cli-0.4.0}/README.md

@@ -26,13 +26,20 @@ 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
 ```
 
+`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 `0600` TOML file:
 
 ```bash
@@ -75,6 +82,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 +103,51 @@ 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.
+
+## 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
@@ -163,8 +209,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 +221,13 @@ 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. Read it before changing anything.
 
 ## License
 

{odoo_agent_cli-0.2.0 → odoo_agent_cli-0.4.0}/SKILL.md

@@ -36,6 +36,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.
@@ -59,8 +105,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 +138,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 +158,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.
@@ -119,7 +175,8 @@ One2many and many2many fields take Odoo commands, written as JSON in `-v` or `--
    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`.
+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 +188,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.2.0 → odoo_agent_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "odoo-agent-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Odoo JSON-RPC CLI and Python client built for AI agents and scripts."
 readme = "README.md"
 license = "MIT"
@@ -44,6 +44,12 @@ dev = [
   "respx>=0.21",
   "ruff>=0.6",
   "mypy>=1.11",
+  "pytest-cov>=5",
+]
+docs = [
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.26",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -76,6 +82,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"]

{odoo_agent_cli-0.2.0 → odoo_agent_cli-0.4.0}/src/odoocli/AGENT_GUIDE.md

@@ -31,6 +31,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.
@@ -54,8 +100,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`):
 
 ```
@@ -79,7 +133,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`.
@@ -98,8 +153,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.
@@ -114,7 +170,8 @@ One2many and many2many fields take Odoo commands, written as JSON in `-v` or `--
    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`.
+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
@@ -126,6 +183,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.2.0 → odoo_agent_cli-0.4.0}/src/odoocli/_version.py

@@ -1,3 +1,3 @@
 """Single source of the package version (kept import-free to avoid cycles)."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"