operx-cli 0.1.0__tar.gz → 0.2.1__tar.gz

{operx_cli-0.1.0 → operx_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: operx-cli
-Version: 0.1.0
+Version: 0.2.1
 Summary: La línea de comandos de OperX: tu empresa desde la terminal, con tu token de API.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ Requires-Dist: typer>=0.27
 Requires-Dist: httpx>=0.28
 Requires-Dist: keyring>=25
 Requires-Dist: openpyxl>=3.1
+Requires-Dist: prompt_toolkit>=3.0
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 
@@ -19,38 +20,75 @@ tú, con tu rol, y solo en tu empresa.
 
 ## Instalar
 
-Necesitas Python 3.10 o más nuevo.
+Windows (PowerShell):
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"; uv tool install operx-cli
+```
+
+Mac y Linux:
 
 ```sh
-pipx install ./cli          # desde esta carpeta del repositorio
-operx --version
+curl -LsSf https://astral.sh/uv/install.sh | sh && uv tool install operx-cli
 ```
 
+`uv` instala su propio Python, así que no necesitas tener uno. Si ya tienes
+Python 3.10 o más nuevo, también sirve `pipx install operx-cli`. Abre una
+terminal nueva y comprueba con `operx --version`.
+
+Para actualizar: `uv tool upgrade operx-cli`.
+
 ## Entrar
 
-1. En la app, abre el menú de tu cuenta › **Acceso por API** y crea un token.
-   Elige *Lectura y escritura* si vas a crear o cambiar datos.
-2. Guárdalo en tu equipo:
+```sh
+operx login
+```
+
+1. La terminal muestra un código y abre el navegador en la página de OperX.
+2. Entras como siempre. La página dice qué terminal pide acceso: apruébalo solo
+   si acabas de escribir `operx login` en tu propio computador y el código es
+   el mismo. Escribe el código de 6 dígitos de tu app de autenticación (o tu
+   contraseña, si no usas una) y elige *Solo lectura* o *Lectura y
+   escritura*.
+3. Vuelve a la terminal: ya entraste. Nunca ves ni copias un token.
 
-   ```sh
-   operx entrar        # pega el token; no se muestra
-   operx cuenta        # quién eres, tu empresa y tu rol
-   ```
+Tu rol necesita el permiso «Acceso por API» (Ajustes › Usuarios y acceso ›
+Roles); un administrador lo da. El acceso dura 90 días y lo ves, y puedes
+revocarlo, en el menú de tu cuenta › Acceso por API.
 
 El token queda en el llavero del sistema (en Windows, el Administrador de
-credenciales), nunca en un archivo. En un servidor sin llavero, usa variables
-de entorno: `OPERX_TOKEN` (el token) y, si no es producción, `OPERX_DIRECCION`.
+credenciales), nunca en un archivo. En un servidor sin navegador ni llavero:
+`operx login --token` te deja pegar un token creado en Acceso por API, o puedes
+usar variables de entorno: `OPERX_TOKEN` (el token) y, si no es producción,
+`OPERX_DIRECCION`.
 
 Para otra dirección u otra empresa, usa un perfil:
 
 ```sh
-operx --perfil pruebas entrar --direccion https://…
+operx --perfil pruebas login --direccion https://…
 operx --perfil pruebas ordenes listar
 ```
 
-`operx salir` borra el token de este equipo; para que deje de funcionar,
+`operx logout` borra el token de este equipo; para que deje de funcionar,
 revócalo en Acceso por API.
 
+## Modo interactivo
+
+Escribe `operx` solo, en una terminal, y se abre la pantalla de bienvenida
+(quién eres y los números de hoy: órdenes abiertas, vencidas, artículos bajo
+el mínimo) con un prompt. Ahí escribes los comandos sin el `operx`, con
+Tab para completar y ↑ para repetir lo anterior:
+
+```
+operx › ordenes listar --vencidas
+operx › buscar "bomba"
+operx › ayuda
+operx › salir
+```
+
+`salir` (o Ctrl+D) termina la sesión sin borrar tu token. En un script o una
+tubería, `operx` solo muestra la ayuda y no espera a nadie.
+
 ## Comandos
 
 ```sh
@@ -124,6 +162,13 @@ operx api POST work-orders/1234/attachments/ -a file=foto.jpg -d '{"file_type":
 En Git Bash, una dirección que empieza por `/` se vuelve una ruta de Windows:
 escríbela sin la barra inicial, como arriba.
 
+## Para agentes de IA
+
+`operx agentes` imprime una guía para un agente de IA (Claude, ChatGPT,
+Copilot, Codex…): las reglas para usar `operx` bien (leer con `--json`,
+preguntar antes de escribir, no tocar tokens) y cada comando con sus opciones.
+Dile a tu agente: «Ejecuta `operx agentes` y sigue esa guía».
+
 ## Para desarrollar
 
 ```sh
@@ -134,3 +179,31 @@ python -m venv .venv && .venv/Scripts/python -m pip install -e ".[test]"
 
 `operx_cli/client.py` es lo único que habla con la red; el servidor MCP lo
 usará igual.
+
+### Publicar una versión
+
+El paquete es `operx-cli` en PyPI. Una versión publicada no se puede reemplazar:
+si algo falla, se sube la siguiente.
+
+1. Sube el número en `pyproject.toml` y en `operx_cli/__init__.py`.
+2. Las funciones nuevas del servidor (como `operx login`) tienen que estar ya
+   desplegadas en producción antes de publicar: el paquete nuevo las llama.
+3. Desde `cli/`:
+
+   ```sh
+   uv build --clear
+   uv publish
+   ```
+
+`uv publish` toma el token de PyPI de la variable de entorno
+`UV_PUBLISH_TOKEN`. Usa un token solo del proyecto `operx-cli` (PyPI › Account
+settings › API tokens). Se guarda una vez, en tu usuario de Windows, desde
+PowerShell; lo pegas donde lo pide y no se ve:
+
+```powershell
+$token = Read-Host "Token de PyPI" -AsSecureString
+[Environment]::SetEnvironmentVariable("UV_PUBLISH_TOKEN", [Net.NetworkCredential]::new("", $token).Password, "User")
+```
+
+Las terminales que abras después ya lo tienen. El token es secreto: nunca va
+en un archivo del repositorio ni en un chat.

{operx_cli-0.1.0 → operx_cli-0.2.1}/README.md

@@ -6,38 +6,75 @@ tú, con tu rol, y solo en tu empresa.
 
 ## Instalar
 
-Necesitas Python 3.10 o más nuevo.
+Windows (PowerShell):
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"; uv tool install operx-cli
+```
+
+Mac y Linux:
 
 ```sh
-pipx install ./cli          # desde esta carpeta del repositorio
-operx --version
+curl -LsSf https://astral.sh/uv/install.sh | sh && uv tool install operx-cli
 ```
 
+`uv` instala su propio Python, así que no necesitas tener uno. Si ya tienes
+Python 3.10 o más nuevo, también sirve `pipx install operx-cli`. Abre una
+terminal nueva y comprueba con `operx --version`.
+
+Para actualizar: `uv tool upgrade operx-cli`.
+
 ## Entrar
 
-1. En la app, abre el menú de tu cuenta › **Acceso por API** y crea un token.
-   Elige *Lectura y escritura* si vas a crear o cambiar datos.
-2. Guárdalo en tu equipo:
+```sh
+operx login
+```
+
+1. La terminal muestra un código y abre el navegador en la página de OperX.
+2. Entras como siempre. La página dice qué terminal pide acceso: apruébalo solo
+   si acabas de escribir `operx login` en tu propio computador y el código es
+   el mismo. Escribe el código de 6 dígitos de tu app de autenticación (o tu
+   contraseña, si no usas una) y elige *Solo lectura* o *Lectura y
+   escritura*.
+3. Vuelve a la terminal: ya entraste. Nunca ves ni copias un token.
 
-   ```sh
-   operx entrar        # pega el token; no se muestra
-   operx cuenta        # quién eres, tu empresa y tu rol
-   ```
+Tu rol necesita el permiso «Acceso por API» (Ajustes › Usuarios y acceso ›
+Roles); un administrador lo da. El acceso dura 90 días y lo ves, y puedes
+revocarlo, en el menú de tu cuenta › Acceso por API.
 
 El token queda en el llavero del sistema (en Windows, el Administrador de
-credenciales), nunca en un archivo. En un servidor sin llavero, usa variables
-de entorno: `OPERX_TOKEN` (el token) y, si no es producción, `OPERX_DIRECCION`.
+credenciales), nunca en un archivo. En un servidor sin navegador ni llavero:
+`operx login --token` te deja pegar un token creado en Acceso por API, o puedes
+usar variables de entorno: `OPERX_TOKEN` (el token) y, si no es producción,
+`OPERX_DIRECCION`.
 
 Para otra dirección u otra empresa, usa un perfil:
 
 ```sh
-operx --perfil pruebas entrar --direccion https://…
+operx --perfil pruebas login --direccion https://…
 operx --perfil pruebas ordenes listar
 ```
 
