operx-cli 0.1.0__py3-none-any.whl

operx_cli/commands/ordenes.py

@@ -0,0 +1,187 @@
+"""`operx ordenes`: Trabajos' work orders."""
+
+from enum import Enum
+from typing import Annotated, Optional
+
+import typer
+
+from ..lookup import find_one
+from ..output import print_record, print_rows
+from .common import (
+    AllOption, CsvOption, JsonOption, SearchOption, YesOption, client_of, confirm_write, day, list_rows,
+    output_format, without_empty,
+)
+
+app = typer.Typer(help="Órdenes de trabajo: verlas, crearlas, moverlas de estado, asignarlas y comentarlas.", no_args_is_help=True)
+
+
+class Estado(str, Enum):
+    abierta = "abierta"
+    en_progreso = "en-progreso"
+    en_espera = "en-espera"
+    completada = "completada"
+    cancelada = "cancelada"
+
+
+class Prioridad(str, Enum):
+    baja = "baja"
+    media = "media"
+    alta = "alta"
+    critica = "critica"
+
+
+class Tipo(str, Enum):
+    correctivo = "correctivo"
+    preventivo = "preventivo"
+    predictivo = "predictivo"
+    inspeccion = "inspeccion"
+    infraestructura = "infraestructura"
+
+
+# Verifying an order is a person's sign-off in the app: the API refuses it
+# to a token, so it isn't offered here.
+STATUS_KEYS = {
+    "abierta": "open", "en-progreso": "in_progress", "en-espera": "on_hold",
+    "completada": "completed", "cancelada": "cancelled",
+}
+STATUS_LABELS = {
+    "open": "Abierta", "in_progress": "En progreso", "on_hold": "En espera",
+    "completed": "Completada", "verified": "Verificada", "cancelled": "Cancelada",
+}
+PRIORITY_KEYS = {"baja": "low", "media": "medium", "alta": "high", "critica": "critical"}
+PRIORITY_LABELS = {"low": "Baja", "medium": "Media", "high": "Alta", "critical": "Crítica"}
+TYPE_KEYS = {
+    "correctivo": "corrective", "preventivo": "preventive", "predictivo": "predictive",
+    "inspeccion": "inspection", "infraestructura": "infrastructure",
+}
+COLUMNS = [
+    ("id", "ID"), ("title", "Título"), ("status", "Estado"), ("priority", "Prioridad"),
+    ("assigned_to_name", "Asignada a"), ("asset_name", "Equipo"), ("site_name", "Lugar"), ("due_date", "Vence"),
+]
+
+PersonOption = Annotated[
+    Optional[str], typer.Option("--asignada-a", help="«yo», o el nombre o código de la persona.")
+]
+
+
+def _in_spanish(order):
+    return {
+        **order,
+        "status": STATUS_LABELS.get(order.get("status"), order.get("status")),
+        "priority": PRIORITY_LABELS.get(order.get("priority"), order.get("priority")),
+        "due_date": (order.get("due_date") or "")[:10],
+    }
+
+
+def account_id(client, person):
+    """The account a work order is assigned to: «yo», or a person found by
+    name or code among the maintenance staff (their user_id, not their
+    record's id)."""
+    if person.strip().casefold() == "yo":
+        return client.get("auth/me")["id"]
+    return find_one(client, "employees", person, ["user_name", "employee_code"], "persona")["user_id"]
+
+
+@app.command()
+def listar(
+    ctx: typer.Context,
+    estado: Annotated[Optional[Estado], typer.Option("--estado", help="Solo las de este estado.")] = None,
+    prioridad: Annotated[Optional[Prioridad], typer.Option("--prioridad", help="Solo las de esta prioridad.")] = None,
+    asignada_a: PersonOption = None,
+    vencidas: Annotated[bool, typer.Option("--vencidas", help="Solo las vencidas.")] = False,
+    buscar: SearchOption = None,
+    todas: AllOption = False,
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Las órdenes de trabajo que puedes ver."""
+    output = output_format(as_json, as_csv)
+    client = client_of(ctx)
+    params = {
+        "status": STATUS_KEYS[estado.value] if estado else None,
+        "priority": PRIORITY_KEYS[prioridad.value] if prioridad else None,
+        "assigned_to_id": account_id(client, asignada_a) if asignada_a else None,
+        "overdue": "true" if vencidas else None,
+        "search": buscar,
+    }
+    orders = list_rows(client, "work-orders", params, todas)
+    print_rows(COLUMNS, orders if output == "json" else [_in_spanish(order) for order in orders], output)
+
+
+@app.command()
+def ver(ctx: typer.Context, orden: Annotated[int, typer.Argument(help="El número de la orden.")], as_json: JsonOption = False):
+    """Una orden de trabajo, con todos sus datos."""
+    print_record(client_of(ctx).get(f"work-orders/{orden}"), output_format(as_json, False))
+
+
+@app.command()
+def crear(
+    ctx: typer.Context,
+    titulo: Annotated[str, typer.Option("--titulo", help="Qué hay que hacer.")],
+    descripcion: Annotated[Optional[str], typer.Option("--descripcion")] = None,
+    prioridad: Annotated[Optional[Prioridad], typer.Option("--prioridad")] = None,
+    tipo: Annotated[Optional[Tipo], typer.Option("--tipo")] = None,
+    equipo: Annotated[Optional[str], typer.Option("--equipo", help="El código o nombre del equipo.")] = None,
+    lugar: Annotated[Optional[str], typer.Option("--lugar", help="El nombre del lugar.")] = None,
+    cliente: Annotated[Optional[str], typer.Option("--cliente", help="El nombre o NIT del cliente.")] = None,
+    asignar_a: Annotated[Optional[str], typer.Option("--asignar-a", help="«yo», o el nombre o código de la persona.")] = None,
+    vence: Annotated[Optional[str], typer.Option("--vence", help="La fecha límite: 30/10/2026.")] = None,
+    si: YesOption = False,
+):
+    """Crea una orden de trabajo."""
+    client = client_of(ctx)
+    order = without_empty({
+        "title": titulo,
+        "description": descripcion,
+        "priority": PRIORITY_KEYS[prioridad.value] if prioridad else None,
+        "work_type": TYPE_KEYS[tipo.value] if tipo else None,
+        "asset_id": find_one(client, "assets", equipo, ["code", "name"], "equipo")["id"] if equipo else None,
+        "site_id": find_one(client, "locations", lugar, ["name"], "lugar")["id"] if lugar else None,
+        "customer_id": find_one(client, "customers", cliente, ["name", "tax_id"], "cliente")["id"] if cliente else None,
+        "assigned_to_id": account_id(client, asignar_a) if asignar_a else None,
+        "due_date": day(vence),
+    })
+    confirm_write(f"Crear la orden «{titulo}».", si)
+    created = client.send("POST", "work-orders", json=order).json()
+    typer.echo(f"Orden {created['id']} creada: {created['title']}.")
+
+
+@app.command()
+def estado(
+    ctx: typer.Context,
+    orden: Annotated[int, typer.Argument(help="El número de la orden.")],
+    nuevo: Annotated[Estado, typer.Argument(help="El estado al que pasa.")],
+    si: YesOption = False,
+):
+    """Cambia el estado de una orden. Verificarla se hace en la app."""
+    confirm_write(f"Pasar la orden {orden} a «{nuevo.value}».", si)
+    changed = client_of(ctx).send("POST", f"work-orders/{orden}/transition", json={"status": STATUS_KEYS[nuevo.value]}).json()
+    typer.echo(f"Orden {orden}: {STATUS_LABELS.get(changed.get('status'), changed.get('status'))}.")
+
+
+@app.command()
+def asignar(
+    ctx: typer.Context,
+    orden: Annotated[int, typer.Argument(help="El número de la orden.")],
+    persona: Annotated[str, typer.Argument(help="«yo», «nadie», o el nombre o código de la persona.")],
+    si: YesOption = False,
+):
+    """Asigna una orden a una persona, que recibe el aviso."""
+    client = client_of(ctx)
+    account = None if persona.strip().casefold() == "nadie" else account_id(client, persona)
+    confirm_write(f"Asignar la orden {orden} a {persona}.", si)
+    client.send("POST", f"work-orders/{orden}/assign", json={"assigned_to_id": account})
+    typer.echo(f"Orden {orden} asignada a {persona}.")
+
+
+@app.command()
+def comentar(
+    ctx: typer.Context,
+    orden: Annotated[int, typer.Argument(help="El número de la orden.")],
+    texto: Annotated[str, typer.Argument(help="El comentario.")],
+    si: YesOption = False,
+):
+    """Agrega un comentario a una orden."""
+    confirm_write(f"Comentar en la orden {orden}.", si)
+    client_of(ctx).send("POST", f"work-orders/{orden}/comments", json={"body": texto})
+    typer.echo(f"Comentario agregado a la orden {orden}.")

operx_cli/commands/personas.py

@@ -0,0 +1,107 @@
+"""`operx personas importar`: a company's people from its own Excel, into
+Personas (backend/people/import_views.py).
+
+Every run checks the whole file first and shows each row's errors; with
+--confirmar, a clean file is saved all at once, or nothing is saved. Nobody
+gets access to the app here: invitations are sent from Usuarios y acceso.
+"""
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from ..lookup import NoSingleMatch, find_one
+from ..output import note, print_rows
+from ..spreadsheet import DATE_FIELDS, people_rows
+from .common import CliError, YesOption, client_of, confirm_write
+
+app = typer.Typer(help="Personas: la gente de tu empresa.", no_args_is_help=True)
+
+# The API takes at most this many rows a call (people/import_views.py).
+MAX_ROWS = 1000
+BAD_DATE = "no se entiende la fecha; escríbela como 31/12/2026."
+REPORT_COLUMNS = [("line", "Fila"), ("name", "Nombre"), ("result", "Resultado")]
+
+
+def _with_place_ids(client, people):
+    """A "Sede" column holds a place's name; the API takes its id."""
+    found = {}
+    rows = []
+    for line, person in zip(people.lines, people.rows):
+        person = dict(person)
+        place_name = person.pop("sede", None)
+        if place_name:
+            if place_name not in found:
+                try:
+                    found[place_name] = find_one(client, "locations", place_name, ["name"], "sede")["id"]
+                except NoSingleMatch as error:
+                    raise CliError(f"Fila {line}: {error}") from None
+            person["branch_id"] = found[place_name]
+        rows.append(person)
+    return rows
+
+
+def _errors_text(errors, columns):
+    parts = []
+    for field, messages in errors.items():
+        text = " ".join(messages) if isinstance(messages, list) else str(messages)
+        if field in DATE_FIELDS:
+            # The API names its own format (YYYY-MM-DD); the file is read day first.
+            text = BAD_DATE
+        column = columns.get(field)
+        parts.append(f"{column}: {text}" if column else text)
+    return "; ".join(parts)
+
+
+def _show_report(answer, people):
+    columns = {field: column for column, field in people.mapping.items()}
+    columns["branch_id"] = columns.get("sede")
+    report = [
+        {
+            "line": people.lines[row["row"] - 1],
+            "name": row["name"],
+            "result": "Bien" if row["ok"] else _errors_text(row["errors"], columns),
+        }
+        for row in answer.get("report", [])
+    ]
+    print_rows(REPORT_COLUMNS, report, "tabla")
+
+
+@app.command()
+def importar(
+    ctx: typer.Context,
+    archivo: Annotated[Path, typer.Argument(help="El Excel (.xlsx) o CSV con una persona por fila.")],
+    hoja: Annotated[Optional[str], typer.Option("--hoja", help="La hoja del Excel; sin ella, la primera.")] = None,
+    mapa: Annotated[
+        Optional[list[str]],
+        typer.Option("--mapa", help="Una columna que no se reconoce: \"Tu columna=campo\". Se repite."),
+    ] = None,
+    confirmar: Annotated[bool, typer.Option("--confirmar", help="Guarda las personas si ninguna fila tiene errores.")] = False,
+    si: YesOption = False,
+):
+    """Importa personas desde un Excel. Sin --confirmar solo revisa el archivo y no guarda nada."""
+    people = people_rows(archivo, mapa, hoja)
+    if not people.rows:
+        raise CliError("El archivo no tiene filas con datos.")
+    if len(people.rows) > MAX_ROWS:
+        raise CliError(f"El archivo tiene {len(people.rows)} filas y se importan hasta {MAX_ROWS} por vez: divídelo.")
+    note("Columnas: " + ", ".join(f"{column} → {field}" for column, field in people.mapping.items()))
+    if people.ignored:
+        note("Sin usar: " + ", ".join(people.ignored))
+
+    client = client_of(ctx)
+    rows = _with_place_ids(client, people)
+    preview = client.send("POST", "people/import", json={"rows": rows, "dry_run": True}).json()
+    _show_report(preview, people)
+    if preview["with_errors"]:
+        raise CliError(
+            f"{preview['with_errors']} de {preview['rows']} filas tienen errores: corrígelas en el archivo. No se guardó nada."
+        )
+    if not confirmar:
+        note("Es una prueba: no se guardó nada. Para guardar, repite con --confirmar.")
+        return
+
+    confirm_write(f"Guardar {len(rows)} personas en Personas.", si)
+    saved = client.send("POST", "people/import", json={"rows": rows, "dry_run": False}).json()
+    typer.echo(f"Se guardaron {saved['saved']} personas. Nadie recibió acceso a la app: invítalos en Usuarios y acceso.")

operx_cli/commands/raw.py

@@ -0,0 +1,114 @@
+"""`operx api`: any call a token may make (Acceso por API › Documentación
+lists them), for what has no command of its own yet."""
+
+import json
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from ..client import ApiError, api_path
+from ..output import json_text, note
+from .common import AllOption, CliError, YesOption, client_of, confirm_write
+
+METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+
+
+def _pairs(texts, what):
+    """['search=acme', 'page=2'] → {'search': 'acme', 'page': '2'}."""
+    pairs = {}
+    for text in texts or []:
+        key, equals, value = text.partition("=")
+        if not equals or not key.strip():
+            raise CliError(f"«{text}» no es {what}: escríbelo como nombre=valor.")
+        pairs[key.strip()] = value
+    return pairs
+
+
+def _body(text):
+    """The JSON to send: written out, or read from a file with @archivo.json."""
+    if text is None:
+        return None
+    if text.startswith("@"):
+        path = Path(text[1:])
+        if not path.exists():
+            raise CliError(f"No existe el archivo {path}.")
+        text = path.read_text(encoding="utf-8-sig")
+    try:
+        return json.loads(text)
+    except ValueError as error:
+        raise CliError(f"Los datos no son JSON válido: {error}") from None
+
+
+def _form_fields(body):
+    """With files, the other fields go as a form: text for each one."""
+    if body is None:
+        return None
+    if not isinstance(body, dict):
+        raise CliError("Con --adjunto, los datos deben ser un objeto JSON: {\"campo\": \"valor\"}.")
+    return {key: value if isinstance(value, str) else json.dumps(value) for key, value in body.items()}
+
+
+def _show(response, salida):
+    if salida:
+        salida.write_bytes(response.content)
+        note(f"Guardado en {salida}.")
+        return
+    content_type = response.headers.get("Content-Type", "")
+    if not response.content:
+        note("Hecho.")
+    elif "json" in content_type:
+        typer.echo(json_text(response.json()))
+    elif content_type.startswith("text/"):
+        typer.echo(response.text, nl=False)
+    else:
+        raise CliError(f"La respuesta es un archivo ({content_type}): guárdala con --salida archivo.")
+
+
+def api(
+    ctx: typer.Context,
+    metodo: Annotated[str, typer.Argument(help="GET, POST, PATCH, PUT o DELETE.")],
+    ruta: Annotated[str, typer.Argument(help="La dirección, como en la documentación: /work-orders/ o /customers/12/.")],
+    consulta: Annotated[Optional[list[str]], typer.Option("--consulta", "-q", help="Un filtro, nombre=valor. Se repite.")] = None,
+    datos: Annotated[Optional[str], typer.Option("--datos", "-d", help="El JSON a enviar, o @archivo.json.")] = None,
+    adjunto: Annotated[Optional[list[str]], typer.Option("--adjunto", "-a", help="Un archivo a subir, campo=ruta. Se repite.")] = None,
+    todas: AllOption = False,
+    salida: Annotated[Optional[Path], typer.Option("--salida", "-o", help="Guarda la respuesta en este archivo (CSV, PDF…).")] = None,
+    si: YesOption = False,
+):
+    """Cualquier llamada que tu token pueda hacer. Responde el JSON de la API."""
+    method = metodo.upper()
+    if method not in METHODS:
+        raise CliError(f"«{metodo}» no es un método: usa {', '.join(METHODS)}.")
+    params = _pairs(consulta, "un filtro")
+    body = _body(datos)
+    files = _pairs(adjunto, "un adjunto")
+    if todas and method != "GET":
+        raise CliError("--todas es solo para GET.")
+    if method != "GET":
+        confirm_write(f"{method} {ruta}", si)
+
+    client = client_of(ctx)
+    try:
+        if todas:
+            typer.echo(json_text(client.all_pages(ruta, params)))
+            return
+        with ExitStack() as stack:
+            opened = {}
+            for field, path in files.items():
+                if not Path(path).exists():
+                    raise CliError(f"No existe el archivo {path}.")
+                opened[field] = (Path(path).name, stack.enter_context(open(path, "rb")))
+            response = client.send(
+                method, ruta, params=params or None,
+                json=None if opened else body,
+                data=_form_fields(body) if opened else None,
+                files=opened or None,
+            )
+    except ApiError as error:
+        if error.status != 404:
+            raise
+        # Git Bash rewrites "/work-orders/" into a Windows path: show what was asked.
+        raise ApiError(404, f"{error} ({method} {api_path(ruta)})") from None
+    _show(response, salida)

operx_cli/commands/registros.py

@@ -0,0 +1,192 @@
+"""Registros, the records every product shares: `operx equipos`, `operx
+clientes` and `operx lugares`."""
+
+from enum import Enum
+from typing import Annotated, Optional
+
+import typer
+
+from ..lookup import find_one
+from ..output import print_record, print_rows
+from .common import (
+    AllOption, CsvOption, JsonOption, SearchOption, YesOption, client_of, confirm_write, list_rows, output_format,
+    without_empty,
+)
+
+equipos = typer.Typer(help="Equipos (Registros): las máquinas y activos de tu empresa.", no_args_is_help=True)
+clientes = typer.Typer(help="Clientes y proveedores (Registros).", no_args_is_help=True)
+lugares = typer.Typer(help="Lugares (Registros): sedes, plantas, bodegas y vehículos.", no_args_is_help=True)
+
+ASSET_COLUMNS = [
+    ("id", "ID"), ("code", "Código"), ("name", "Nombre"), ("status", "Estado"), ("category_name", "Categoría"),
+    ("site_name", "Lugar"), ("customer_name", "Cliente"),
+]
+ASSET_STATUS_LABELS = {
+    "active": "Activo", "inactive": "Inactivo", "under_maintenance": "En mantenimiento", "decommissioned": "Dado de baja",
+}
+CUSTOMER_COLUMNS = [
+    ("id", "ID"), ("name", "Nombre"), ("tax_id", "NIT"), ("contract_status", "Contrato"), ("is_active", "Activo"),
+]
+CONTRACT_LABELS = {"active": "Activo", "pending": "Pendiente", "expired": "Vencido", "cancelled": "Cancelado"}
+PLACE_COLUMNS = [
+    ("id", "ID"), ("name", "Nombre"), ("kind_label", "Tipo"), ("path", "Dentro de"), ("city", "Ciudad"),
+    ("customer_name", "Cliente"), ("is_active", "Activo"),
+]
+
+
+class Rol(str, Enum):
+    cliente = "cliente"
+    proveedor = "proveedor"
+    gestor = "gestor"
+    laboratorio = "laboratorio"
+    consultor = "consultor"
+
+
+# customers/models.py ROLES: Ambiental's outside firms are the last three.
+ROLE_KEYS = {
+    "cliente": "client", "proveedor": "supplier", "gestor": "waste_manager",
+    "laboratorio": "lab", "consultor": "consultant",
+}
+
+
+def _labelled(rows, field, labels, output):
+    if output == "json":
+        return rows
+    return [{**row, field: labels.get(row.get(field), row.get(field))} for row in rows]
+
+
+# ── Equipos ────────────────────────────────────────────────────────────────
+
+
+@equipos.command("listar")
+def listar_equipos(
+    ctx: typer.Context,
+    buscar: SearchOption = None,
+    todas: AllOption = False,
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Los equipos que puedes ver."""
+    output = output_format(as_json, as_csv)
+    rows = list_rows(client_of(ctx), "assets", {"search": buscar}, todas)
+    print_rows(ASSET_COLUMNS, _labelled(rows, "status", ASSET_STATUS_LABELS, output), output)
+
+
+@equipos.command("ver")
+def ver_equipo(
+    ctx: typer.Context,
+    equipo: Annotated[str, typer.Argument(help="El código, nombre o id del equipo.")],
+    as_json: JsonOption = False,
+):
+    """Un equipo, con todos sus datos."""
+    client = client_of(ctx)
+    found = find_one(client, "assets", equipo, ["code", "name"], "equipo")
+    print_record(client.get(f"assets/{found['id']}"), output_format(as_json, False))
+
+
+@equipos.command("crear")
+def crear_equipo(
+    ctx: typer.Context,
+    nombre: Annotated[str, typer.Option("--nombre")],
+    codigo: Annotated[Optional[str], typer.Option("--codigo")] = None,
+    lugar: Annotated[Optional[str], typer.Option("--lugar", help="El nombre del lugar donde está.")] = None,
+    categoria: Annotated[Optional[str], typer.Option("--categoria", help="El nombre de su categoría.")] = None,
+    serie: Annotated[Optional[str], typer.Option("--serie", help="El número de serie.")] = None,
+    fabricante: Annotated[Optional[str], typer.Option("--fabricante")] = None,
+    modelo: Annotated[Optional[str], typer.Option("--modelo")] = None,
+    etiqueta: Annotated[Optional[str], typer.Option("--etiqueta", help="Su etiqueta en otro sistema (SCADA, ERP).")] = None,
+    si: YesOption = False,
+):
+    """Crea un equipo."""
+    client = client_of(ctx)
+    asset = without_empty({
+        "name": nombre,
+        "code": codigo,
+        "site_id": find_one(client, "locations", lugar, ["name"], "lugar")["id"] if lugar else None,
+        "category_id": find_one(client, "assets/categories", categoria, ["name"], "categoría")["id"] if categoria else None,
+        "serial_number": serie,
+        "manufacturer": fabricante,
+        "model_number": modelo,
+        "external_tag": etiqueta,
+    })
+    confirm_write(f"Crear el equipo «{nombre}».", si)
+    created = client.send("POST", "assets", json=asset).json()
+    typer.echo(f"Equipo {created['id']} creado: {created['name']}.")
+
+
+# ── Clientes ───────────────────────────────────────────────────────────────
+
+
+@clientes.command("listar")
+def listar_clientes(
+    ctx: typer.Context,
+    buscar: SearchOption = None,
+    todas: AllOption = False,
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Los clientes y proveedores que puedes ver."""
+    output = output_format(as_json, as_csv)
+    rows = list_rows(client_of(ctx), "customers", {"search": buscar}, todas)
+    print_rows(CUSTOMER_COLUMNS, _labelled(rows, "contract_status", CONTRACT_LABELS, output), output)
+
+
+@clientes.command("ver")
+def ver_cliente(
+    ctx: typer.Context,
+    cliente: Annotated[str, typer.Argument(help="El nombre, NIT o id.")],
+    as_json: JsonOption = False,
+):
+    """Un cliente o proveedor, con todos sus datos."""
+    client = client_of(ctx)
+    found = find_one(client, "customers", cliente, ["name", "tax_id", "legal_name"], "cliente")
+    print_record(client.get(f"customers/{found['id']}"), output_format(as_json, False))
+
+
+@clientes.command("crear")
+def crear_cliente(
+    ctx: typer.Context,
+    nombre: Annotated[str, typer.Option("--nombre")],
+    nit: Annotated[Optional[str], typer.Option("--nit")] = None,
+    razon_social: Annotated[Optional[str], typer.Option("--razon-social")] = None,
+    telefono: Annotated[Optional[str], typer.Option("--telefono")] = None,
+    ciudad: Annotated[Optional[str], typer.Option("--ciudad")] = None,
+    correo_facturacion: Annotated[Optional[str], typer.Option("--correo-facturacion")] = None,
+    direccion_facturacion: Annotated[Optional[str], typer.Option("--direccion-facturacion")] = None,
+    notas: Annotated[Optional[str], typer.Option("--notas")] = None,
+    rol: Annotated[
+        Optional[list[Rol]], typer.Option("--rol", help="cliente (sin --rol), proveedor, gestor, laboratorio o consultor. Se repite.")
+    ] = None,
+    si: YesOption = False,
+):
+    """Crea un cliente o proveedor."""
+    customer = without_empty({
+        "name": nombre,
+        "tax_id": nit,
+        "legal_name": razon_social,
+        "phone": telefono,
+        "city": ciudad,
+        "billing_email": correo_facturacion,
+        "billing_address": direccion_facturacion,
+        "notes": notas,
+    })
+    customer["roles"] = [ROLE_KEYS[role.value] for role in rol] if rol else ["client"]
+    confirm_write(f"Crear «{nombre}».", si)
+    created = client_of(ctx).send("POST", "customers", json=customer).json()
+    typer.echo(f"«{created['name']}» creado con el id {created['id']}.")
+
+
+# ── Lugares ────────────────────────────────────────────────────────────────
+
+
+@lugares.command("listar")
+def listar_lugares(
+    ctx: typer.Context,
+    buscar: SearchOption = None,
+    todas: AllOption = False,
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Los lugares de tu empresa y de tus clientes."""
+    rows = list_rows(client_of(ctx), "locations", {"search": buscar}, todas)
+    print_rows(PLACE_COLUMNS, rows, output_format(as_json, as_csv))

operx_cli/commands/search.py

@@ -0,0 +1,21 @@
+"""`operx buscar`: the app's top bar search, across everything you may open."""
+
+from typing import Annotated
+
+import typer
+
+from ..output import print_rows
+from .common import CsvOption, JsonOption, client_of, output_format
+
+COLUMNS = [("kind", "Tipo"), ("id", "ID"), ("title", "Nombre"), ("subtitle", "Detalle")]
+
+
+def buscar(
+    ctx: typer.Context,
+    texto: Annotated[str, typer.Argument(help="Lo que buscas; desde 2 letras.")],
+    as_json: JsonOption = False,
+    as_csv: CsvOption = False,
+):
+    """Busca órdenes, equipos, clientes, lugares y personas, como la barra de arriba de la app."""
+    answer = client_of(ctx).get("search", {"q": texto})
+    print_rows(COLUMNS, answer.get("results", []), output_format(as_json, as_csv))

operx_cli/lookup.py

@@ -0,0 +1,42 @@
+"""Finding a record by what people type (a code, a name) instead of its id.
+
+Only an exact match counts, ignoring case and extra spaces: a search's first
+hit is never taken, so "Bodega" can't move stock into "Bodega central norte".
+A number nobody is called is taken as the record's id.
+"""
+
+
+class NoSingleMatch(Exception):
+    pass
+
+
+def plural(word):
+    return word + ("s" if word[-1] in "aeiouáéíóú" else "es")
+
+
+def _normalized(text):
+    return " ".join(str(text).split()).casefold()
+
+
+def find_in(rows, text, fields, what):
+    """The one row whose `fields` hold exactly `text`."""
+    wanted = _normalized(text)
+    matches = [row for row in rows if any(_normalized(row.get(field) or "") == wanted for field in fields)]
+    if len(matches) == 1:
+        return matches[0]
+    if matches:
+        ids = ", ".join(str(row["id"]) for row in matches)
+        raise NoSingleMatch(f"Hay {len(matches)} {plural(what)} con «{text}» (ids {ids}): usa el id.")
+    raise NoSingleMatch(f"No se encontró «{text}» entre los {plural(what)}.")
+
+
+def find_one(client, path, text, fields, what, params=None):
+    """The record at `path` (a list address) called `text`: searched in the
+    API, matched exactly here, or read by id when `text` is a number."""
+    rows = client.all_pages(path, {**(params or {}), "search": text})
+    try:
+        return find_in(rows, text, fields, what)
+    except NoSingleMatch:
+        if str(text).strip().isdigit():
+            return client.get(f"{path.rstrip('/')}/{str(text).strip()}/")
+        raise