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

Necesitas Python 3.10 o más nuevo.

```sh
pipx install ./cli          # desde esta carpeta del repositorio
operx --version
```

## Entrar

1. En la app, abre el menú de tu cuenta › **Acceso por API** y crea un token.
   Elige *Lectura y escritura* si vas a crear o cambiar datos.
2. Guárdalo en tu equipo:

   ```sh
   operx entrar        # pega el token; no se muestra
   operx cuenta        # quién eres, tu empresa y tu rol
   ```

El token queda en el llavero del sistema (en Windows, el Administrador de
credenciales), nunca en un archivo. En un servidor sin llavero, usa 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 entrar --direccion https://…
operx --perfil pruebas ordenes listar
```

`operx salir` borra el token de este equipo; para que deje de funcionar,
revócalo en Acceso por API.

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