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