odoo-lens

A small TypeScript client + CLI for reading data from an Odoo instance via the JSON-RPC API (Odoo /jsonrpc).

The higher-level goal is to make it easy for LLMs and coding agents (and humans) to fetch structured Odoo data on demand, so they can answer questions like:

• What is the current status of order EC-...?
• Which picking is blocking shipment?
• What fields exist on a model?

Usage

You can run odoo-lens directly via npx without installing it.

npx odoo-lens list-models --like sale.order

Search and read records:

npx odoo-lens search-read sale.order '[["name","=","EC-0000000"]]' --fields '["name","state"]' --limit 1

Examples you can copy/paste:

# Latest RMAs (returns)
npx odoo-lens search-read rma.order '[]' --fields '["name","state","partner_id","date_rma"]' --limit 5

# Find a customer by email
npx odoo-lens search-read res.partner '[["email","=","[email protected]"]]' --fields '["id","name","email","phone","street","city","state_id","zip"]' --limit 5

Runnables scripts (repo checkout): see ./examples.

(You can also install it globally via npm install -g odoo-lens and run odoo-lens version)

Configuration

odoo-lens needs connection details to communicate with your Odoo instance.

By default, it looks for environment variables, a .env file, and a .env.local file (which overrides .env) in your current working directory.

Required keys:

• ODOO_URL (or url)
• ODOO_DB (or database)
• ODOO_USERNAME (or username)
• ODOO_PASSWORD (or password)

Example .env.local:

ODOO_URL=https://my-odoo.example.com
ODOO_DB=my_database
ODOO_USERNAME=admin
ODOO_PASSWORD=supersecret

You can specify a custom env file:

npx odoo-lens --dotenv ./.env.prod version

Direct-IP / self-signed TLS mode

If your Odoo instance is behind a WAF/Cloudflare on the public hostname, you may need to use direct IP access:

• ODOO_URL=https://203.0.113.10
• ODOO_RPC_INSECURE_TLS=true
• ODOO_RPC_SERVERNAME=odoo.example.com

Notes:

• ODOO_RPC_INSECURE_TLS=true disables TLS certificate verification (required for self-signed certs).
• ODOO_RPC_SERVERNAME is used for TLS SNI and will also be sent as the HTTP Host header.

Optional request headers

If required (WAF allowlist headers, cookies, custom user agent, etc.), you can pass additional HTTP headers for JSON-RPC requests:

• ODOO_RPC_HEADERS as JSON, e.g. { "X-Foo": "bar" }
• ODOO_RPC_COOKIE for a raw Cookie header value
• ODOO_RPC_USER_AGENT for a custom User-Agent

Legacy environment variables

This project used to use XML-RPC. For backwards compatibility, the following legacy env vars are still supported and map to the JSON-RPC HTTP request settings:

• ODOO_XMLRPC_HEADERS -> ODOO_RPC_HEADERS
• ODOO_XMLRPC_COOKIE -> ODOO_RPC_COOKIE
• ODOO_XMLRPC_USER_AGENT -> ODOO_RPC_USER_AGENT
• ODOO_XMLRPC_INSECURE_TLS -> ODOO_RPC_INSECURE_TLS
• ODOO_XMLRPC_SERVERNAME -> ODOO_RPC_SERVERNAME

How it works (JSON-RPC)

Internally, odoo-lens calls Odoo's JSON-RPC endpoint:

• POST /jsonrpc with common.authenticate to get a uid
• POST /jsonrpc with object.execute_kw for model methods like search_read, read_group, etc.

This is the same API the Odoo web client uses, and it tends to work better than XML-RPC in environments that require extra HTTP headers (WAF allowlists, direct-IP host override, etc.).

Example outputs (redacted)

examples/customer-by-email.ts:

{
  "email": "[email protected]",
  "count": 1,
  "partners": [
    {
      "id": 123,
      "name": "Example Customer",
      "email": "[email protected]",
      "phone": "(***) ***-****",
      "street": "...",
      "city": "...",
      "state_id": [1, "..."],
      "zip": "..."
    }
  ]
}

examples/latest-rmas.ts:

{
  "count": 5,
  "rmas": [
    {
      "id": 1,
      "name": "RMA/0001",
      "state": "draft",
      "partner_id": [1, "..."],
      "date_rma": false
    }
  ]
}

Local Development

If you want to contribute or modify odoo-lens locally:

1. Clone the repository
2. Install dependencies: pnpm install
3. Create your .env.local

Run the CLI via the source files:

pnpm dev -- version
pnpm dev -- list-models --like stock.picking

Testing & Building

Run tests and typecheck:

pnpm test
pnpm typecheck

Build the project:

pnpm build

Verify release readiness (runs typecheck, tests, and build):

pnpm release:check

Security

• Never commit .env or .env.local.
• Prefer environment variables for CI.

Troubleshooting

JSON-RPC returns HTML instead of JSON

If you see errors like Unexpected token < in JSON at position 0 (or similar), the server likely returned HTML (commonly a WAF / Cloudflare challenge page) instead of JSON.

Try direct-IP mode (above) and/or ensure the /jsonrpc endpoint is allowlisted.