Skip to content

Commands

NAME

odoo-work-cli - Book Odoo 17 timesheets and attendance from the terminal

SYNOPSIS

odoo-work-cli COMMAND [OPTIONS] [ARGUMENTS]
odoo-work-cli --version
odoo-work-cli --help

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.

--format FORMAT

Output FORMAT: table, json or jsonl.

one of table, json, jsonl; optional; default: table

--json

Shorthand for --format json.

flag; optional

--backend BACKEND

BACKEND: odoo or fake (offline, made-up data; env ODOO_WORK_CLI_BACKEND).

string; optional; default: odoo; env: ODOO_WORK_CLI_BACKEND

--config FILE

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)

SEE ALSO