Metadata-Version: 2.4
Name: kctl-odoo
Version: 0.28.0
Summary: Kodemeio Odoo CLI - manage Odoo 18 ERP instances
Author-email: Kodemeio <dev@kodeme.io>
License-Expression: MIT
Keywords: cli,erp,json-rpc,kodemeio,odoo
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.0
Requires-Dist: kctl-lib>=0.8.0
Requires-Dist: kodemeio-accurate>=0.5.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# kctl-odoo

Kodemeio Odoo CLI -- manage Odoo 18 ERP instances via JSON-RPC and Docker Compose.

## Installation

```bash
uv tool install ./cli
```

To upgrade after code changes:

```bash
uv tool install --force --reinstall ./cli
```

## Quick Start

```bash
# 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`).

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# Install for your shell
kctl-odoo --install-completion bash
kctl-odoo --install-completion zsh
kctl-odoo --install-completion fish
```

See [docs/completions.md](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:

```toml
# 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

```bash
cd cli
uv run pytest tests/ -v
```

### Linting and Formatting

```bash
cd cli
uv run ruff check src/
uv run ruff format src/
```

### Type Checking

```bash
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
```
