kctl-odoo 0.33.0

Kodemeio Odoo CLI - manage Odoo 18 ERP instances

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) → streams docker compose logs -f in the project directory.
• remote → streams docker logs -f over SSH via kctl-dokploy compose service-logs --follow. Requires --compose-id (find with kctl-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's ir.logging model.
• logs search <pattern> — finite ilike search against ir.logging.

Command Groups (94 groups, 913 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, report-formats, kpi, mis-reports, data-quality, sql-export
Monitoring & Ops	doctor, monitor, maintenance, backup, deploy, workers, mail, cron, jobs, workflow, 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 ~/.config/kctl-odoo/config.toml (XDG-compliant).

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/status with 3 built-in workflows (deploy-safe, maintenance-window, data-quality-sweep). Abort/skip/retry failure modes.
• Doctor auto-fix — doctor fix remediates overdue crons, disabled mail servers, stale sessions.
• Error hints — Actionable guidance on auth/config/connection errors.
• Exception specificity — All 563 except Exception blocks replaced with specific types. BLE001 ruff rule enforced.
• Feature flags — @requires_model decorator 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