CLI 레퍼런스

@objectstack/cli 패키지는 단일 바이너리 os(별칭 objectstack로도 사용 가능)를 설치합니다. 아래의 모든 예제는 더 짧은 os를 사용합니다.

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

서버 명령어

`os start` — 설정 없는 부팅

4가지 단계적 모드를 자동으로 감지합니다:

빈 부팅(Empty boot) — cwd에 아티팩트도 설정도 없음 → Console과 marketplace가 포함된 최소한의 커널을 부팅합니다.
프로젝트 부팅(Project boot) — cwd에 objectstack.config.ts가 있음 → ./dist/objectstack.json으로 자동 컴파일한 뒤 그것으로 부팅합니다.
아티팩트 부팅(Artifact boot) — dist/objectstack.json에 접근 가능 → 그것으로 직접 부팅합니다.
명시적 재정의(Explicit overrides) — --artifact, --database, --port가 우선합니다.

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)

HOME 디렉터리 기본값:

cwd에 프로젝트 설정이 있을 때 → <cwd>/.objectstack (프로젝트 로컬)
없을 때 → ~/.objectstack (전역, 호출 간 공유)

`os serve` — 프로덕션 서버

objectstack.config.ts가 있으면 이를 읽고, 없으면 dist/objectstack.json (또는 http(s):// URL을 포함한 OS_ARTIFACT_PATH)으로 대체합니다. 엄격한 동작을 원하는 프로덕션 컨테이너에서 사용하세요.

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

`os dev` — 핫 리로드를 지원하는 개발

objectstack.config.ts와 src/를 감시합니다. 저장 시 재컴파일 및 리로드합니다. 스캐폴딩된 프로젝트에서 npm dev 스크립트로 사용됩니다.

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

`os studio` — 개발 서버가 포함된 Console

os dev와 동일하지만 Console이 명시적으로 활성화됩니다.

프로젝트 명령어

`os init` — 새 프로젝트 스캐폴딩

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

템플릿:

템플릿	제공하는 것
`app`	전체 앱 — 오브젝트, 뷰, 액션을 갖추고 확장할 준비 완료
`plugin`	재사용 가능한 기능을 배포하기 위한 플러그인 스캐폴드
`empty`	매니페스트와 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`	프로토콜 스키마에 대해 설정을 검증
`os lint`	스타일 및 규칙 검사 (CI에서 권장)
`os diff <old> <new>`	두 설정을 비교하여 호환성 깨짐(breaking changes) 감지
`os info`	설정 또는 아티팩트의 메타데이터 요약 출력
`os explain <object>`	오브젝트 스키마에 대한 사람이 읽기 쉬운 설명
`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               # extract translation keys from source
os i18n check                 # find missing keys across configured locales

클라우드 명령어

ObjectStack Cloud(선택적 호스팅 컨트롤 플레인) 사용자를 위한 명령어입니다.

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

게시 / 패키지 명령어

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

환경 명령어

컨트롤 플레인을 기반으로 프로젝트당 여러 환경(dev, staging, prod)을 사용하는 배포를 위한 명령어입니다.

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

테스트 명령어

os test                       # run Quality Protocol scenarios against a running server

공통 플래그 규칙

플래그	의미
`-p, --port`	HTTP 포트
`-a, --artifact`	컴파일된 아티팩트의 경로 또는 URL
`-d, --database`	데이터베이스 URL
`--home`	영구 상태 디렉터리
`-v, --verbose`	상세 출력
`--no-ui`	Console / Account 포털 비활성화

전체 플래그 목록을 보려면 어떤 명령어든 --help와 함께 실행하세요:

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