Documentación pública · v1.0.0

05 · Roustix CLI

MSD-05-CLI · Roustix CLI

Automatizar la integración también forma parte de la experiencia del desarrollador.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Definir la interfaz oficial de línea de comandos (CLI) de Roustix, permitiendo a desarrolladores, administradores y pipelines de automatización interactuar con la plataforma sin construir solicitudes HTTP manualmente.

La CLI utiliza el mismo contrato definido en MAG v1.0 y el SDK oficial (MSD-04), ofreciendo una experiencia consistente para desarrollo, pruebas y automatización.

1 · Filosofía

La CLI es el puente entre la API y la automatización.

No reemplaza el SDK ni el Portal para Desarrolladores.

Cada comando ejecuta operaciones utilizando exactamente el mismo contrato REST.

Usuario
      │
      ▼
 roustix-cli
      │
      ▼
 SDK Oficial
      │
      ▼
   OpenAPI
      │
      ▼
 API Roustix

La CLI es un cliente oficial de Roustix.

Rol	Herramienta
Exploración humana	Developer Portal · Quick Start
Integración en código	SDK
Scripts · CI/CD	CLI

2 · Instalación

Python (PyPI)

pip install roustix-cli

Verificación

roustix --version

Salida esperada:

Roustix CLI 1.0.0
API MAG v1

Estado: paquete roustix-cli planificado · especificación MSD-05 entregada.

3 · Configuración

Primer inicio:

roustix login

El asistente solicita:

URL del servidor
Usuario
Contraseña
Empresa (empresa_slug)

Configuración almacenada localmente:

~/.roustix/config.yaml

Ejemplo:

server: https://api.roustix.app
empresa: empresa-demo
token: "************"

El token nunca se almacena en texto plano cuando el sistema operativo dispone de un almacén seguro de credenciales (Keychain · Credential Manager · Secret Service).

Variables de entorno alternativas para CI:

export ROUSTIX_TOKEN=<jwt>

4 · Autenticación

La CLI utiliza el endpoint oficial:

POST /api/v1/auth/login

→ MAG-02 · JWT

Una vez autenticado:

roustix whoami

Resultado:

Usuario : Ana García
Empresa : Empresa Demo
Rol     : Admin
Plan    : Grow

Equivalente a GET /api/v1/me con contexto enriquecido cuando el plan esté disponible en el token.

5 · Organización de comandos

roustix
│
├── login
├── logout
├── whoami
│
├── assets
│     ├── list
│     ├── get
│     ├── create
│     └── delete
│
├── work-orders
├── inventory
├── purchases
├── sales
├── admin
│
├── openapi
├── config
└── version

La estructura refleja exactamente los recursos definidos en MAG-04.

Comando	Recurso MAG
`roustix assets`	`maintenance/assets`
`roustix work-orders`	`maintenance/work-orders`
`roustix inventory`	`inventory/*`
`roustix admin`	`admin/*`

6 · Ejemplos

Listar activos:

roustix assets list

Obtener un activo:

roustix assets get 25

Crear una orden:

roustix work-orders create

Consultar inventario:

roustix inventory products list

Todos los comandos invocan el SDK internamente — no construyen HTTP manualmente.

7 · Formatos de salida

Formato por defecto — tabla legible en terminal:

┌────┬──────────┬─────────────┐
│ ID │ Código   │ Nombre      │
├────┼──────────┼─────────────┤
│ 25 │ CMP-025  │ Compresor B │
└────┴──────────┴─────────────┘

Salida JSON (automatización):

roustix assets list --json

Salida YAML:

roustix assets list --yaml

Salida CSV:

roustix assets list --csv

Flag	Uso
`--json`	Pipelines · jq · scripts
`--yaml`	Config · legibilidad
`--csv`	Excel · reportes
(default)	Operación interactiva humana

8 · Automatización

La CLI está diseñada para integrarse con:

GitHub Actions
GitLab CI
Azure DevOps
Jenkins
Scripts Bash
PowerShell

Ejemplo:

roustix inventory stock-low --json

Puede utilizarse directamente dentro de pipelines CI/CD.

# GitHub Actions (conceptual)
- name: Check low stock
  env:
    ROUSTIX_TOKEN: ${{ secrets.ROUSTIX_TOKEN }}
  run: roustix inventory stock-low --json

9 · OpenAPI

Descargar la especificación oficial:

roustix openapi download

Resultado: openapi.v1.yaml

Opciones:

roustix openapi validate
roustix openapi version

Basado en MSD-03 · OpenAPI 3.1.

Comando	Acción
`openapi download`	Guarda spec desde `/api/v1/openapi.yaml`
`openapi validate`	Lint local (Spectral)
`openapi version`	Muestra `info.version` del contrato

10 · Buenas prácticas

#	Regla
1	Nunca almacenar tokens en scripts versionados
2	Utilizar variables de entorno para automatización
3	Mantener la CLI sincronizada con MAG
4	Toda operación utiliza el SDK oficial
5	Respetar los códigos de error definidos en MAG-06
6	Mostrar mensajes legibles y códigos de salida estándar
7	Preferir `--json` en CI · tabla en terminal interactiva

11 · Códigos de salida

Código	Significado
0	Operación exitosa
1	Error de ejecución genérico
2	Error de autenticación
3	Error de validación
4	Error de conexión
5	Error interno

Estos códigos facilitan la integración con scripts y pipelines.

Los errores API mapean desde MAG-06:

HTTP / `error.code`	Exit code CLI
401 · `UNAUTHORIZED`	2
422 · `VALIDATION_ERROR`	3
Timeout · red	4
500 · `INTERNAL_ERROR`	5

12 · Roadmap

Próximas funcionalidades:

autocompletado para Bash, Zsh y PowerShell
actualización automática (roustix update)
plugins oficiales
modo interactivo (roustix shell)
gestión de múltiples perfiles (roustix config use staging)
diagnóstico (roustix doctor)
importación y exportación masiva

Filosofía del capítulo

La CLI convierte el contrato MAG en acciones ejecutables desde la terminal — sin fricción para DevOps, soporte y desarrolladores que automatizan Roustix.

Junto al SDK y al Portal para Desarrolladores, completa el triángulo de integración: explorar · codificar · automatizar.

← 04 · SDK 06 · Sandbox →