operx-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{operx_cli-0.4.0/operx_cli.egg-info → operx_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: operx-cli
-Version: 0.4.0
+Version: 0.6.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
@@ -80,9 +80,11 @@ este equipo. Un token puesto en `OPERX_TOKEN` no lo toca.
 ## 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:
+con un prompt: quién eres, un aviso si tu acceso vence en menos de una
+semana, y los números de hoy de cada producto de tu empresa (órdenes abiertas
+y vencidas, artículos bajo el mínimo, equipos parados, acciones del SG-SST,
+obligaciones ambientales del mes). Ahí escribes los comandos sin el `operx`,
+con Tab para completar y ↑ para repetir lo anterior:
 
 ```
 operx › ordenes listar --vencidas
@@ -95,6 +97,14 @@ operx › salir
 muestran solo los comandos de los productos que tiene tu empresa. En un script
 o una tubería, `operx` solo muestra la ayuda y no espera a nadie.
 
+### Tab en PowerShell
+
+`operx completar` hace que Tab complete los comandos y las opciones de operx
+también en tu PowerShell de siempre (`operx ord` + Tab → `operx ordenes`).
+Pregunta antes de agregar una línea a tu perfil de PowerShell, y `operx
+completar --quitar` la quita. No toca la política de ejecución: si tu
+PowerShell no corre scripts, te dice la línea para permitir los tuyos.
+
 ## Comandos
 
 ```sh
@@ -124,10 +134,17 @@ operx preventivos ejecuciones 12
 operx equipos listar --buscar compresor
 operx equipos ver BOM-04
 operx equipos crear --nombre "Bomba 4" --codigo BOM-04 --lugar "Planta Norte"
+operx equipos editar BOM-04 --estado en-mantenimiento --lugar "Taller"
 operx clientes listar
 operx clientes crear --nombre "Acme S.A.S." --nit 900123456
 operx clientes crear --nombre "Filtros Ltda" --rol proveedor
+operx clientes editar 900123456 --telefono "601 555 0101"
 operx lugares listar
+operx lugares crear --nombre "Bodega central" --tipo bodega --dentro-de "Planta Norte"
+
+operx articulos listar --bajo-minimo
+operx articulos ver FIL-010
+operx articulos crear --nombre "Filtro de aceite" --unidad und --tipo consumible
 
 operx inventario existencias --buscar filtro
 operx inventario entrada --articulo FIL-010 --lugar "Bodega central" --cantidad 10 --costo-unitario 1.500,50
@@ -179,7 +196,9 @@ llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
 ### 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
+programada no hay a quién preguntar: agrega `--si`. Con `--json`, lo que
+escribe responde el registro creado o cambiado (con su `id`) en vez de una
+frase. Cada escritura queda en
 el historial del token (Acceso por API › el token › Actividad) marcada como
 hecha desde la CLI.
 
@@ -194,13 +213,17 @@ Usuarios y acceso.
 
 ### Cualquier otra llamada
 
-Lo que no tiene comando propio se hace con `operx api`. `operx api rutas`
-lista todas las direcciones que tu token puede llamar (`operx api rutas
-compresor` deja las que lo mencionan); también están en Acceso por API ›
-Documentación:
+Lo que no tiene comando propio se hace con `operx api`: todo lo que tu
+token puede hacer, más de 400 llamadas. `operx api rutas` las lista
+(`operx api rutas sst inspections` deja las que tienen esas palabras), y
+`operx api campos RUTA` dice qué lleva una: sus filtros, cada campo con su
+tipo, si es obligatorio y los valores permitidos. También están en Acceso
+por API › Documentación:
 
 ```sh
-operx api rutas schedules
+operx api rutas repuestos
+operx api campos inventory/work-orders/1234/parts/ --metodo POST
+operx api POST inventory/work-orders/1234/parts/ -d '{"action": "usar", "item": 3, "quantity": "2", "location": 2}'
 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_cli-0.4.0/PKG-INFO → operx_cli-0.6.0/README.md

@@ -1,257 +1,266 @@
-Metadata-Version: 2.4
-Name: operx-cli
-Version: 0.4.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: `operx update`. La pantalla de bienvenida avisa cuando hay una
-versión nueva. En Windows la instala otra ventana, que espera a que se cierre
-`operx` (Windows no deja reemplazar un programa abierto); si quedó a medias,
-`uv tool install operx-cli --force --refresh` lo deja bien.
-
-## 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; en Mac, el Llavero). En un equipo sin llavero, como un servidor
-Linux, queda en un archivo de la carpeta de operx que solo tú puedes leer
-(`~/.config/operx/token-principal`, permisos 600). En un servidor sin
-navegador: `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` cierra la sesión: revoca el token en el servidor y lo borra de
-este equipo. Un token puesto en `OPERX_TOKEN` no lo toca.
-
-## 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. `ayuda` y Tab
-muestran solo los comandos de los productos que tiene tu empresa. 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 ordenes editar 1234 --prioridad critica --vence 05/11/2026
-operx ordenes adjuntar 1234 foto.jpg --momento despues
-
-operx reportes indicadores --dias 30           # MTTR, MTBF, cumplimiento de preventivos
-operx reportes vencidas
-operx reportes carga                           # órdenes por persona
-operx avisos                                   # tus avisos sin leer
-operx agenda                                   # lo que toca esta semana
-
-operx preventivos listar --estado vencidos
-operx preventivos ver 12
-operx preventivos crear --nombre "Lubricar rodamientos" --cada 3 --unidad meses --equipo BOM-04 --proxima 01/11/2026
-operx preventivos nota 12 "Usar grasa EP2"
-operx preventivos ejecuciones 12
-
-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 inventario traslado --articulo FIL-010 --cantidad 2 --de "Bodega central" --a "Camioneta 1"
-operx inventario ajuste --articulo FIL-010 --lugar "Bodega central" --cantidad -1 --motivo Conteo
-operx inventario movimientos --articulo FIL-010
-operx inventario revertir 4512                 # deshace un movimiento equivocado
-
-operx equipos parar BOM-04 --motivo Falla --minutos 90
-operx equipos reanudar 21
-operx equipos hallazgo BOM-04 --titulo "Fuga en el sello" --severidad alta
-operx lecturas anular 31 --motivo "Lectura de otro equipo"
-
-operx lecturas puntos BOM-04
-operx lecturas registrar --punto 12 --valor 73,4
-
-operx personas listar --buscar pérez
-operx personas importar empleados.xlsx               # revisa el archivo, no guarda
-operx personas importar empleados.xlsx --confirmar   # guarda si ninguna fila tiene errores
-
-operx sst acciones --estado abiertas
-operx sst nueva-accion --titulo "Señalizar la salida" --para 15/11/2026 --responsable "Ana Ruiz"
-operx sst accion-hecha 7 --evidencia "Se instalaron dos señales"
-operx sst incidentes
-
-operx ambiental acciones
-operx ambiental permisos
-operx ambiental obligaciones --mes 11/2026
-operx ambiental residuo --corriente "Aceite usado" --kg 12,5
-operx ambiental lectura --medidor Acueducto --valor 1.234,5
-```
-
-SG-SST y Ambiental van por empresa: sin `--empresa`, la de tu cuenta. Si
-llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
-`operx ambiental empresas` las listan.
-
-`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`. `operx api rutas`
-lista todas las direcciones que tu token puede llamar (`operx api rutas
-compresor` deja las que lo mencionan); también están en Acceso por API ›
-Documentación:
-
-```sh
-operx api rutas schedules
-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: 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: `operx update`. La pantalla de bienvenida avisa cuando hay una
+versión nueva. En Windows la instala otra ventana, que espera a que se cierre
+`operx` (Windows no deja reemplazar un programa abierto); si quedó a medias,
+`uv tool install operx-cli --force --refresh` lo deja bien.
+
+## 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; en Mac, el Llavero). En un equipo sin llavero, como un servidor
+Linux, queda en un archivo de la carpeta de operx que solo tú puedes leer
+(`~/.config/operx/token-principal`, permisos 600). En un servidor sin
+navegador: `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` cierra la sesión: revoca el token en el servidor y lo borra de
+este equipo. Un token puesto en `OPERX_TOKEN` no lo toca.
+
+## Modo interactivo
+
+Escribe `operx` solo, en una terminal, y se abre la pantalla de bienvenida
+con un prompt: quién eres, un aviso si tu acceso vence en menos de una
+semana, y los números de hoy de cada producto de tu empresa (órdenes abiertas
+y vencidas, artículos bajo el mínimo, equipos parados, acciones del SG-SST,
+obligaciones ambientales del mes). 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. `ayuda` y Tab
+muestran solo los comandos de los productos que tiene tu empresa. En un script
+o una tubería, `operx` solo muestra la ayuda y no espera a nadie.
+
+### Tab en PowerShell
+
+`operx completar` hace que Tab complete los comandos y las opciones de operx
+también en tu PowerShell de siempre (`operx ord` + Tab → `operx ordenes`).
+Pregunta antes de agregar una línea a tu perfil de PowerShell, y `operx
+completar --quitar` la quita. No toca la política de ejecución: si tu
+PowerShell no corre scripts, te dice la línea para permitir los tuyos.
+
+## 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 ordenes editar 1234 --prioridad critica --vence 05/11/2026
+operx ordenes adjuntar 1234 foto.jpg --momento despues
+
+operx reportes indicadores --dias 30           # MTTR, MTBF, cumplimiento de preventivos
+operx reportes vencidas
+operx reportes carga                           # órdenes por persona
+operx avisos                                   # tus avisos sin leer
+operx agenda                                   # lo que toca esta semana
+
+operx preventivos listar --estado vencidos
+operx preventivos ver 12
+operx preventivos crear --nombre "Lubricar rodamientos" --cada 3 --unidad meses --equipo BOM-04 --proxima 01/11/2026
+operx preventivos nota 12 "Usar grasa EP2"
+operx preventivos ejecuciones 12
+
+operx equipos listar --buscar compresor
+operx equipos ver BOM-04
+operx equipos crear --nombre "Bomba 4" --codigo BOM-04 --lugar "Planta Norte"
+operx equipos editar BOM-04 --estado en-mantenimiento --lugar "Taller"
+operx clientes listar
+operx clientes crear --nombre "Acme S.A.S." --nit 900123456
+operx clientes crear --nombre "Filtros Ltda" --rol proveedor
+operx clientes editar 900123456 --telefono "601 555 0101"
+operx lugares listar
+operx lugares crear --nombre "Bodega central" --tipo bodega --dentro-de "Planta Norte"
+
+operx articulos listar --bajo-minimo
+operx articulos ver FIL-010
+operx articulos crear --nombre "Filtro de aceite" --unidad und --tipo consumible
+
+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 inventario traslado --articulo FIL-010 --cantidad 2 --de "Bodega central" --a "Camioneta 1"
+operx inventario ajuste --articulo FIL-010 --lugar "Bodega central" --cantidad -1 --motivo Conteo
+operx inventario movimientos --articulo FIL-010
+operx inventario revertir 4512                 # deshace un movimiento equivocado
+
+operx equipos parar BOM-04 --motivo Falla --minutos 90
+operx equipos reanudar 21
+operx equipos hallazgo BOM-04 --titulo "Fuga en el sello" --severidad alta
+operx lecturas anular 31 --motivo "Lectura de otro equipo"
+
+operx lecturas puntos BOM-04
+operx lecturas registrar --punto 12 --valor 73,4
+
+operx personas listar --buscar pérez
+operx personas importar empleados.xlsx               # revisa el archivo, no guarda
+operx personas importar empleados.xlsx --confirmar   # guarda si ninguna fila tiene errores
+
+operx sst acciones --estado abiertas
+operx sst nueva-accion --titulo "Señalizar la salida" --para 15/11/2026 --responsable "Ana Ruiz"
+operx sst accion-hecha 7 --evidencia "Se instalaron dos señales"
+operx sst incidentes
+
+operx ambiental acciones
+operx ambiental permisos
+operx ambiental obligaciones --mes 11/2026
+operx ambiental residuo --corriente "Aceite usado" --kg 12,5
+operx ambiental lectura --medidor Acueducto --valor 1.234,5
+```
+
+SG-SST y Ambiental van por empresa: sin `--empresa`, la de tu cuenta. Si
+llevas el SG-SST o lo ambiental de tus clientes, `operx sst empresas` y
+`operx ambiental empresas` las listan.
+
+`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`. Con `--json`, lo que
+escribe responde el registro creado o cambiado (con su `id`) en vez de una
+frase. 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`: todo lo que tu
+token puede hacer, más de 400 llamadas. `operx api rutas` las lista
+(`operx api rutas sst inspections` deja las que tienen esas palabras), y
+`operx api campos RUTA` dice qué lleva una: sus filtros, cada campo con su
+tipo, si es obligatorio y los valores permitidos. También están en Acceso
+por API › Documentación:
+
+```sh
+operx api rutas repuestos
+operx api campos inventory/work-orders/1234/parts/ --metodo POST
+operx api POST inventory/work-orders/1234/parts/ -d '{"action": "usar", "item": 3, "quantity": "2", "location": 2}'
+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.