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

{operx_cli-0.2.0/operx_cli.egg-info → operx_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: operx-cli
-Version: 0.2.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
@@ -47,7 +47,8 @@ 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 tu contraseña y elige *Solo lectura* o *Lectura y
+   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.
 
@@ -161,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
@@ -180,12 +188,22 @@ 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/`, con un entorno que tenga `build` y `twine`:
+3. Desde `cli/`:
 
    ```sh
-   python -m build
-   python -m twine upload dist/*     # usuario __token__, y el token del proyecto
+   uv build --clear
+   uv publish
    ```
 
-El token de PyPI es secreto: se escribe en tu terminal, nunca en un archivo del
-repositorio ni en un chat.
+`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.0/PKG-INFO → operx_cli-0.2.1/README.md

@@ -1,191 +1,195 @@
-Metadata-Version: 2.4
-Name: operx-cli
-Version: 0.2.0
-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
-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"
-
-# operx: OperX desde la terminal
-
-`operx` usa la API de OperX con tu token personal: lo mismo que puedes hacer
-en la app, desde una terminal, un script o una tarea programada. Actúa como
-tú, con tu rol, y solo en tu empresa.
-
-## Instalar
-
-Windows (PowerShell):
-
-```powershell
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex"; uv tool install operx-cli
-```
-
-Mac y Linux:
-
-```sh
-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
-
-```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 tu contraseña y elige *Solo lectura* o *Lectura y
-   escritura*.
-3. Vuelve a la terminal: ya entraste. Nunca ves ni copias un token.
-
-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 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 login --direccion https://…
-operx --perfil pruebas ordenes listar
-```
-
-`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
-operx buscar "bomba"                       # como la barra de búsqueda de la app
-
-operx ordenes listar --estado en-progreso --asignada-a yo
-operx ordenes ver 1234
-operx ordenes crear --titulo "Cambio de rodamiento" --equipo BOM-04 --prioridad alta --vence 30/10/2026
-operx ordenes estado 1234 completada
-operx ordenes asignar 1234 "Pedro Pérez"
-operx ordenes comentar 1234 "Llegó el repuesto"
-
-operx equipos listar --buscar compresor
-operx equipos ver BOM-04
-operx equipos crear --nombre "Bomba 4" --codigo BOM-04 --lugar "Planta Norte"
-operx clientes listar
-operx clientes crear --nombre "Acme S.A.S." --nit 900123456
-operx clientes crear --nombre "Filtros Ltda" --rol proveedor
-operx lugares listar
-
-operx inventario existencias --buscar filtro
-operx inventario entrada --articulo FIL-010 --lugar "Bodega central" --cantidad 10 --costo-unitario 1.500,50
-operx inventario salida --articulo FIL-010 --lugar "Bodega central" --cantidad 2 --motivo Consumo
-
-operx lecturas puntos BOM-04
-operx lecturas registrar --punto 12 --valor 73,4
-
-operx personas importar empleados.xlsx               # revisa el archivo, no guarda
-operx personas importar empleados.xlsx --confirmar   # guarda si ninguna fila tiene errores
-```
-
-`operx --help` y `operx ordenes --help` muestran todas las opciones.
-
-- Los equipos, lugares, clientes, artículos y personas se nombran por su
-  código o su nombre exacto. Si dos se llaman igual, `operx` lo dice y pide
-  el id.
-- Los números y las fechas se escriben como en la app: `73,4`, `1.500,50`,
-  `30/10/2026`, `22/10/2026 08:00`.
-- Las listas muestran la primera página; `--todas` las trae todas.
-- `--json` da todo lo que responde la API; `--csv` da un CSV que Excel abre
-  bien (`operx equipos listar --todas --csv > equipos.csv`).
-
-### Antes de escribir
-
-Todo lo que crea o cambia algo pregunta antes. En un script o una tarea
-programada no hay a quién preguntar: agrega `--si`. Cada escritura queda en
-el historial del token (Acceso por API › el token › Actividad) marcada como
-hecha desde la CLI.
-
-### Importar personas
-
-La primera columna con el nombre basta. `operx` reconoce las columnas
-Nombres, Apellidos, Código, Cargo, Tipo de contrato, Fecha de ingreso, Fin de
-contrato, Celular, Sede y las de contacto de emergencia, con o sin tildes.
-Una columna con otro nombre se indica con `--mapa "Tu columna=campo"`.
-Nadie recibe acceso a la app al importarlo: las invitaciones se envían en
-Usuarios y acceso.
-
-### Cualquier otra llamada
-
-Lo que no tiene comando propio se hace con `operx api`, con las direcciones
-de Acceso por API › Documentación (sin `/api/v1/`):
-
-```sh
-operx api GET pm/schedules/ -q search=compresor
-operx api POST contacts/ -d @contacto.json
-operx api GET work-orders/export/ -o ordenes.csv
-operx api POST work-orders/1234/attachments/ -a file=foto.jpg -d '{"file_type": "photo"}'
-```
-
-En Git Bash, una dirección que empieza por `/` se vuelve una ruta de Windows:
-escríbela sin la barra inicial, como arriba.
-
-## Para desarrollar
-
-```sh
-cd cli
-python -m venv .venv && .venv/Scripts/python -m pip install -e ".[test]"
-.venv/Scripts/python -m pytest
-```
-
-`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/`, con un entorno que tenga `build` y `twine`:
-
-   ```sh
-   python -m build
-   python -m twine upload dist/*     # usuario __token__, y el token del proyecto
-   ```
-
-El token de PyPI es secreto: se escribe en tu terminal, nunca en un archivo del
-repositorio ni en un chat.
+# operx: OperX desde la terminal
+
+`operx` usa la API de OperX con tu token personal: lo mismo que puedes hacer
+en la app, desde una terminal, un script o una tarea programada. Actúa como
+tú, con tu rol, y solo en tu empresa.
+
+## Instalar
+
+Windows (PowerShell):
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"; uv tool install operx-cli
+```
+
+Mac y Linux:
+
+```sh
+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
+
+```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.
+
+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 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 login --direccion https://…
+operx --perfil pruebas ordenes listar
+```
+
+`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
+operx buscar "bomba"                       # como la barra de búsqueda de la app
+
+operx ordenes listar --estado en-progreso --asignada-a yo
+operx ordenes ver 1234
+operx ordenes crear --titulo "Cambio de rodamiento" --equipo BOM-04 --prioridad alta --vence 30/10/2026
+operx ordenes estado 1234 completada
+operx ordenes asignar 1234 "Pedro Pérez"
+operx ordenes comentar 1234 "Llegó el repuesto"
+
+operx equipos listar --buscar compresor
+operx equipos ver BOM-04
+operx equipos crear --nombre "Bomba 4" --codigo BOM-04 --lugar "Planta Norte"
+operx clientes listar
+operx clientes crear --nombre "Acme S.A.S." --nit 900123456
+operx clientes crear --nombre "Filtros Ltda" --rol proveedor
+operx lugares listar
+
+operx inventario existencias --buscar filtro
+operx inventario entrada --articulo FIL-010 --lugar "Bodega central" --cantidad 10 --costo-unitario 1.500,50
+operx inventario salida --articulo FIL-010 --lugar "Bodega central" --cantidad 2 --motivo Consumo
+
+operx lecturas puntos BOM-04
+operx lecturas registrar --punto 12 --valor 73,4
+
+operx personas importar empleados.xlsx               # revisa el archivo, no guarda
+operx personas importar empleados.xlsx --confirmar   # guarda si ninguna fila tiene errores
+```
+
+`operx --help` y `operx ordenes --help` muestran todas las opciones.
+
+- Los equipos, lugares, clientes, artículos y personas se nombran por su
+  código o su nombre exacto. Si dos se llaman igual, `operx` lo dice y pide
+  el id.
+- Los números y las fechas se escriben como en la app: `73,4`, `1.500,50`,
+  `30/10/2026`, `22/10/2026 08:00`.
+- Las listas muestran la primera página; `--todas` las trae todas.
+- `--json` da todo lo que responde la API; `--csv` da un CSV que Excel abre
+  bien (`operx equipos listar --todas --csv > equipos.csv`).
+
+### Antes de escribir
+
+Todo lo que crea o cambia algo pregunta antes. En un script o una tarea
+programada no hay a quién preguntar: agrega `--si`. Cada escritura queda en
+el historial del token (Acceso por API › el token › Actividad) marcada como
+hecha desde la CLI.
+
+### Importar personas
+
+La primera columna con el nombre basta. `operx` reconoce las columnas
+Nombres, Apellidos, Código, Cargo, Tipo de contrato, Fecha de ingreso, Fin de
+contrato, Celular, Sede y las de contacto de emergencia, con o sin tildes.
+Una columna con otro nombre se indica con `--mapa "Tu columna=campo"`.
+Nadie recibe acceso a la app al importarlo: las invitaciones se envían en
+Usuarios y acceso.
+
+### Cualquier otra llamada
+
+Lo que no tiene comando propio se hace con `operx api`, con las direcciones
+de Acceso por API › Documentación (sin `/api/v1/`):
+
+```sh
+operx api GET pm/schedules/ -q search=compresor
+operx api POST contacts/ -d @contacto.json
+operx api GET work-orders/export/ -o ordenes.csv
+operx api POST work-orders/1234/attachments/ -a file=foto.jpg -d '{"file_type": "photo"}'
+```
+
+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
+cd cli
+python -m venv .venv && .venv/Scripts/python -m pip install -e ".[test]"
+.venv/Scripts/python -m pytest
+```
+
+`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.2.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.2.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