-`operx salir` borra el token de este equipo; para que deje de funcionar,
+`operx logout` borra el token de este equipo; para que deje de funcionar,
 revócalo en Acceso por API.
 
+## Modo interactivo
+
+Escribe `operx` solo, en una terminal, y se abre la pantalla de bienvenida
+(quién eres y los números de hoy: órdenes abiertas, vencidas, artículos bajo
+el mínimo) con un prompt. Ahí escribes los comandos sin el `operx`, con
+Tab para completar y ↑ para repetir lo anterior:
+
+```
+operx › ordenes listar --vencidas
+operx › buscar "bomba"
+operx › ayuda
+operx › salir
+```
+
+`salir` (o Ctrl+D) termina la sesión sin borrar tu token. En un script o una
+tubería, `operx` solo muestra la ayuda y no espera a nadie.
+
 ## Comandos
 
 ```sh
@@ -111,6 +148,13 @@ operx api POST work-orders/1234/attachments/ -a file=foto.jpg -d '{"file_type":
 En Git Bash, una dirección que empieza por `/` se vuelve una ruta de Windows:
 escríbela sin la barra inicial, como arriba.
 
+## Para agentes de IA
+
+`operx agentes` imprime una guía para un agente de IA (Claude, ChatGPT,
+Copilot, Codex…): las reglas para usar `operx` bien (leer con `--json`,
+preguntar antes de escribir, no tocar tokens) y cada comando con sus opciones.
+Dile a tu agente: «Ejecuta `operx agentes` y sigue esa guía».
+
 ## Para desarrollar
 
 ```sh
