kctl-odoo
Kodemeio Odoo CLI -- manage Odoo 18 ERP instances via JSON-RPC and Docker Compose.
Installation
uv tool install ./cli
To upgrade after code changes:
uv tool install --force --reinstall ./cli
Quick Start
# Configure connection (interactive)
kctl-odoo config init
# Verify connectivity
kctl-odoo config test
# Dashboard overview
kctl-odoo dashboard summary
# List installed modules
kctl-odoo modules list --state installed
# Health check
kctl-odoo doctor check
Fast debugging — log tailing
kctl-odoo logs tail is a unified streaming command for local + remote Odoo
with structured filters. It auto-detects the transport from the current
profile URL:
- local (
localhost/127.0.0.1) → streamsdocker compose logs -fin the project directory. - remote → streams
docker logs -fover SSH viakctl-dokploy compose service-logs --follow. Requires--compose-id(find withkctl-dokploy compose list).
# Local dev — stream everything
kctl-odoo logs tail
# Local dev — only warnings and above from the account.move module
kctl-odoo logs tail --level WARNING --module account.move
# Remote prod — stream tpp-odoo-erp
kctl-odoo -p idtpp-tpp-odoo-erp logs tail \
--dokploy-profile idtpp \
--compose-id Qki8U2u4Ltstq0_6zW7UE
# Narrow by worker PID or request id in the message
kctl-odoo logs tail --worker 12 --grep "traceback"
Filter flags compose as AND: --level, --module, --request, --worker,
--grep.
Full traceback capture. Filters apply per log record, not per line. When
a record's timestamped header matches, all of its continuation lines
(Traceback (most recent call last):, File "...", ^^^, exception
message) are emitted too — stack traces survive --level ERROR or any
other filter. --grep can also match a continuation line directly (e.g.
--grep "fields.py" to find tracebacks involving a specific file); when
it does, the rest of that record's block is included.
Other logs subcommands:
logs follow— legacy local-only streamer (kept for back-compat).logs errors --days N— finite query against Odoo'sir.loggingmodel.logs search <pattern>— finite ilike search againstir.logging.
Command Groups (98 groups, 1,164 commands)
Organized into 13 help panels. Run kctl-odoo --help for the full list.
| Panel | Groups |
|---|---|
| Admin & Config | config, users, companies, partners, security, sessions, databases |
| Sales & CRM | sales, crm, delivery, pricelist, pos |
| Procurement & Ops | purchasing, inventory, mrp |
| HR & Projects | hr, onboarding, project, products, dashboard |
| Accounting & Finance | accounting, tax, budget, dunning, statements, assets, bank, payment-gateways, currency |
| Domain Apps | website, fleet, helpdesk, events, approvals, forms, compliance, quality, support |
| Reports & Analytics | report (incl. report build — author reports from YAML, no code and no deploy — and report build sql — author governed raw-SQL reports that run under a read-only PostgreSQL role: lint/explain/diff/preview/apply a committed file, list/show/versions/rollback/publish/unpublish/retire/export/promote a report, plus role status/role sync and test record/test check golden fixtures), report-formats, kpi, mis-reports, data-quality, sql-export |
| Monitoring & Ops | doctor, monitor, maintenance, backup, deploy, workers, mail, cron, jobs, flow (author workflow_base definitions from committed YAML — lint/diff/contract/export write nothing; adopt/apply/promote and the lifecycle verbs need --yes off local), workflow (DEPRECATED name — client-side step runner, unrelated to flow), audit |
| Performance & Storage | storage, performance, logs, integration |
| Development | dev, lint, test, scaffold, manifest, views, orm, record-rules, traceback, translations, fastapi, e2e |
| Instance Management | local, modules, bundles, roles, addons, tenants, setup, pipeline |
| Data & Migration | diff, server, master-data, automation, sequences, periods, migrate, accurate |
| Tools | shell, export, import, history, skill |
Command Aliases
Hidden short aliases for common workflows (20 total):
| Alias | Expands to | Alias | Expands to |
|---|---|---|---|
mi |
modules install |
acc |
accounting |
mu |
modules upgrade |
inv |
inventory |
ml |
modules list |
sal |
sales |
hc |
doctor check |
rep |
report |
di |
dashboard summary |
aud |
audit |
bl |
bundles list |
mnt |
maintenance |
bi |
bundles install |
dq |
data-quality |
pl |
profiles list |
wf |
workflow |
pi |
profiles install |
perf |
performance |
tr |
test run |
dx |
doctor |
Example:
kctl-odoo mi sale_management # same as: kctl-odoo modules install sale_management
kctl-odoo tr base_management # same as: kctl-odoo test run base_management
Global Options
--json Output as JSON (machine-readable)
--quiet, -q Suppress informational messages
--profile, -p Use a named config profile
--url Odoo URL override
--api-key API key override
--database, -d Database override
--username, -u Username override
--version, -V Show version and exit
Configuration
Profiles
kctl-odoo supports named profiles for managing multiple Odoo instances:
# Create profiles
kctl-odoo config add production --url https://erp.kodeme.io --database kodemeio --api-key $KEY
kctl-odoo config add staging --url https://staging.kodeme.io --database staging --api-key $KEY
# Switch default profile
kctl-odoo config use production
# Use per-command
kctl-odoo --profile staging modules list
# List all profiles
kctl-odoo config list
Config File
Configuration is stored in the shared Kodemeio config file:
~/.config/kodemeio/config.yaml.
Shell Completions
# Install for your shell
kctl-odoo --install-completion bash
kctl-odoo --install-completion zsh
kctl-odoo --install-completion fish
See docs/completions.md for manual installation and troubleshooting.
Plugin Development
kctl-odoo supports extending the CLI via Python entry points. Create a package that
registers a Typer app under the kctl_odoo.plugins entry point group:
# In your plugin's pyproject.toml
[project.entry-points."kctl_odoo.plugins"]
my_plugin = "my_plugin.cli:app"
The plugin's app (a typer.Typer instance) will be registered as a command group
automatically on startup.
Recent Changes
- CLI restructure — 94 groups (down from 100), 13 help panels. Standardized CRUD verbs (
list/get/create/summary). Merged thin groups (dev-mode→dev, staging→deploy, repl→shell, auto-maintain→maintenance, clean→maintenance, self-test→doctor). All old names preserved as hidden aliases. - Performance — HTTP response cache (60s TTL, LRU), async commands (top-10 with asyncio.gather), connection pool tuning, pagination guards.
- Workflow engine —
workflow list/run/statuswith 3 built-in workflows (deploy-safe, maintenance-window, data-quality-sweep). Abort/skip/retry failure modes. - Doctor auto-fix —
doctor fixremediates overdue crons, disabled mail servers, stale sessions. - Error hints — Actionable guidance on auth/config/connection errors.
- Exception specificity — All 563
except Exceptionblocks replaced with specific types. BLE001 ruff rule enforced. - Feature flags —
@requires_modeldecorator gracefully skips commands when Odoo modules aren't installed.
Development
Running Tests
cd cli
uv run pytest tests/ -v
Linting and Formatting
cd cli
uv run ruff check src/
uv run ruff format src/
Type Checking
cd cli
uv run mypy src/kctl_odoo/
Project Structure
cli/
src/kctl_odoo/
cli.py Main app + command registration
__init__.py Version
core/
callbacks.py Global option handling (AppContext)
client.py JSON-RPC client for remote Odoo
local.py Docker Compose client for local dev
config.py Profile/config management
exceptions.py Custom exception hierarchy
output.py Output formatting (table, JSON, plain)
commands/
aliases.py Short command aliases (20 aliases)
dev/ Development tools (split into 5 sub-modules)
report/ Report engine (split into 3 sub-modules)
maintenance/ DB maintenance (split into 4 sub-modules)
readiness/ Readiness checks (split into 4 sub-modules)
accurate/ Accurate integration (split into 2 sub-modules)
workflow_cmd.py Workflow orchestration engine
... (90+ command modules)
tests/ pytest test suite (1,100+ tests)
skills/odoo-admin/ Claude Code skill (auto-generated)
pyproject.toml Package metadata and tool config
README.md This file
docs/ Additional documentation
1 maintainer
Release files for kctl-odoo 1.24.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kctl_odoo-1.24.1.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kctl_odoo-1.24.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.8 MB
Release files / kctl_odoo-1.24.1.tar.gz
| Download URL | kctl_odoo-1.24.1.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7cf4ca37d9ef0aa608e4fe96137179d1787cea97ec5a207e65bc611254158416
|
|
BLAKE2b-256 checksum How to use checksums |
32e6137d52f5ae8a8f6a81ac9af334e6faf11c0fe265b13f2dc250e737f68998
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / kctl_odoo-1.24.1-py3-none-any.whl
| Download URL | kctl_odoo-1.24.1-py3-none-any.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
41e2887b898ecf9a113b6c3fd5edb7a58a5608204aa1231a954a44add2497094
|
|
BLAKE2b-256 checksum How to use checksums |
b3baa3e64c44b08bf3cb15d9344e81d57b916cb1e66317f49d88946926c6c1f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
