CLI 参考

@objectstack/cli 包安装单个二进制文件 os（也可作为 objectstack）。下面所有示例使用更短的 os。

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

Server 命令

`os start` —— 零配置启动

自动检测 4 种递进模式：

空启动 —— 当前目录无 artifact、无 config → 启动一个带 Console + marketplace 的裸内核。
项目启动 —— 当前目录有 objectstack.config.ts → 自动编译到 ./dist/objectstack.json 并从中启动。
Artifact 启动 —— 可访问 dist/objectstack.json → 直接从中启动。
显式覆盖 —— --artifact、--database、--port 优先。

os start                                # 默认端口 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      # 持久化 home 目录
os start --no-ui                       # 仅 API（无 Console/Account）

HOME 目录默认值：

当前目录有项目 config → <cwd>/.objectstack（项目本地）
无 → ~/.objectstack（全局,跨调用共享）

`os serve` —— 生产服务器

如果存在则读取 objectstack.config.ts,否则回退到 dist/objectstack.json（或 OS_ARTIFACT_PATH,包括 http(s):// URL）。在希望严格行为的生产容器中使用此命令。

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

`os dev` —— 带热重载的开发模式

监听 objectstack.config.ts 和 src/。保存时重新编译并重载。脚手架项目中作为 npm dev 脚本使用。

os dev                         # 默认端口 3002
os dev -p 4002

`os studio` —— 带开发服务器的 Console

与 os dev 相同,但显式启用 Console。

项目命令

`os init` —— 脚手架新项目

os init my-app                       # 交互式
os init my-app -t app --install      # 默认 pnpm 自动安装
os init my-app -t app --install -p npm
os init my-app -t plugin             # 插件脚手架
os init my-app -t empty              # 最小骨架

模板：

模板	提供内容
`app`	完整应用 —— 对象、视图、Action,可扩展
`plugin`	用于分发可复用能力的插件脚手架
`empty`	仅 manifest + tsconfig

`os create` —— 从模板创建包、插件或示例

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

构建/校验命令

命令	用途
`os compile` (`os build`)	编译 `objectstack.config.ts` → `dist/objectstack.json`
`os validate`	根据协议 schema 校验 config
`os lint`	风格和约定检查（推荐在 CI 中使用）
`os diff <old> <new>`	比较两个 config,检测破坏性变更
`os info`	打印 config 或 artifact 的元数据摘要
`os explain <object>`	对象 schema 的可读说明
`os doctor`	健康检查：检测循环依赖、断裂引用、环境问题
`os generate` (`os g`)	生成 TypeScript 类型/元数据文件

os doctor 是感觉不对劲时首先要运行的命令 —— 它能捕获运行时只会以警告呈现的配置错误。

数据命令

从终端操作记录 —— 用于种子数据、迁移和 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>

元数据命令

在运行时读写元数据记录（对象、视图、权限集……）。

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

i18n 命令

os i18n extract               # 从源码提取翻译键
os i18n check                 # 查找已配置 locale 间缺失的键

Cloud 命令

供 ObjectStack Cloud（可选托管控制平面）用户使用。

os login                      # 交互式
os logout
os whoami
os register                   # 创建账户
os cloud login | logout | whoami

发布/打包命令

os package publish            # 将 artifact 作为版本化包发布
os publish                    # 发布到 ObjectStack Cloud
os rollback <revision>        # 激活之前的 artifact 版本

环境命令

适用于每个项目使用多环境（dev、staging、prod）并由控制平面支持的部署。

os environments list
os environments show <id>
os environments create <name>
os environments switch <id>
os environments bind          # 将本地 artifact 绑定到一个环境

测试命令

os test                       # 针对运行中的服务器执行 Quality Protocol 场景

常用 flag 约定

Flag	含义
`-p, --port`	HTTP 端口
`-a, --artifact`	已编译 artifact 的路径或 URL
`-d, --database`	数据库 URL
`--home`	持久化状态目录
`-v, --verbose`	详细输出
`--no-ui`	禁用 Console / Account 门户

任意命令带 --help 查看完整 flag 列表：

os start --help
os data query --help

CLI 的角色定位

运维/首次运行 → os start
构建应用的开发者 → os init → os dev → os compile
CI/发布管道 → os lint && os validate && os compile && os test
生产运行时 → os serve（通常位于 Docker 镜像的 CMD 内）
诊断 → os doctor、os info、os explain

CLI 参考

On this page