Vodoo

Modern Python library and CLI for Odoo

---

Vodoo is a typed Python library and CLI for interacting with Odoo instances via JSON-RPC (Odoo 17–18) and JSON-2 (Odoo 19+). It covers helpdesk tickets, project tasks, projects, CRM leads/opportunities, knowledge articles, and timesheets.

Highlights

• Dual-use — works as a CLI tool and as an importable Python library
• Sync + Async — full async API under vodoo.aio with httpx
• Auto-detecting transport — JSON-2 for Odoo 19+ (~3-4× faster), legacy JSON-RPC for 17–18
• AI-first design — clear command structure for Claude Code and similar assistants
• Fully typed — strict mypy, Pydantic models, rich terminal output
• Comprehensive — CRUD, comments, notes, tags, attachments, timers, security groups
• Rich exceptions — Odoo server errors mapped to typed Python exceptions

Odoo Version Support

Version	Protocol	Status
Odoo 17	Legacy JSON-RPC	Fully tested
Odoo 18	Legacy JSON-RPC	Fully tested
Odoo 19	JSON-2 (bearer auth)	Fully tested

Quick Example

CLIPython Library

# List helpdesk tickets
vodoo helpdesk list --stage "In Progress"

# Add a comment to a CRM lead
vodoo crm comment 42 "Following up on the proposal"

# Start a timer on a task
vodoo timer start 15

from vodoo import OdooClient, OdooConfig

config = OdooConfig(
    url="https://my.odoo.com",
    database="mydb",
    username="bot@example.com",
    password="api-key-here",
)
client = OdooClient(config)

# Search partners
partners = client.search_read(
    "res.partner",
    domain=[["email", "ilike", "@acme.com"]],
    fields=["name", "email"],
    limit=10,
)

# Use domain helpers
tickets = client.helpdesk.list(limit=5)

What's Next?

• Install Vodoo

  ---

  Install via pip, pipx, or uvx in under a minute.

  Installation

• Configure

  ---

  Set up credentials and connect to your Odoo instance.

  Configuration

• CLI Reference

  ---

  All commands, options, and examples.

  CLI Reference

• API Reference

  ---

  Auto-generated from source — every class, function, and type.

  API Reference