@@ -121,3 +165,31 @@ python -m venv .venv && .venv/Scripts/python -m pip install -e ".[test]"
 
 `operx_cli/client.py` es lo único que habla con la red; el servidor MCP lo
 usará igual.
+
+### Publicar una versión
+
+El paquete es `operx-cli` en PyPI. Una versión publicada no se puede reemplazar:
+si algo falla, se sube la siguiente.
+
+1. Sube el número en `pyproject.toml` y en `operx_cli/__init__.py`.
+2. Las funciones nuevas del servidor (como `operx login`) tienen que estar ya
+   desplegadas en producción antes de publicar: el paquete nuevo las llama.
+3. Desde `cli/`:
+
+   ```sh
+   uv build --clear
+   uv publish
+   ```
+
+`uv publish` toma el token de PyPI de la variable de entorno
+`UV_PUBLISH_TOKEN`. Usa un token solo del proyecto `operx-cli` (PyPI › Account
+settings › API tokens). Se guarda una vez, en tu usuario de Windows, desde
+PowerShell; lo pegas donde lo pide y no se ve:
+
+```powershell
+$token = Read-Host "Token de PyPI" -AsSecureString
+[Environment]::SetEnvironmentVariable("UV_PUBLISH_TOKEN", [Net.NetworkCredential]::new("", $token).Password, "User")
+```
+
+Las terminales que abras después ya lo tienen. El token es secreto: nunca va
+en un archivo del repositorio ni en un chat.

