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: uv tool upgrade operx-cli.

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

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

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

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

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:

   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.