Metadata-Version: 2.4
Name: operx-cli
Version: 0.5.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
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`. 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.