operx_cli-0.2.1/operx_cli/AGENTES.md

@@ -0,0 +1,134 @@
+# operx para agentes de IA
+
+Esta guía es para un agente de IA (Claude, ChatGPT, Copilot, Codex…) que usa
+`operx` en nombre de una persona. `operx` llama a la API de OperX con el token
+de esa persona: actúa como ella, con su rol, y solo en su empresa. Cada
+llamada queda en el historial del token, marcada como hecha desde la CLI.
+
+## Reglas
+
+1. Escribe siempre el comando completo (`operx ordenes listar …`). No abras el
+   modo interactivo: `operx` solo, fuera de una terminal, solo muestra la ayuda.
+2. Lee con `--json`: es lo que responde la API, completo. Las tablas son para
+   personas.
+3. Antes de crear o cambiar algo, dile a la persona qué vas a hacer y espera
+   su sí. Con su sí, agrega `--si`: sin él, toda escritura falla fuera de una
+   terminal.
+4. Nunca pidas, muestres ni guardes un token o una contraseña. Si no hay
+   sesión, pídele a la persona que ejecute `operx login`.
+5. Si una escritura dice que la API no respondió a tiempo, no la repitas:
+   consulta primero si quedó hecha.
+6. Si un nombre coincide con varios registros, `operx` lo dice con sus ids:
+   usa el id, no adivines.
+7. Usa un comando propio cuando exista; `operx api` es para lo demás.
+
+## Entrar
+
+- Empieza con `operx cuenta --json`: quién es la persona, su empresa, su rol
+  y los productos de la empresa (`products`).
+- Si responde «No has entrado», la persona ejecuta `operx login`: se abre su
+  navegador, aprueba con su código y la terminal queda conectada 90 días.
+  Puedes ejecutarlo tú si la persona está frente al computador: espera hasta
+  10 minutos a que apruebe.
+- En un servidor sin navegador, la persona pone el token en la variable de
+  entorno `OPERX_TOKEN` (y `OPERX_DIRECCION` si no es producción).
+- `--perfil NOMBRE` (o `OPERX_PERFIL`) usa otra empresa u otra dirección.
+
+## Leer
+
+- Las listas traen la primera página y avisan en stderr cuántas filas hay en
+  total. `--todas` las trae todas.
+- `--buscar TEXTO` filtra en el servidor. `operx buscar TEXTO --json` busca en
+  todo (órdenes, equipos, clientes, lugares y personas), desde 2 letras.
+- `ver` da un registro completo: `operx ordenes ver 1234 --json`.
+- En `--json` los valores van como los manda la API, en inglés: el `status`
+  de una orden es `open`, `in_progress`, `on_hold`, `completed`, `verified` o
+  `cancelled`, y su `priority` es `low`, `medium`, `high` o `critical`. Las
+  opciones de los comandos van en español: `--estado en-progreso`.
+- Los resultados van a stdout y los avisos a stderr:
+  `operx equipos listar --todas --json > equipos.json` guarda solo los datos.
+- `--csv` da un CSV para Excel (separado por punto y coma, con decimales con
+  coma).
+
+## Escribir
+
+- Escriben: `ordenes crear`, `ordenes estado`, `ordenes asignar`,
+  `ordenes comentar`, `equipos crear`, `clientes crear`, `inventario entrada`,
+  `inventario salida`, `lecturas registrar`, `personas importar --confirmar`,
+  y `operx api` con POST, PUT, PATCH o DELETE. Todos llevan `--si`.
+- `operx personas importar ARCHIVO` sin `--confirmar` solo revisa el archivo
+  y no guarda nada: hazlo primero y muéstrale el resultado a la persona.
+- Un acceso de solo lectura no escribe: la API responde 403.
+- Una orden se verifica en la app, nunca por la API. Un token nunca firma ni
+  aprueba, y la API nunca abre resultados médicos, nómina, quejas de
+  convivencia ni los archivos del SG-SST. Si algo responde 403, dile a la
+  persona que lo haga en la app (operx.pro).
+
+## Nombres, números y fechas
+
+- Equipos, lugares, clientes, artículos y personas se nombran por su código o
+  su nombre exacto (sin importar mayúsculas), o por su id. Un nombre a medias
+  no sirve: busca primero con `listar --buscar` o `operx buscar`.
+- `yo` es la persona dueña del token: `--asignada-a yo`, `--asignar-a yo`.
+  `operx ordenes asignar 1234 nadie` quita la asignación.
+- Números como en la app: `73,4` o `1.500,50` (también `73.4`).
+- Fechas con el día primero: `30/10/2026`; con hora: `22/10/2026 08:00`.
+  También sirven `2026-10-30` y `2026-10-22T08:00`. La hora es la del
+  computador.
+
+## Errores
+
+| Código de salida | Qué pasó |
+|---|---|
+| 0 | Funcionó. |
+| 1 | `operx` o la API lo rechazó. El motivo va en stderr, en una línea que empieza por `Error:`. |
+| 2 | El comando está mal escrito: una opción que no existe o un dato que falta. Mira `operx COMANDO --help`. |
+
+Lo que responde la API:
+
+- **401**: el acceso venció o lo revocaron. La persona ejecuta `operx login`.
+- **403**: el rol de la persona no lo permite, el acceso es de solo lectura,
+  la empresa no tiene ese producto, o un token no puede hacer eso.
+- **404**: no existe, o la persona no lo puede ver.
+- **400**: un dato no sirve. El mensaje dice cuál y por qué.
+- **429**: demasiadas llamadas (120 por minuto por token, 600 por empresa).
+  `operx` espera y reintenta solo, hasta 3 veces.
+
+## Cualquier otra llamada: `operx api`
+
+`operx api MÉTODO RUTA` hace cualquier llamada que el token pueda hacer y
+responde el JSON de la API. Las rutas están en la app, en Acceso por API ›
+Documentación; escríbelas sin `/api/v1/` y sin barra inicial.
+
+- `-q nombre=valor`: un filtro. Se repite.
+- `-d '{"campo": "valor"}'` o `-d @archivo.json`: el cuerpo de la llamada.
+- `-a campo=ruta`: un archivo a subir. Se repite.
+- `--todas`: todas las páginas de un GET.
+- `-o archivo`: guarda una respuesta que es un archivo (CSV, PDF).
+
+```sh
+operx api GET pm/schedules/ -q search=compresor
+operx api POST contacts/ -d @contacto.json --si
+operx api GET work-orders/export/ -o ordenes.csv
+```
+
+## Recetas
+
+```sh
+# Las órdenes vencidas de la persona
+operx ordenes listar --vencidas --asignada-a yo --todas --json
+
+# Pasar una orden a completada, después de su sí
+operx ordenes estado 1234 completada --si
+
+# Registrar una lectura: primero el número del punto
+operx lecturas puntos BOM-04 --json
+operx lecturas registrar --punto 12 --valor 73,4 --si
+
+# Sacar stock: primero el código y el lugar exactos
+operx inventario existencias --buscar filtro --json
+operx inventario salida --articulo FIL-010 --lugar "Bodega central" --cantidad 2 --motivo Consumo --si
+
+# Los equipos en un CSV para Excel
+operx equipos listar --todas --csv > equipos.csv
+```

