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 -c "irm https://astral.sh/uv/install.ps1 | iex"; uv tool install operx-cli

Mac y Linux:

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

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:

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

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:

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

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/:

   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:

$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.