Commands¶
NAME¶
odoo-work-cli - Book Odoo 17 timesheets and attendance from the terminal
SYNOPSIS¶
DESCRIPTION¶
odoo-work-cli reads and writes your own Odoo 17 timesheet entries and attendance records: list projects and tasks, book, change and delete timesheet entries, clock in and out, and correct attendance afterwards. The tui command opens an interactive weekly grid.
Every command that prints data prints a table for humans by default and a stable JSON contract with --json or --format json|jsonl, for scripts and coding agents. Write commands validate their input before they connect; entries add and entries update can show the result first with --dry-run.
Models are read and written over XML-RPC with an Odoo API key. Clock in and clock out without --at use the web session of the Odoo attendance systray, which needs the login password and, with two-factor authentication, the TOTP secret. Secrets can be resolved from 1Password at startup ([op_secrets]).
--backend fake (or ODOO_WORK_CLI_BACKEND=fake) replaces Odoo by a local file with made-up data; nothing leaves the machine.
COMMANDS¶
Timesheets¶
odoo-work-cli entries- List individual timesheet entries with full detail.
odoo-work-cli entries add- Create a new timesheet entry.
odoo-work-cli entries delete- Delete a timesheet entry.
odoo-work-cli entries update- Update an existing timesheet entry.
odoo-work-cli timesheets- List Odoo timesheets for a week.
odoo-work-cli tui- Interactive weekly timesheet view.
Attendance¶
odoo-work-cli clock- Clock in/out and attendance status.
odoo-work-cli clock add- Add an attendance record (e.g. the second half of a day with a break).
odoo-work-cli clock edit- Edit an attendance record's check-in/check-out time.
odoo-work-cli clock in- Clock in (start attendance).
odoo-work-cli clock list- List attendance records of a day or week.
odoo-work-cli clock out- Clock out (end attendance).
odoo-work-cli clock status- Show current attendance status.
Projects and tasks¶
odoo-work-cli projects- List Odoo projects.
odoo-work-cli tasks- List Odoo tasks.
Configuration¶
odoo-work-cli config- Show discovered config files and merged configuration.
odoo-work-cli config install- Create a default config file in the platform config directory.
odoo-work-cli fields- Inspect Odoo model fields.
odoo-work-cli whoami- Show current Odoo user info.
Agents and LLMs¶
odoo-work-cli llm- Print a usage guide for LLM agents (--skill).
odoo-work-cli mcp- Run the MCP server on stdin/stdout (started by the MCP client).
odoo-work-cli mcp print- Print the MCP client configuration for this server.
Shell completion¶
odoo-work-cli completion- Generate the autocompletion script for the specified shell.
GLOBAL OPTIONS¶
Every command accepts --config, --backend and --help. Commands that print data also accept --json and --format.
--formatFORMAT-
Output FORMAT: table, json or jsonl.
one of table, json, jsonl; optional; default: table
--json-
Shorthand for --format json.
flag; optional
--backendBACKEND-
BACKEND: odoo or fake (offline, made-up data; env ODOO_WORK_CLI_BACKEND).
string; optional; default: odoo; env: ODOO_WORK_CLI_BACKEND
--configFILE-
Read only the config FILE (skip discovery).
string; optional
-h,--help- Print the help of the command and exit.
-v,--version- Print the version and exit.
ENVIRONMENT¶
ODOO_URL- Odoo server URL; overrides url from the config files.
ODOO_DATABASE- Odoo database name; overrides database.
ODOO_USERNAME- Odoo login, usually an e-mail address; overrides username.
ODOO_PASSWORD- Odoo API key, used for XML-RPC. Despite the name, not the login password.
ODOO_WEB_PASSWORD- Odoo login password, used for the web session of clock in and clock out.
ODOO_TOTP_SECRET- TOTP secret (base32 or otpauth:// URL) for accounts with two-factor authentication.
ODOO_OP_TIMEOUT- Timeout of the 1Password call that resolves [op_secrets], a Go duration; default 5s.
ODOO_WORK_CLI_NO_OP- If 1, true, yes or on, [op_secrets] is ignored and the 1Password CLI is never called.
ODOO_WORK_CLI_BACKEND- Backend, odoo (default) or fake; --backend overrides it.
ODOO_WORK_CLI_FAKE_STATE- State file of the fake backend; default odoo-work-cli-fake-state.json in the temporary directory.
XDG_CONFIG_HOME- Base directory of the global config file; default ~/.config.
ODOO_WORK_CLI_MCP_SECRETS- When the MCP server resolves 1Password secrets: lazy (first tool call, default) or eager (at server start); mcp --secrets overrides it.
FILES¶
~/.config/odoo-work-cli/config.toml- Global configuration ($XDG_CONFIG_HOME/odoo-work-cli/config.toml if XDG_CONFIG_HOME is set). Created by odoo-work-cli config install.
.odoo-work-cli.toml- Configuration of a directory tree. Every such file from the filesystem root down to the current directory is merged over the global file, the deepest last. --config FILE loads only FILE instead.
$TMPDIR/odoo-work-cli-fake-state.json- State of the fake backend (--backend fake); ODOO_WORK_CLI_FAKE_STATE sets another path. Delete it to start over with the seed data.
EXIT STATUS¶
0 on success, 1 on any error, including usage errors. With --json or --format json|jsonl the error is printed on standard output as one JSON object, {"error": {"kind": KIND, "message": TEXT}}, and nothing on standard error; otherwise as "Error: TEXT" on standard error, after usage errors followed by the usage.
Error kinds (the kind field of the JSON error):
auth- Authentication failed: wrong API key or login password, TOTP rejected.
access_denied- Odoo's access rules forbid the operation, e.g. attendance writes without the Attendance Officer right.
not_found- The record does not exist or is not visible.
validation- Invalid input: unknown flag, bad argument, malformed date, time or hours, a time in the future, an unknown project.
conflict- The request contradicts the current state, e.g. clock in while clocked in, or an overlapping attendance record.
network- Odoo cannot be reached: DNS, connection refused, timeout, TLS.
config- The local configuration is missing or invalid.
secrets_locked- 1Password is locked or unreachable, so op:// references could not be resolved.
internal- Anything else: an unexpected Odoo response or a bug.
EXAMPLES¶
Who am I, on the offline fake backend:
$ odoo-work-cli --backend fake whoami
ID: 2
Name: Alex Demo
Login: alex.demo@example.invalid
Email: alex.demo@example.invalid
Company: Example Consulting
The bookings of one day:
$ odoo-work-cli --backend fake entries --date 2026-04-08
Date: 2026-04-08
ID Date ProjID Project TaskID Task Hours Status Description
-------- ------------ -------- ------------------------- -------- ------------------------- ------ ---------- ------------------------------
4016 2026-04-08 3 Internal 32 Training 1:30 draft Accessibility workshop
4015 2026-04-08 2 Orchard Mobile App 22 Support 2:30 draft Crash report on login
4014 2026-04-08 1 Lighthouse Portal 12 Frontend 4:00 draft Result list layout
Total: 8:00 (3 entries)