Create a project

Overview

A project is the fundamental container for your Oblax application. It organizes your code, configuration, and resources into a single deployable unit. Project initialization creates a directory with oblax.json configuration and the standard /app filesystem structure.

The project structure enables offline-first development, deterministic serialization, and version control readiness. All application data lives under /app, with each module mapping to specific subdirectories.

Installation

Project creation requires the Oblax CLI to be installed and authenticated.

Verify CLI Installation

obx version

Expected output:

obx version 0.1.0

Authenticate

obx login

Configuration

Project Initialization

obx project create my-first-project

What happens:

1. A new directory my-first-project/ is created
2. An oblax.json configuration file is generated inside it
3. The standard /app filesystem structure is scaffolded
4. You’re positioned inside the new project directory

Success output:

| SUCCESS: Project created
| Project 'my-first-project' has been initialized.
|
| Directory structure:
| ├── oblax.json
| └── app/
|   ├── forms/
|   ├── bookmarks/
|   ├── flux/
|   ├── templates/
|   └── acl/
|
| Next steps:
|   1. cd my-first-project
|   2. Review the generated oblax.json
|   3. Start building with `obx app forms init`

The oblax.json Configuration File

Every Oblax project must contain an oblax.json at its root. This file is the single source of truth for your project’s identity and configuration.

Minimal oblax.json:

{
  "name": "my-first-project",
  "description": "My first Oblax project",
  "version": "0.1.0"
}

Full oblax.json reference:

The /app Filesystem Model

Oblax projects use a filesystem-synced local state. All application data lives under the /app directory. This design enables:

• Offline-first development — all data is local until you push
• Deterministic serialization — files map directly to platform records
• Version control readiness — project directories git-ready out of the box

Standard /app directory structure:

/app
  /forms       → ID-based CRUD collections (objects have `id`)
  /bookmarks   → ID-based CRUD collections
  /flux        → Key-based semantic singletons (flux scripts)
  /templates   → Key-based semantic singletons
  /acl         → HTTP-key-based (API permissions)

Module identity systems:

Project Workflow Patterns

1. Initialize a Record Template

obx app forms init

This creates ./app/forms/init.json with the structure of a form record, ready for you to fill in.

Output:

| SUCCESS: Role file initialized
| Edit the initialized role file ./app/forms/init.json

2. Push to Platform

obx app forms push init

This does four things:

1. Pushes the data to the Oblax platform
2. Writes the response to a file with platform-generated ID (e.g., ./app/forms/f2837hfd17q3phc3.json)
3. Deletes the local init file
4. You now refer to the record by its ID: f2837hfd17q3phc3

Output:

| SUCCESS: Role created
| The role 'role' has been successfully created on the platform.
|
| Local copy of the record is saved in ./app/forms/f2837hfd17q3phc3.json

3. Pull from Platform

obx app forms pull d28a7hfz17q4p2c0

Pulls data for the record and creates/overwrites the local file. If a local file with that ID already exists, use --override:

obx app forms pull d28a7hfz17q4p2c0 --override

4. Delete a Record

obx app forms delete d28a7hfz17q4p2c0

Deletes the record via the API and removes the local file ./app/forms/d28a7hfz17q4p2c0.json.

Usage

Project Checklist

Next Steps

Your project is ready. Now:

1. Build your first app — scaffold your application
2. Make your first API call — authenticate and interact with your data
3. Run your first CLI command — practice the CRUD workflows