Book Odoo 17 timesheets and attendance from the terminal: a CLI for scripts and coding agents, and a TUI for the weekly grid.
Documentation: https://seletz.github.io/odoo-work-cli/
- Timesheets: list, add, update and delete entries;
--dry-runpreviews a write - Attendance: clock in/out, also for non-admin users and with 2FA (TOTP); backdate, fix or add records for a forgotten day
- TUI: weekly grid with holidays, colour-coded totals, attendance per day, search, inline add/edit, configurable keys
- For scripts and agents:
--json/--format jsonloutput with JSON Schemas, stable error kinds,llm --skillguide - Offline: a built-in fake backend runs every command without Odoo
brew tap seletz/tap
brew install odoo-work-cliUpdate with brew update && brew upgrade odoo-work-cli. Release binaries and
go install: see Install and update.
odoo-work-cli config install # then set url, database, username
export ODOO_PASSWORD="your-api-key" # the Odoo API key, not your password
odoo-work-cli whoami
odoo-work-cli tuiStep by step: Your first booking. Without an Odoo server: Try it offline.
| Tutorials | try it offline, first booking, TUI tour |
| How-to guides | book time, clock in/out, JSON output, agents, MCP, troubleshooting |
| Reference | every command and flag, JSON output, error kinds, configuration, TUI keys |
| Explanation | config layering, secrets, the two transports, the attendance model |
- Go 1.21+
- mise for task running and tool management
- 1Password CLI (
op) — optional, for[op_secrets]resolution
# Install tools via mise
mise install
# Build
mise run build
# Run tests
mise run test
# Lint
mise run lintThe site under docs/ is built with Zensical
(pinned in pyproject.toml, installed by uv) and deployed to GitHub Pages
as part of each release (.github/workflows/release.yml), so the site always
matches the latest release. .github/workflows/docs.yml checks and builds it on
pull requests and develop, without deploying.
mise run docs:serve # live preview
mise run docs:build # strict build into site/
mise run docs:screenshots # TUI screenshots, CLI samples, demo state
mise run docs:reference # command reference: site pages and man pages (man/man1)
mise run docs:check # fail if anything generated is stale (CI runs this)Screenshots and CLI samples are rendered by tools/docsgen from the fake
backend with a fixed demo state and clock (2026-W15), so they are
reproducible. A change to the TUI, a command's output or its help text makes
docs:check fail until you regenerate and commit.
Important
Local development and automated tests target the dev Odoo environment only. The test and prod environments must never be touched by local development or tests.
Dev credentials live in a single 1Password item and flow into the project in two ways:
.envfor mise tasks —1p.envis a 1Password template containingop://references.mise run prepare_envrunsop injecton it to generate a local.env, which mise auto-loads for every task (includingmise run run -- ...and theodoo:*tasks below).[op_secrets]for the CLI — the checked-in.odoo-work-cli.tomlresolves the same 1Password item at runtime, so running the built binary from the repo directory picks up dev credentials automatically.
Both expect a 1Password item with the fields url, database-name, login,
api-key, password, and totp_secret.
Bootstrap tasks:
mise run prepare_env # generate .env from 1p.env via op inject
mise run odoo:create-api-key # create an XML-RPC API key via the web login
# flow (handles 2FA) and write it back to 1Password
mise run odoo:add-test-data # idempotent: seed the dev db with the modules,
# company, project, tasks and employee the
# checked-in config filters expect
mise run odoo:ensure-test-user # idempotent: provision the non-admin test
# user (see below)
mise run odoo:prepare-db # all of the above in order — bootstraps a
# freshly recreated dev db in one commandWhen the dev database is recreated ("nuked"), all previously issued API keys
are gone. mise run odoo:prepare-db fixes that end-to-end: it creates a new
API key, refreshes .env, and re-seeds the test data.
The CLI user provisioned above is an administrator, so ACL/permission
bugs never surface with it — #40
(whoami faulting for regular users) is exactly the class of bug that hides.
The bootstrap therefore also provisions a permanent non-admin test user
(issue #55):
mise run odoo:ensure-test-user— idempotent; creates/repairs a user with logintest-user, the regular-employee groups only (Internal User, Project/User, Timesheets/User: own timesheets only — verified not to be in Administration/Settings), and a linkedhr.employeerecord. Strictly Internal-User-only does not work: Odoo denies readingaccount.analytic.line/project.projectwithout the per-app user groups every real employee has. A fresh random password is set on every run and written to thetest-user-passwordfield of the "ODOO Work CLI" 1Password item (printed once to stdout instead if theopCLI is unavailable). The user has no 2FA, so XML-RPC accepts the plain password — no API key needed.mise run odoo:run-as-user -- <args...>— run any CLI/TUI command as that user, e.g.mise run odoo:run-as-user -- whoami. OverridesODOO_USERNAME/ODOO_PASSWORD/ODOO_WEB_PASSWORDfor the invocation (password read from 1Password, or fromODOO_TEST_USER_PASSWORDif set).mise run odoo:smoke-test-user— smoke check: runswhoami,clock statusandentriesas the non-admin user and fails loudly on ACL faults. Run it after changes that touch Odoo model reads/writes.
The 2FA web session used by clock in|out authenticates through Odoo's HTML
login flow (/web/login → /web/login/totp) and therefore encodes
web-controller internals that a new Odoo version may change
(#57):
GET /web/login?db=<db>binds the session and serves acsrf_tokeninputPOST /web/loginacceptscsrf_token,login,password,redirect- 303 redirect = accepted (to
/web/login/totpwhen 2FA is pending), 200 = rejected POST /web/login/totpacceptscsrf_token,totp_token
mise run odoo:login-canaryexercises the full flow against the dev instance — login, TOTP challenge, and a session-authenticated JSON-RPC call — and on failure names the encoded assumption that broke (e.g. "login page markup may have changed; check the Odoo version").
This is the mandatory pre-upgrade check. Dev receives new Odoo versions
first, so run the canary against dev before any Odoo upgrade reaches test
or prod. If it fails, clock in|out (and mise run odoo:create-api-key,
which mirrors the same flow) will break on that Odoo version.
Known limitation: clock in|out currently fails against multi-database
servers — the web session is not reliably bound to the requested database.
Tracked in #48.
Releases are managed via mise run release and built by
GoReleaser in GitHub Actions.
mise run releaseThis will:
- Check that the generated docs are current (
mise run docs:check); abort if not - Show the current version (latest
v*tag, orv0.0.0if none) - Prompt for bump type (patch / minor / major)
- Create an annotated git tag
- Push the tag to origin
The Release workflow then runs three dependent jobs: verify (tests, lint,
docs check, strict docs build), goreleaser and docs (deploys the site to
GitHub Pages). If verify fails, nothing is released. GoReleaser:
- Cross-compiles for macOS (amd64, arm64), Linux (amd64, arm64), and Windows (amd64)
- Packages binaries as
.tar.gz(Unix) or.zip(Windows) - Creates a GitHub Release with all artifacts and SHA-256 checksums
- Updates the Homebrew tap cask so
brew upgradepicks up the new version
mise run goreleaser-check # validate .goreleaser.yml
mise run goreleaser-snapshot # full build without publishingThe build injects the version via -ldflags:
mise run build
./odoo-work-cli --version