Skip to content

Two transports

odoo-work-cli talks to Odoo in two ways. Most commands use XML-RPC with an API key. clock in and clock out use a web session with your password, like the browser. This page explains why.

flowchart LR
  CLI[odoo-work-cli]
  CLI -- "XML-RPC, API key<br/>projects, tasks, entries,<br/>clock list/edit/add/status" --> M["/xmlrpc/2/object<br/>models"]
  CLI -- "JSON-RPC, password + TOTP<br/>clock in, clock out" --> S["/web/session/authenticate<br/>/hr_attendance/systray_check_in_out"]

XML-RPC for the models

Projects, tasks, timesheet entries (account.analytic.line) and attendance records (hr.attendance) are Odoo models. Odoo's external API reads and writes them over XML-RPC with execute_kw, and the CLI uses only that low-level API.

Odoo 17 requires an API key here. Your login password is not accepted, and the failure is silent: authenticate returns false without a reason. That is the most common setup mistake; see Troubleshoot.

Access rights apply as in the browser. A regular employee may read their own attendance records, but not create or change them over the API. That needs the Attendance Officer right; see Clock in and out → Permissions.

A web session for clocking in and out

Clocking in and out is exactly what a regular employee may not do over XML-RPC: it creates and changes hr.attendance records. In the browser it works anyway, because the attendance button in the systray calls a controller (/hr_attendance/systray_check_in_out) that acts with elevated rights on your own behalf.

The CLI calls that same controller. A controller is not part of the external API, so the CLI logs in like the browser: /web/session/authenticate over JSON-RPC, then, with 2FA, the TOTP step, then the call with the session cookie. That login is the exact opposite of XML-RPC: it rejects API keys and wants the real password.

So clock in and clock out work for every employee, and they need the password (and the TOTP secret). Backdating with --at, clock edit and clock add cannot use the controller, which only knows "now"; they write the model over XML-RPC and need the officer right instead.

If the session expires while the TUI is open, the CLI logs in again.

Why not one transport

  • XML-RPC only would leave regular employees without clock in and out.
  • The web session only would need the password for every command and the TOTP step for every call, and controllers do not cover projects, tasks and timesheets the way the model API does.

Two transports keep the common case (reading and booking) on the API key, and use the password only where Odoo leaves no other way.

Version drift

The web login is not a public API; its details can change between Odoo versions. A canary test checks the whole login flow against a development instance before an Odoo upgrade reaches production.