Your first CLI command

Overview

The obx CLI is the command-center for everything Oblax. Its grammar is deterministic, predictable, and designed for automation. Every command follows the fixed structure: obx <domain> <module[:submodule...]> <action> [target] [flags].

The CLI supports interactive and non-interactive modes, with strict separation for scriptable workflows. Output formats are consistent across all actions, designed for human readability in terminal sessions.

Installation

The CLI must be installed and authenticated before use.

Verify Installation

obx version

Expected output:

obx version 0.1.0

Authenticate

obx login

Configuration

CLI Grammar — The Fixed Structure

Every obx command follows this exact pattern:

obx <domain> <module[:submodule...]> <action> [target] [flags]

Diagram:

           +--------+       +----------+     +--------+     +------+
           | domain | →     | module   | →   | action | →   | target|
           +--------+       +----------+     +--------+     +------+
                |               |               |               |
                v               v               v               v
          obx app forms get 123

Domains

Domain	Purpose	Example
`account`	Account-level operations	`obx account create`
`project`	Project-level operations	`obx project create my-proj`
`app`	Application-domain resources	`obx app forms list`

Modules (Hierarchical, : Separated)

Module	Submodules	Description
`forms`	(none)	ID-based CRUD collections
`bookmarks`	(none)	ID-based CRUD collections
`flux:scripts`	`flux:events`	Key-based semantic singletons
`templates`	(none)	Key-based semantic singletons
`acl`	(none)	HTTP-key-based (API permissions)

Actions

Action	Alias	Meaning
`list`	`ls`	List resources
`get`	(none)	Fetch single item
`init`	(none)	Create local file template
`push`	(none)	Sync local → remote
`pull`	(none)	Sync remote → local
`del`	`delete`	Remove resource
`docs`	(none)	Open documentation

Interactive vs. Non-Interactive Mode

The Oblax CLI has a strict separation between interactive and non-interactive compatibility:

Category	Allowed	Not Allowed
`obx project create`	Interactive (TUI)	—
`obx app forms init`	Interactive	—
`obx app forms push init`	Non-interactive	TUI-only commands
`obx login`	Interactive (opens browser)	—
All other actions	Must be non-interactive compatible	Pure TUI commands

Rule: Only obx project create and obx login are allowed to present interactive UI. All other commands must work in non-interactive mode (scriptable, pipeable).

Output Rules

The CLI produces consistent output across all actions:

Action	Output Format
`list` / `ls`	Plain terminal table (no TUI)
`get`	Formatted “reverse table” — line by line output. Optionally JSON with output mode
`pull`	Writes files to disk
`push`	Success/failure messages
`delete`	Confirmation + success message

No output mode flags in v1. The default output is designed for human readability in terminal sessions.

CLI Shortcuts and Conventions

Shortcut	Equivalent	Description
`obx app forms push form.json`	`obx app forms push --data @form.json`	Shortcut: push from a local file
`obx delete <id>`	`obx del <id>`	Alias for delete
`obx list <module>`	`obx ls <module>`	Alias for list

Usage

Your First CLI Commands

1. Check CLI Version

obx version

2. Log In (Authentication)

obx login

This opens your default browser to the Oblax authentication page. After successful login:

Your JWT is stored in the CLI session
All subsequent commands carry your authentication token
You’re ready to interact with the platform

3. Create a Project (Already Done)

obx project create my-first-project

4. Initialize Your First Form

obx app forms init

Output:

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

5. Push the Form to Platform

obx app forms push init

Output:

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

6. List All Forms

obx app forms list

Output: Table displaying all forms in your project.

7. Get a Single Form by ID

obx app forms get f2837hfd17q3phc3

Output: Reverse-table format output of the form details.

8. Pull a Form from Platform

obx app forms pull f2837hfd17q3phc3

Output: Data for the record is written to ./app/forms/f2837hfd17q3phc3.json.

If a local file with that ID already exists, you’ll see:

| ERROR: Role pull failed
| A local version of the record exist. Use '--override' to overwrite it.

Use --override to force the pull:

obx app forms pull f2837hfd17q3phc3 --override

9. Update a Form

obx app forms push f2837hfd17q3phc3

Pushes updated data. The CLI detects whether the ID is present (update) or absent (create).

10. Delete a Form

obx app forms delete f2837hfd17q3phc3

Output: The record is deleted from the platform and the local file ./app/forms/f2837hfd17q3phc3.json is removed.

Safety: All destructive actions require confirmation:

| Are you sure you want to delete this record? (Y/N)

Use --allow-destructive-action to skip the confirmation:

obx app forms delete f2837hfd17q3phc3 --allow-destructive-action

CLI CRUD Workflow Patterns

Pattern 1: ID-Based Records (Forms, Bookmarks)

Step	Command	Purpose
1	`obx app forms init`	Create local template file
2	Edit the file	Add your data
3	`obx app forms push init`	Create on platform → gets ID
4	`obx app forms push <id>`	Update existing record
5	`obx app forms pull <id>`	Pull from platform
6	`obx app forms delete <id>`	Delete from platform + local

Pattern 2: Key-Based Records (Flux Scripts, Templates)

Step	Command	Purpose
1	`obx app flux:scripts init user.created`	Initialize with platform-defined key
2	`obx app flux:scripts push user.created`	Push to platform
3	`obx app flux:scripts pull user.deleted`	Pull from platform
4	`obx app flux:scripts enable/disable <key>`	Enable/disable the script

Pattern 3: HTTP-Key-Based Records (ACL)

Step	Command	Purpose
1	`obx app acl init`	Initialize ACL rules
2	`obx app acl push post@/api/v1/users`	Push with `method@route` format
3	`obx app acl pull post_api_v1_users`	Pull by normalized filename

Common CLI Troubleshooting

Issue	Resolution
`obx: command not found`	Ensure CLI is installed and in your `PATH` (`obx version` should work)
`Authentication failed`	Run `obx login` again. Your JWT may have expired.
`ERROR: Role pull failed`	Use `--override` if a local file with that ID already exists
`ERROR: Flux handler initialization failed`	Verify the key is valid for the flux:scripts module (see documentation for valid keys)
Command hangs	Check your internet connection and ensure `obx version` works first

Quick CLI Cheat Sheet

obx version
obx login
obx project create my-proj
obx app forms init
obx app forms push init
obx app forms list
obx app forms get <id>
obx app forms pull <id>
obx app forms delete <id>
obx app bookmarks init
obx app bookmarks list
obx app flux:scripts init user.created
obx app flux:scripts push user.created
obx app acl init
obx app acl push post@/api/v1/users

Next Steps

You’ve mastered the CLI. Now level up:

Your First SDK Call — JavaScript/TypeScript integration from a web or mobile front-end
Run and Deploy — production deployment, observability, and going live