CLI Reference

The @objectstack/cli package installs a single binary, os (also available as objectstack). All examples below use the shorter os.

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

Server commands

os start — zero-config boot

Auto-detects 4 escalating modes:

1. Empty boot — no artifact, no config in cwd → boots a bare kernel with the UI + marketplace.
2. Project boot — objectstack.config.ts in cwd → auto-compiles to ./dist/objectstack.json and boots from it.
3. Artifact boot — dist/objectstack.json reachable → boots from it directly.
4. Explicit overrides — --artifact, --database, --port win.

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 UI/Account portals)

HOME directory default:

• with a project config in cwd → <cwd>/.objectstack (project-local)
• without → ~/.objectstack (global, shared across invocations)

os serve — production server

Reads objectstack.config.ts if present, otherwise falls back to dist/objectstack.json. Use this in production containers when you want strict behavior.

To boot a published artifact instead, name it with OS_ARTIFACT_URL — an absolute https://, http:// or file:// URL, with an optional #sha256= integrity pin in the fragment. It is resolved before any configuration is read. The older OS_ARTIFACT_PATH spelling is retired: on the ObjectOS runtime image a non-default value refuses the boot and names the replacement. See Environment Variables.

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

os dev — development with hot-reload

Watches objectstack.config.ts and src/. Recompiles + reloads on save. Used as the npm dev script in scaffolded projects.

os dev                         # port 3000 by default
os dev -p 4000

Note os dev asks for the same port os start uses (3000). If that port is taken it binds the next free one and says so: ↪ server bound to port 3001 (requested 3000).

Project commands

os init — scaffold a new project

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

Templates:

os create — scaffold a kernel code plugin

os create plugin my-plugin

os create plugin writes a TypeScript package implementing the kernel's Plugin contract, which os init does not. os create example was retired in ObjectStack 17.4: it wrote a subset of what os init writes, and it now exits with an error that names os init.

Build / validate commands

os doctor is the first thing to run when something feels off — it catches misconfigurations the runtime would only surface as a runtime warning.

Since ObjectStack 13, os compile also gates the build on security posture: validateSecurityPosture errors (unset/aliased sharing models, high-privilege anchor bindings, leftover role vocabulary, unqualified field-permission keys, …) fail the build, and os lint reports them earlier in the loop. If you commit an access-matrix.json snapshot, any permission-capability drift fails os compile until re-snapshotted with --update-access-matrix — every capability change becomes reviewable.

Data commands

Operate on records from the terminal — useful for seeding, migrations, and 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>

Metadata commands

Read/write metadata records (objects, views, permission sets, …) at runtime.

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

Database migrations — os migrate

os migrate brings a deployment's database in line with its metadata, and runs the one-off data migrations a release asks for. Every subcommand works on the database --database-url names, which defaults to $OS_DATABASE_URL and then to the project's own database — so name the deployment's database explicitly. Each one boots the app to read its metadata. Back the database up first. Which commands a given upgrade needs is on Upgrade and Rollback.

Schema

os migrate plan                                    # what would change; writes nothing
os migrate apply --allow-destructive --yes         # also drop and tighten (CI / scripts)
os migrate unmapped-columns --object contact --json > contact-unmapped.json

Data migrations

Each of these rewrites rows rather than schema, and is a fact about your database, not about the version you installed: the runtime does not run them for you. Unless its row says otherwise, each is a dry run until you pass --apply.

os migrate account-issuer                          # read-only pre-flight
os migrate audit-metadata-bodies                   # dry run: what it would rewrite
os migrate audit-metadata-bodies --apply           # rewrite

Secrets and stored files

i18n commands

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

Cloud commands

For users of ObjectOS Cloud (the optional hosted control plane).

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

Publish / package commands

os package publish            # publish artifact as a versioned package
os package install <id|file>  # install into a RUNNING runtime: catalog id
                              # (com.acme.crm) or a compiled artifact JSON
                              # (air-gapped, inline). --runtime / --email /
                              # --password identify the runtime to install into

Environment commands

For deployments using multiple environments per project (dev, staging, prod) backed by a control plane.

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 command

os test                       # run Quality Protocol scenarios against a running server

Common flag conventions

Run any command with --help for the full flag list:

os start --help
os data query --help

Where the CLI fits

• Operator / first run → os start
• Developer building an app → os init → os dev → os compile
• CI / release pipeline → os lint && os validate && os compile && os test
• Production runtime → os serve (typically inside the Docker image's CMD)
• Upgrading a deployment → the os migrate steps the upgrade page lists for your versions
• Diagnostics → os doctor, os info, os explain