odoo-agent-cli 0.2.0__tar.gz

odoo_agent_cli-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.DS_Store

odoo_agent_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Organize-IT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

odoo_agent_cli-0.2.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: odoo-agent-cli
+Version: 0.2.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
+Author-email: Organize-IT <maxime@organizeit.be>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,erp,json-rpc,odoo
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# odoo-agent-cli
+
+Odoo JSON-RPC command line tool and Python client, built for AI agents and scripts.
+
+`odoo search res.partner -w is_company=true --fields name,email` prints exactly what Odoo
+returns. stdout is data only, stderr is diagnostics, exit codes mean something, and nothing
+writes to your ERP unless you switched writes on for that connection.
+
+Extracted from the connector that powers [UpBoard.ai](https://upboard.ai). Not affiliated with
+Odoo S.A.
+
+## Install
+
+```bash
+uv tool install odoo-agent-cli   # or: pipx install odoo-agent-cli
+odoo --version
+```
+
+Requires Python 3.11+. Works with Odoo 17, 18 and 19 (integration-tested in CI), and should
+work with any version exposing `/jsonrpc` with API keys (14+).
+
+## 60 seconds
+
+```bash
+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 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 \
+     --fields name,partner_id,amount_residual --order "invoice_date_due" --limit 20
+```
+
+Prefer named connections? They live in a `0600` TOML file:
+
+```bash
+odoo profile add acme --url https://acme.odoo.com --db acme --login bot@acme.com \
+     --api-key-env ACME_ODOO_KEY --test
+odoo -p acme search res.partner -w name~acme
+```
+
+## Connection resolution
+
+First match wins, and the CLI never prompts:
+
+1. `--profile NAME` or `ODOO_PROFILE=NAME`
+2. `ODOO_URL`, `ODOO_DB`, `ODOO_LOGIN`, `ODOO_API_KEY`
+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.
+
+## Output contract
+
+| Situation | stdout | stderr | exit |
+|---|---|---|---|
+| piped / captured | raw Odoo JSON (`--format json` by default) | | 0 |
+| terminal | table (`--format table`), `jsonl` and `csv` available | | 0 |
+| Odoo raised | | `{"error": {"code", "message", "odoo": {...}}}` | 1 |
+| bad arguments | | `{"error": ...}` | 2 |
+| connection, auth, no profile | | `{"error": ...}` | 3 |
+| refused by a guard | | `{"error": ...}` | 4 |
+| write executed | result | `{"write": {"model", "method", "ids", "fields"}}` | 0 |
+
+Data is never humanised: many2one fields stay `[id, "name"]`, empty values stay `false`.
+Values of fields named like `password`, `api_key`, `secret` are `[redacted]` unless
+`--no-redact`. Global options are accepted anywhere on the command line:
+
+| Option | Effect |
+|---|---|
+| `--profile/-p NAME`, `--format/-f FMT`, `--timeout S` | connection, output, per-call timeout |
+| `--include-archived` | context `active_test=false`: searches also return archived records |
+| `--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 |
+| `--debug` | one JSON line per RPC on stderr (method, id, duration, retries) |
+| `--verbose` | include Odoo's server traceback in error output |
+
+## Conditions
+
+`-w` is repeatable and AND-ed; `--domain` takes a raw Odoo domain (use it for OR).
+
+| `-w` | Odoo leaf |
+|---|---|
+| `is_company=true` | `["is_company", "=", true]` |
+| `amount_total>=1000` | `["amount_total", ">=", 1000]` |
+| `name~acme` / `name!~acme` | `["name", "ilike", "acme"]` / `not ilike` |
+| `state in draft,sent` | `["state", "in", ["draft", "sent"]]` |
+| `email=null` | `["email", "=", false]` |
+| `partner_id.country_id.code=BE` | `["partner_id.country_id.code", "=", "BE"]` |
+| `tag_ids in [1,2]` | `["tag_ids", "in", [1, 2]]` |
+| `parent_id child_of 5` | `["parent_id", "child_of", 5]` |
+
+Values: `true/false/null`, integers, floats, JSON lists or objects, quoted strings, else text.
+
+## 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             # prints the new id
+odoo write res.partner 42,43 -v active=false
+odoo unlink res.partner 99 --yes                                            # --yes required
+odoo call sale.order action_confirm --ids 12 --yes                          # any method
+odoo call res.partner name_search --args '["acme"]' --kwargs '{"limit": 5}' # read-only: no guard
+```
+
+`unlink` and any `call` to a non read-only method need `--yes` or `ODOO_ASSUME_YES=1`.
+Sensitive models (`ir.config_parameter`, `ir.mail_server`, `res.users.apikeys`, `ir.cron`, ...)
+are refused unless `--include-sensitive`.
+
+## For AI agents
+
+- `odoo agent-guide` prints the working method, pitfalls (non-stored fields, version drift,
+  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.
+
+## Library
+
+The distribution is `odoo-agent-cli`; the import name is `odoocli`.
+
+```python
+from odoocli import OdooClient
+
+with OdooClient("https://acme.odoo.com", "acme", "bot@acme.com", "api-key") as odoo:
+    overdue = odoo.search_read(
+        "account.move",
+        [["move_type", "=", "out_invoice"], ["payment_state", "=", "not_paid"]],
+        ["name", "partner_id", "amount_residual"],
+        limit=50,
+        order="invoice_date_due",
+    )
+```
+
+```python
+from odoocli import AsyncOdooClient, OdooAccessError
+
+async with AsyncOdooClient(url, db, login, key) as odoo:
+    try:
+        new_id = await odoo.create("res.partner", {"name": "Acme"})
+    except OdooAccessError as e:
+        print(e.code, e.message, e.data)
+```
+
+Exceptions: `OdooError` (base, `.code`, `.message`, `.data`), `OdooConnectionError`,
+`OdooAuthError`, `OdooAccessError`, `OdooValidationError`, `OdooMissingError`.
+
+Both clients accept `context={...}` (merged into every call; a per-call `context=` keyword
+wins), `verify_ssl=False` and `max_retries`. HTTP 429 is always retried with backoff and
+`Retry-After`; network errors, timeouts and HTTP 5xx are retried only for calls that cannot
+change data, so a `create` that timed out is never replayed. Logs go to the `odoocli.rpc`
+logger. Domain helpers live in `odoocli.domain`, guards in `odoocli.security`, the opt-in
+repair loop in `odoocli.lenient`.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest                        # unit tests, mocked JSON-RPC
+uv run ruff check && uv run mypy
+
+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 \
+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.
+
+## License
+
+MIT. Odoo is a trademark of Odoo S.A.; this project is independent.

odoo_agent_cli-0.2.0/README.md

@@ -0,0 +1,181 @@
+# odoo-agent-cli
+
+Odoo JSON-RPC command line tool and Python client, built for AI agents and scripts.
+
+`odoo search res.partner -w is_company=true --fields name,email` prints exactly what Odoo
+returns. stdout is data only, stderr is diagnostics, exit codes mean something, and nothing
+writes to your ERP unless you switched writes on for that connection.
+
+Extracted from the connector that powers [UpBoard.ai](https://upboard.ai). Not affiliated with
+Odoo S.A.
+
+## Install
+
+```bash
+uv tool install odoo-agent-cli   # or: pipx install odoo-agent-cli
+odoo --version
+```
+
+Requires Python 3.11+. Works with Odoo 17, 18 and 19 (integration-tested in CI), and should
+work with any version exposing `/jsonrpc` with API keys (14+).
+
+## 60 seconds
+
+```bash
+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 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 \
+     --fields name,partner_id,amount_residual --order "invoice_date_due" --limit 20
+```
+
+Prefer named connections? They live in a `0600` TOML file:
+
+```bash
+odoo profile add acme --url https://acme.odoo.com --db acme --login bot@acme.com \
+     --api-key-env ACME_ODOO_KEY --test
+odoo -p acme search res.partner -w name~acme
+```
+
+## Connection resolution
+
+First match wins, and the CLI never prompts:
+
+1. `--profile NAME` or `ODOO_PROFILE=NAME`
+2. `ODOO_URL`, `ODOO_DB`, `ODOO_LOGIN`, `ODOO_API_KEY`
+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.
+
+## Output contract
+
+| Situation | stdout | stderr | exit |
+|---|---|---|---|
+| piped / captured | raw Odoo JSON (`--format json` by default) | | 0 |
+| terminal | table (`--format table`), `jsonl` and `csv` available | | 0 |
+| Odoo raised | | `{"error": {"code", "message", "odoo": {...}}}` | 1 |
+| bad arguments | | `{"error": ...}` | 2 |
+| connection, auth, no profile | | `{"error": ...}` | 3 |
+| refused by a guard | | `{"error": ...}` | 4 |
+| write executed | result | `{"write": {"model", "method", "ids", "fields"}}` | 0 |
+
+Data is never humanised: many2one fields stay `[id, "name"]`, empty values stay `false`.
+Values of fields named like `password`, `api_key`, `secret` are `[redacted]` unless
+`--no-redact`. Global options are accepted anywhere on the command line:
+
+| Option | Effect |
+|---|---|
+| `--profile/-p NAME`, `--format/-f FMT`, `--timeout S` | connection, output, per-call timeout |
+| `--include-archived` | context `active_test=false`: searches also return archived records |
+| `--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 |
+| `--debug` | one JSON line per RPC on stderr (method, id, duration, retries) |
+| `--verbose` | include Odoo's server traceback in error output |
+
+## Conditions
+
+`-w` is repeatable and AND-ed; `--domain` takes a raw Odoo domain (use it for OR).
+
+| `-w` | Odoo leaf |
+|---|---|
+| `is_company=true` | `["is_company", "=", true]` |
+| `amount_total>=1000` | `["amount_total", ">=", 1000]` |
+| `name~acme` / `name!~acme` | `["name", "ilike", "acme"]` / `not ilike` |
+| `state in draft,sent` | `["state", "in", ["draft", "sent"]]` |
+| `email=null` | `["email", "=", false]` |
+| `partner_id.country_id.code=BE` | `["partner_id.country_id.code", "=", "BE"]` |
+| `tag_ids in [1,2]` | `["tag_ids", "in", [1, 2]]` |
+| `parent_id child_of 5` | `["parent_id", "child_of", 5]` |
+
+Values: `true/false/null`, integers, floats, JSON lists or objects, quoted strings, else text.
+
+## 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             # prints the new id
+odoo write res.partner 42,43 -v active=false
+odoo unlink res.partner 99 --yes                                            # --yes required
+odoo call sale.order action_confirm --ids 12 --yes                          # any method
+odoo call res.partner name_search --args '["acme"]' --kwargs '{"limit": 5}' # read-only: no guard
+```
+
+`unlink` and any `call` to a non read-only method need `--yes` or `ODOO_ASSUME_YES=1`.
+Sensitive models (`ir.config_parameter`, `ir.mail_server`, `res.users.apikeys`, `ir.cron`, ...)
+are refused unless `--include-sensitive`.
+
+## For AI agents
+
+- `odoo agent-guide` prints the working method, pitfalls (non-stored fields, version drift,
+  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.
+
+## Library
+
+The distribution is `odoo-agent-cli`; the import name is `odoocli`.
+
+```python
+from odoocli import OdooClient
+
+with OdooClient("https://acme.odoo.com", "acme", "bot@acme.com", "api-key") as odoo:
+    overdue = odoo.search_read(
+        "account.move",
+        [["move_type", "=", "out_invoice"], ["payment_state", "=", "not_paid"]],
+        ["name", "partner_id", "amount_residual"],
+        limit=50,
+        order="invoice_date_due",
+    )
+```
+
+```python
+from odoocli import AsyncOdooClient, OdooAccessError
+
+async with AsyncOdooClient(url, db, login, key) as odoo:
+    try:
+        new_id = await odoo.create("res.partner", {"name": "Acme"})
+    except OdooAccessError as e:
+        print(e.code, e.message, e.data)
+```
+
+Exceptions: `OdooError` (base, `.code`, `.message`, `.data`), `OdooConnectionError`,
+`OdooAuthError`, `OdooAccessError`, `OdooValidationError`, `OdooMissingError`.
+
+Both clients accept `context={...}` (merged into every call; a per-call `context=` keyword
+wins), `verify_ssl=False` and `max_retries`. HTTP 429 is always retried with backoff and
+`Retry-After`; network errors, timeouts and HTTP 5xx are retried only for calls that cannot
+change data, so a `create` that timed out is never replayed. Logs go to the `odoocli.rpc`
+logger. Domain helpers live in `odoocli.domain`, guards in `odoocli.security`, the opt-in
+repair loop in `odoocli.lenient`.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest                        # unit tests, mocked JSON-RPC
+uv run ruff check && uv run mypy
+
+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 \
+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.
+
+## License
+
+MIT. Odoo is a trademark of Odoo S.A.; this project is independent.

odoo_agent_cli-0.2.0/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: odoo-cli
+description: Use when a task needs to read or change data in an Odoo ERP (partners, invoices, orders, stock, any model) through the `odoo` command line tool from the odoo-agent-cli package (import name odoocli). Covers connection setup, domain syntax, guarded writes, output contract and version-drift pitfalls.
+---
+
+# odoo CLI guide for AI agents
+
+`odoo` talks to one Odoo database over JSON-RPC. It is built so that a program can drive it:
+stdout is data only, stderr is diagnostics, exit codes mean something.
+
+## Connection
+
+Resolution order, first match wins:
+
+1. `--profile NAME` or `ODOO_PROFILE=NAME`, defined with
+   `odoo profile add NAME --url https://... --db DB --login USER --api-key KEY`
+2. Environment: `ODOO_URL`, `ODOO_DB`, `ODOO_LOGIN`, `ODOO_API_KEY`
+3. A profile named `default`
+
+Nothing resolved: exit code 3 and a message listing these three ways. The CLI never prompts.
+`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`).
+
+## Context: archived records, company, language
+
+Odoo hides archived records (`active = false`) from every search unless the context says
+otherwise, and multi-company data depends on the company in context. These global flags
+work on every command:
+
+```
+--include-archived        context active_test=false: search also returns archived records
+--company 3               context allowed_company_ids=[3]
+--lang fr_BE              labels and selection values in that language (must be installed
+                          in Odoo: 18+ answers "Invalid language code" otherwise)
+--context '{"tz": "Europe/Brussels"}'   any other key, merged with the flags above
+```
+
+## Output contract
+
+- Piped or captured: raw Odoo JSON, exactly what `search_read`, `read` or `fields_get` return.
+  Many2one fields are `[id, "display name"]`, empty values are `false`, never `null`.
+- On a terminal: a table. Force a format with `--format json|jsonl|table|csv`.
+  Use `--format jsonl` for large result sets.
+- 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).
+- Values of fields named like `password`, `api_key`, `secret` are replaced by `[redacted]`
+  unless `--no-redact`.
+
+## Read commands
+
+```
+odoo info [--modules]                       server version, uid, optional installed modules
+odoo models [--like sale]                   list models (technical name, label)
+odoo fields MODEL [--type many2one] [--stored] [--search text] [--all-attributes]
+odoo search MODEL [-w COND]... [--domain JSON] [--fields a,b] [--limit N] [--offset N]
+                  [--order "x desc"] [--all] [--ids-only] [--lenient-fields]
+odoo count MODEL [-w COND]... [--domain JSON]
+odoo read MODEL ID [ID...] [--fields a,b]
+```
+
+Conditions (`-w`, repeatable, AND-ed together, combined with `--domain`):
+
+```
+-w is_company=true         -w amount_total>=1000      -w name~acme        (ilike)
+-w name!~test              -w state in draft,sent     -w state not in done,cancel
+-w email=null              -w partner_id.country_id.code=BE
+-w tag_ids in [1,2]        -w parent_id child_of 5
+```
+
+For OR, use `--domain` with Odoo prefix notation: `--domain '["|",["a","=",1],["b","=",2]]'`.
+
+## Write commands
+
+Writes only exist when the profile has `allow_writes = true` or `ODOO_ALLOW_WRITES=1`.
+Otherwise exit 4.
+
+```
+odoo create MODEL -v name=Acme -v is_company=true [--values JSON] [--dry-run]
+odoo write MODEL IDS -v field=value... [--values JSON] [--dry-run]
+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.
+- `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`.
+- Every executed write logs one line on stderr:
+  `{"write": {"model": ..., "method": ..., "ids": [...], "fields": [...]}}`.
+
+One2many and many2many fields take Odoo commands, written as JSON in `-v` or `--values`:
+
+```
+-v 'order_line=[[0,0,{"product_id":7,"product_uom_qty":2}]]'   create a line
+-v 'tag_ids=[[4,12]]'                                           link id 12
+-v 'tag_ids=[[6,0,[12,13]]]'                                    replace with ids 12 and 13
+-v 'tag_ids=[[3,12]]'                                           unlink id 12 (keep record)
+-v 'order_line=[[2,55]]'                                        delete line 55
+```
+
+## Working method that avoids most failures
+
+1. Unknown model? `odoo fields MODEL` first. It 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.
+3. `odoo count` before a wide `odoo search`. Default `--limit` is 80. `--all` paginates
+   everything; prefer `--format jsonl` with it. `--ids-only` when you only need ids.
+4. Ask only for the fields you need with `--fields`. `search` without `--fields` returns
+   every field, which is slow and noisy.
+5. Many2one values come back as `[id, name]`. Filter on them with the id
+   (`-w partner_id=42`) or through a related field (`-w partner_id.name~acme`).
+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`.
+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
+    another company (`--company`). `odoo read` exits 1 with `missing_record` in that case.
+11. Something odd on the wire? `--debug` logs every RPC call (method, duration, retries) as
+    JSON lines on stderr. Network errors and HTTP 5xx are retried for reads only; a write that
+    timed out is reported, never replayed.
+
+## Recipes
+
+```
+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 search product.product --fields name,qty_available --all --format jsonl | jq -c 'select(.qty_available < 0)'
+odoo call res.partner name_search --args '["acme"]' --kwargs '{"limit": 5}'
+odoo call account.move read_group --kwargs '{"domain": [["move_type","=","out_invoice"]], "fields": ["amount_total:sum"], "groupby": ["partner_id"]}'
+odoo create crm.lead -v name="Website inquiry" -v partner_id=42 --dry-run
+odoo call sale.order action_confirm --ids 12 --yes
+odoo call sale.order action_cancel --ids 12 --yes --context '{"disable_cancel_warning": true}'
+odoo search res.partner -w name~acme --include-archived --ids-only
+```

odoo_agent_cli-0.2.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "odoo-agent-cli"
+version = "0.2.0"
+description = "Odoo JSON-RPC CLI and Python client built for AI agents and scripts."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Organize-IT", email = "maxime@organizeit.be" }]
+keywords = ["odoo", "cli", "json-rpc", "agents", "erp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27",
+  "typer>=0.12",
+  "rich>=13",
+  "tomli-w>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Organize-IT/odoo-cli"
+Issues = "https://github.com/Organize-IT/odoo-cli/issues"
+
+[project.scripts]
+odoo = "odoocli.cli.app:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "respx>=0.21",
+  "ruff>=0.6",
+  "mypy>=1.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/odoocli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/odoocli", "README.md", "LICENSE", "SKILL.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "ARG", "SIM"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["typer.Argument", "typer.Option"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ARG001"]  # pytest fixtures are used for their side effects
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests"]
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = ["respx", "respx.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["integration: needs a live Odoo (ODOO_URL, ODOO_DB, ODOO_LOGIN, ODOO_API_KEY)"]
+addopts = "-m 'not integration'"