Référence de la CLI

Le paquet @objectstack/cli installe un binaire unique, os (également disponible sous le nom objectstack). Tous les exemples ci-dessous utilisent la forme plus courte os.

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

Commandes du serveur

os start — démarrage sans configuration

Détecte automatiquement 4 modes croissants :

1. Démarrage vide — aucun artefact, aucune configuration dans le répertoire courant → démarre un kernel minimal avec Console + marketplace.
2. Démarrage de projet — objectstack.config.ts dans le répertoire courant → compile automatiquement vers ./dist/objectstack.json et démarre à partir de celui-ci.
3. Démarrage d'artefact — dist/objectstack.json accessible → démarre directement à partir de celui-ci.
4. Surcharges explicites — --artifact, --database, --port l'emportent.

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)

Répertoire HOME par défaut :

• avec une configuration de projet dans le répertoire courant → <cwd>/.objectstack (local au projet)
• sans → ~/.objectstack (global, partagé entre les invocations)

os serve — serveur de production

Lit objectstack.config.ts s'il est présent, sinon se rabat sur dist/objectstack.json (ou OS_ARTIFACT_PATH, y compris les URL http(s)://). Utilisez cette commande dans les conteneurs de production lorsque vous voulez un comportement strict.

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

os dev — développement avec rechargement à chaud

Surveille objectstack.config.ts et src/. Recompile + recharge à chaque enregistrement. Utilisé comme script npm dev dans les projets générés.

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

os studio — Console avec serveur de développement

Identique à os dev mais avec la Console explicitement activée.

Commandes de projet

os init — générer un nouveau projet

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

Modèles :

os create — créer un package, un plugin ou un exemple à partir d'un modèle

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

Commandes de build / validation

os doctor est la première chose à exécuter lorsque quelque chose semble anormal — elle détecte les mauvaises configurations que le runtime ne ferait remonter que sous forme d'avertissement à l'exécution.

Commandes de données

Opèrent sur les enregistrements depuis le terminal — utiles pour l'initialisation, les migrations et les tests de fumée 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>

Commandes de métadonnées

Lecture/écriture des enregistrements de métadonnées (objets, vues, ensembles de permissions, …) à l'exécution.

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

Commandes i18n

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

Commandes Cloud

Pour les utilisateurs d'ObjectStack Cloud (le plan de contrôle hébergé optionnel).

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

Commandes de publication / packaging

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

Commandes d'environnement

Pour les déploiements utilisant plusieurs environnements par projet (dev, staging, prod) adossés à un plan de contrôle.

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

Commande de test

os test                       # run Quality Protocol scenarios against a running server

Conventions courantes des options

Exécutez n'importe quelle commande avec --help pour la liste complète des options :

os start --help
os data query --help

Où la CLI s'inscrit

• Opérateur / premier lancement → os start
• Développeur construisant une application → os init → os dev → os compile
• Pipeline CI / de release → os lint && os validate && os compile && os test
• Runtime de production → os serve (généralement à l'intérieur du CMD de l'image Docker)
• Diagnostics → os doctor, os info, os explain