CLI-Referenz

Das Paket @objectstack/cli installiert eine einzelne Binärdatei, os (auch verfügbar als objectstack). Alle Beispiele unten verwenden das kürzere os.

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

Server-Befehle

`os start` — Boot ohne Konfiguration

Erkennt automatisch 4 eskalierende Modi:

Leerer Boot — kein Artefakt, keine Konfiguration im cwd → bootet einen minimalen Kernel mit Console + marketplace.
Projekt-Boot — objectstack.config.ts im cwd → kompiliert automatisch zu ./dist/objectstack.json und bootet daraus.
Artefakt-Boot — dist/objectstack.json erreichbar → bootet direkt daraus.
Explizite Überschreibungen — --artifact, --database, --port gewinnen.

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)

Standardwert des HOME-Verzeichnisses:

mit einer Projektkonfiguration im cwd → <cwd>/.objectstack (projektlokal)
ohne → ~/.objectstack (global, über Aufrufe hinweg gemeinsam genutzt)

`os serve` — Produktionsserver

Liest objectstack.config.ts, falls vorhanden, andernfalls greift es auf dist/objectstack.json zurück (oder OS_ARTIFACT_PATH, einschließlich http(s)://-URLs). Verwenden Sie dies in Produktionscontainern, wenn Sie striktes Verhalten wünschen.

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

`os dev` — Entwicklung mit Hot-Reload

Überwacht objectstack.config.ts und src/. Rekompiliert + lädt beim Speichern neu. Wird in gerüsteten Projekten als npm-dev-Skript verwendet.

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

`os studio` — Console mit Dev-Server

Wie os dev, aber mit explizit aktivierter Console.

Projekt-Befehle

`os init` — ein neues Projekt aufsetzen

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

Vorlagen:

Vorlage	Was sie Ihnen bietet
`app`	Vollständige App — Objekte, Views, Aktionen, bereit zum Erweitern
`plugin`	Plugin-Gerüst zum Verteilen wiederverwendbarer Funktionen
`empty`	Nur Manifest + tsconfig

`os create` — ein Paket, Plugin oder Beispiel aus einer Vorlage erstellen

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

Build- / Validierungs-Befehle

Befehl	Zweck
`os compile` (`os build`)	`objectstack.config.ts` → `dist/objectstack.json` kompilieren
`os validate`	Konfiguration gegen das Protokollschema validieren
`os lint`	Stil- und Konventionsprüfungen (empfohlen in CI)
`os diff <old> <new>`	Zwei Konfigurationen vergleichen, Breaking Changes erkennen
`os info`	Metadaten-Zusammenfassung einer Konfiguration oder eines Artefakts ausgeben
`os explain <object>`	Menschenlesbare Erklärung eines Objektschemas
`os doctor`	Health-Check: erkennt zirkuläre Abhängigkeiten, defekte Referenzen, Umgebungsprobleme
`os generate` (`os g`)	TypeScript-Typen / Metadatendateien generieren

os doctor ist das Erste, das man ausführen sollte, wenn etwas nicht stimmt — es fängt Fehlkonfigurationen ab, die die Laufzeit nur als Laufzeitwarnung melden würde.

Daten-Befehle

Arbeiten Sie mit Datensätzen vom Terminal aus — nützlich für Seeding, Migrationen und CI-Smoke-Tests.

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>

Metadaten-Befehle

Metadaten-Datensätze (Objekte, Views, Berechtigungssätze, …) zur Laufzeit lesen/schreiben.

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

i18n-Befehle

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

Cloud-Befehle

Für Benutzer von ObjectStack Cloud (der optionalen gehosteten Control-Plane).

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

Publish- / Package-Befehle

os package publish            # publish artifact as a versioned package
os publish                    # publish to ObjectStack Cloud
os rollback <revision>        # activate a previous artifact revision

Umgebungs-Befehle

Für Deployments mit mehreren Umgebungen pro Projekt (dev, staging, prod), die von einer Control-Plane unterstützt werden.

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

Test-Befehl

os test                       # run Quality Protocol scenarios against a running server

Gängige Flag-Konventionen

Flag	Bedeutung
`-p, --port`	HTTP-Port
`-a, --artifact`	Pfad oder URL zum kompilierten Artefakt
`-d, --database`	Datenbank-URL
`--home`	Verzeichnis für persistenten Zustand
`-v, --verbose`	Ausführliche Ausgabe
`--no-ui`	Console-/Account-Portale deaktivieren

Führen Sie einen beliebigen Befehl mit --help aus, um die vollständige Flag-Liste zu erhalten:

os start --help
os data query --help

Wo die CLI hineinpasst

Operator / erster Start → os start
Entwickler, der eine App baut → os init → os dev → os compile
CI / Release-Pipeline → os lint && os validate && os compile && os test
Produktions-Laufzeit → os serve (typischerweise im CMD des Docker-Images)
Diagnose → os doctor, os info, os explain

CLI-Referenz

On this page