Skip to content

cli.es.mdx

Latest commit

 

History

History
208 lines (158 loc) · 6.46 KB

cli.es.mdx

File metadata and controls

208 lines (158 loc) · 6.46 KB
Raw
title Referencia de la CLI
description Cada comando `os`, qué hace y los flags más útiles.

Referencia de la CLI

El paquete @objectstack/cli instala un único binario, os (también disponible como objectstack). Todos los ejemplos a continuación usan el os más corto.

npm i -g @objectstack/cli
os --help

Comandos del servidor

os start — arranque sin configuración

Detecta automáticamente 4 modos escalonados:

  1. Arranque vacío — sin artefacto ni configuración en el cwd → arranca un kernel básico con Console + marketplace.
  2. Arranque de proyecto — objectstack.config.ts en el cwd → compila automáticamente a ./dist/objectstack.json y arranca desde ahí.
  3. Arranque de artefacto — dist/objectstack.json accesible → arranca desde él directamente.
  4. Sobrescrituras explícitas — --artifact, --database, --port tienen prioridad.
os start                                # default port 3000
os start --port 8080
os start --artifact ./build/myapp.json
os start --artifact https://cdn.example.com/app.json
os start --database file:./data/prod.db
os start --database postgres://user:pass@host:5432/mydb
os start --database libsql://my-db.turso.io --database-auth-token $TURSO
os start --auth-secret "$(openssl rand -hex 32)"
os start --home /var/lib/objectos      # persistent home dir
os start --no-ui                       # API only (no Console/Account)

Directorio HOME por defecto:

  • con una configuración de proyecto en el cwd → <cwd>/.objectstack (local al proyecto)
  • sin ella → ~/.objectstack (global, compartido entre invocaciones)

os serve — servidor de producción

Lee objectstack.config.ts si está presente; de lo contrario recurre a dist/objectstack.json (o OS_ARTIFACT_PATH, incluyendo URLs http(s)://). Usa esto en contenedores de producción cuando quieras un comportamiento estricto.

os serve                       # port 3000
os serve --port 4000 --no-ui

os dev — desarrollo con recarga en caliente

Observa objectstack.config.ts y src/. Recompila + recarga al guardar. Se usa como el script npm dev en los proyectos generados.

os dev                         # port 3002 by default
os dev -p 4002

os studio — Console con servidor de desarrollo

Igual que os dev pero con Console habilitada explícitamente.

Comandos de proyecto

os init — genera un nuevo proyecto

os init my-app                       # interactive
os init my-app -t app --install      # auto-install with default pnpm
os init my-app -t app --install -p npm
os init my-app -t plugin             # plugin scaffold
os init my-app -t empty              # bare minimum

Plantillas:

Plantilla Qué te ofrece
app App completa — objetos, vistas, acciones, lista para ampliar
plugin Andamiaje de plugin para distribuir capacidades reutilizables
empty Solo manifiesto + tsconfig

os create — crea un paquete, plugin o ejemplo desde una plantilla

os create plugin my-plugin
os create example my-example

Comandos de compilación / validación

Comando Propósito
os compile (os build) Compila objectstack.config.ts → dist/objectstack.json
os validate Valida la configuración contra el esquema del protocolo
os lint Comprobaciones de estilo y convenciones (recomendado en CI)
os diff <old> <new> Compara dos configuraciones, detecta cambios incompatibles
os info Imprime un resumen de metadatos de una configuración o artefacto
os explain <object> Explicación legible del esquema de un objeto
os doctor Chequeo de salud: detecta dependencias circulares, referencias rotas, problemas de entorno
os generate (os g) Genera tipos de TypeScript / archivos de metadatos

os doctor es lo primero que debes ejecutar cuando algo parece ir mal — detecta configuraciones erróneas que el runtime solo mostraría como una advertencia en tiempo de ejecución.

Comandos de datos

Operan sobre registros desde la terminal — útiles para sembrar datos, migraciones y pruebas de humo en CI.

os data create <object> --data '{"subject": "Hello"}'
os data get <object> <id>
os data query <object> --filter 'status:active' --limit 10
os data update <object> <id> --data '{"done": true}'
os data delete <object> <id>

Comandos de metadatos

Lee/escribe registros de metadatos (objetos, vistas, conjuntos de permisos, …) en tiempo de ejecución.

os meta list <kind>
os meta get <kind> <id>
os meta register <file>
os meta delete <kind> <id>

Comandos de i18n

os i18n extract               # extract translation keys from source
os i18n check                 # find missing keys across configured locales

Comandos de la nube

Para usuarios de ObjectStack Cloud (el plano de control alojado opcional).

os login                      # interactive
os logout
os whoami
os register                   # create an account
os cloud login | logout | whoami

Comandos de publicación / empaquetado

os package publish            # publish artifact as a versioned package

Comandos de entorno

Para despliegues que usan múltiples entornos por proyecto (dev, staging, prod) respaldados por un plano de control.

os environments list
os environments show <id>
os environments create <name>
os environments switch <id>
os environments bind          # bind local artifact to an environment

Comando de prueba

os test                       # run Quality Protocol scenarios against a running server

Convenciones comunes de flags

Flag Significado
-p, --port Puerto HTTP
-a, --artifact Ruta o URL al artefacto compilado
-d, --database URL de la base de datos
--home Directorio de estado persistente
-v, --verbose Salida detallada
--no-ui Deshabilita los portales Console / Account

Ejecuta cualquier comando con --help para ver la lista completa de flags:

os start --help
os data query --help

Dónde encaja la CLI

  • Operador / primer arranque → os start
  • Desarrollador que construye una app → os init → os dev → os compile
  • Pipeline de CI / release → os lint && os validate && os compile && os test
  • Runtime de producción → os serve (normalmente dentro del CMD de la imagen Docker)
  • Diagnóstico → os doctor, os info, os explain