{operx_cli-0.1.0 → operx_cli-0.2.1}/operx_cli/__init__.py

@@ -2,4 +2,4 @@
 API (backend/users/api_allowlist.py) from a terminal, with a personal API
 token."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

operx_cli-0.2.1/operx_cli/agent_guide.py

@@ -0,0 +1,57 @@
+"""`operx agentes`: the guide for AI agents (AGENTES.md), then every command
+with its options, read from the commands themselves so the list matches the
+installed version."""
+
+from importlib.resources import files
+
+ROOT_TITLE = "operx (opciones de cualquier comando)"
+
+
+def guide_text(root):
+    rules = files("operx_cli").joinpath("AGENTES.md").read_text(encoding="utf-8")
+    return rules.rstrip("\n") + "\n\n" + reference(root)
+
+
+def reference(root):
+    lines = ["## Todos los comandos", "", "Cada uno también tiene `--help`.", ""]
+    lines += _command_section(ROOT_TITLE, root)
+    for path, command in _commands(root, ["operx"]):
+        lines += _command_section(" ".join(path), command)
+    return "\n".join(lines)
+
+
+def _commands(group, path):
+    """The commands a person can type, group by group, without the hidden ones."""
+    for name, command in group.commands.items():
+        if getattr(command, "hidden", False):
+            continue
+        if hasattr(command, "commands"):
+            yield from _commands(command, path + [name])
+        else:
+            yield path + [name], command
+
+
+def _command_section(title, command):
+    lines = [f"### {title}", ""]
+    if command.help and title != ROOT_TITLE:
+        lines += [command.help.strip(), ""]
+    params = [param for param in command.params if not getattr(param, "hidden", False)]
+    lines += [f"- {_param_line(param)}" for param in params]
+    return lines + ([""] if params else [])
+
+
+def _param_line(param):
+    if param.param_type_name == "argument":
+        line = f"`{param.name.upper()}`"
+    else:
+        line = ", ".join(f"`{opt}`" for opt in param.opts)
+        choices = getattr(param.type, "choices", None)
+        if choices:
+            line = f"`{' '.join(param.opts)} [{'|'.join(str(choice) for choice in choices)}]`"
+        elif not getattr(param, "is_flag", False):
+            line += " VALOR"
+    marks = [mark for mark, on in (("obligatorio", param.required), ("se repite", getattr(param, "multiple", False))) if on]
+    if marks:
+        line += f" ({', '.join(marks)})"
+    help_text = (getattr(param, "help", None) or "").strip()
+    return f"{line}: {help_text}" if help_text else line

