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:

Arranque vacío — sin artefacto ni configuración en el cwd → arranca un kernel básico con Console + marketplace.
Arranque de proyecto — objectstack.config.ts en el cwd → compila automáticamente a ./dist/objectstack.json y arranca desde ahí.
Arranque de artefacto — dist/objectstack.json accesible → arranca desde él directamente.
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
os publish                    # publish to ObjectStack Cloud
os rollback <revision>        # activate a previous artifact revision

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

Referencia de la CLI

On this page