odoo-lens

A small TypeScript client + CLI for reading data from an Odoo instance via the XML-RPC API.

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-2441218"]]' --fields '["name","state"]' --limit 1

(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://34.44.44.444
• ODOO_XMLRPC_INSECURE_TLS=true
• ODOO_XMLRPC_SERVERNAME=portal.example.com

Notes:

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

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.