operx_cli-0.2.1/operx_cli/app.py

@@ -0,0 +1,149 @@
+"""`operx`: the root of the commands, and what turns a refused call into
+one line instead of a traceback."""
+
+import errno
+import os
+import sys
+from typing import Annotated, Optional
+
+import typer
+from typer.core import TyperGroup
+
+from . import __version__, settings, shell
+from .agent_guide import guide_text
+from .client import ApiError
+from .commands import account, inventario, lecturas, ordenes, personas, raw, registros, search
+from .commands.common import CliError, Session
+from .lookup import NoSingleMatch
+from .spreadsheet import SpreadsheetError
+
+# What a person can fix: shown as "Error: …", exit code 1.
+EXPECTED_ERRORS = (ApiError, CliError, NoSingleMatch, SpreadsheetError, settings.SettingsError)
+
+
+def _is_closed_pipe(error):
+    """What writing to a pipe whose reader left raises: BrokenPipeError (EPIPE),
+    and on Windows a bare EINVAL. That EINVAL names no file: a bad file name
+    raises the same errno with the name in it, and must not be hidden."""
+    if isinstance(error, BrokenPipeError) or error.errno == errno.EPIPE:
+        return True
+    return error.errno == errno.EINVAL and error.filename is None
+
+
+def _silence_stdout():
+    """Python flushes stdout once more on the way out, which would print
+    "Exception ignored…" over the quiet exit: point it at nothing."""
+    try:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    except (OSError, ValueError, AttributeError):
+        pass
+
+
+class ReportedErrors(TyperGroup):
+    def invoke(self, ctx):
+        try:
+            return super().invoke(ctx)
+        except EXPECTED_ERRORS as error:
+            typer.echo(f"Error: {error}", err=True)
+            raise typer.Exit(1) from None
+        except (typer.Abort, KeyboardInterrupt):
+            # Ctrl+C, or a question whose answer never came.
+            typer.echo("Se canceló.", err=True)
+            raise typer.Exit(1) from None
+        except OSError as error:
+            if not _is_closed_pipe(error):
+                raise
+            # `operx … | head`: whoever reads left before the end. Not an error.
+            _silence_stdout()
+            raise typer.Exit(0) from None
+
+
+app = typer.Typer(
+    cls=ReportedErrors,
+    help="OperX desde la terminal: tu empresa con tu token de API.",
+    # `operx` alone is the welcome and the prompt (root below), not the help.
+    no_args_is_help=False,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    # A crash must never print the token, which lives in the client's locals.
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _show_version(value):
+    if value:
+        typer.echo(f"operx {__version__}")
+        raise typer.Exit()
+
+
+def is_interactive():
+    """A person at a terminal, not a script or a pipe: only then does a prompt
+    make sense."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    perfil: Annotated[
+        Optional[str],
+        typer.Option("--perfil", "-p", help="El perfil: otra API u otra empresa. Sin él, «principal» (o OPERX_PERFIL)."),
+    ] = None,
+    version: Annotated[
+        bool, typer.Option("--version", callback=_show_version, is_eager=True, help="La versión instalada.")
+    ] = False,
+):
+    if ctx.obj is None:
+        ctx.obj = Session()
+        ctx.obj.profile = settings.profile_name(perfil)
+    elif perfil:
+        ctx.obj.profile = perfil
+    # Else the interactive mode's session, which already has its profile:
+    # every line typed runs this callback again and must not reset it.
+    if ctx.invoked_subcommand is None:
+        open_the_prompt(ctx)
+
+
+def open_the_prompt(ctx):
+    """`operx` alone: at a terminal, the welcome and the prompt; in a script
+    or a pipe, the help (a prompt would hang it)."""
+    if ctx.obj.in_shell:
+        # Typed at the prompt (`--perfil staging`): it already did what it
+        # says; a second prompt must not open inside the first.
+        return
+    if not is_interactive() and ctx.obj.reader is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+    shell.enter(ctx.obj, ctx.command)
+
+
+app.command()(account.login)
+app.command()(account.logout)
+# The first version's names, for whoever typed them: out of the help.
+app.command(name="entrar", hidden=True)(account.entrar)
+app.command(name="salir", hidden=True)(account.logout)
+app.command()(account.cuenta)
+app.command()(search.buscar)
+app.command()(raw.api)
+app.add_typer(ordenes.app, name="ordenes")
+app.add_typer(registros.equipos, name="equipos")
+app.add_typer(registros.clientes, name="clientes")
+app.add_typer(registros.lugares, name="lugares")
+app.add_typer(inventario.app, name="inventario")
+app.add_typer(lecturas.app, name="lecturas")
+app.add_typer(personas.app, name="personas")
+
+
+@app.command()
+def agentes(ctx: typer.Context):
+    """La guía para agentes de IA (Claude, ChatGPT, Copilot): cómo usar operx bien, con cada comando y sus opciones."""
+    typer.echo(guide_text(ctx.find_root().command))
+
+
+def main():
+    # Redirected to a file, Windows would write the results in its own code
+    # page; the CSV and the JSON are UTF-8.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    app()