BuildX CLI

A command-line interface tool for BuildX API with authentication, project management, and schema synchronization capabilities.

Features

• 🔐 Authentication Management: Secure login/logout with token validation
• 📁 Project Management: List, set default, and manage multiple projects
• 🔄 Schema Synchronization: Pull and push collections/types as code
• ⚡ Function Synchronization: Pull and push function source files as code
• ⚙️ Configuration Management: Store settings or use environment variables
• 🎯 Interactive CLI: User-friendly command-line interface with prompts

Installation

Using npx (Recommended)

npx buildx-cli --help

Global Installation

npm install -g buildx-cli

Local Development

git clone <repository-url>
cd buildx-cli
yarn install
yarn build
yarn start --help

Quick Start

1. Configure API settings:

   npx buildx-cli config:setup

2. Authenticate:

   npx buildx-cli auth:login

3. List projects:

   npx buildx-cli projects:list

4. Pull schema:

   npx buildx-cli schema:pull --project-id <project-id>

5. Pull function code:

   npx buildx-cli function:pull --project-id <project-id>

Configuration

Method 1: Interactive Setup

npx buildx-cli config:setup

Method 2: Environment Variables

Set these environment variables or add them to a .env file:

BUILDX_API_ENDPOINT=https://api.example.com
BUILDX_API_KEY=your-api-key
BUILDX_PROJECT_ID=your-default-project-id

Supported aliases (auto-resolved):

NEXT_PUBLIC_API_ENDPOINT=
NEXT_PUBLIC_API_KEY=
NEXT_PUBLIC_BUILDX_PROJECT_ID=

NEXT_PUBLIC_BUILDX_API_ENDPOINT=
NEXT_PUBLIC_BUILDX_API_KEY=

BUILDX_API_ENDPOINT=
BUILDX_API_KEY=
BUILDX_PROJECT_ID=

Resolution priority is strict-first:

• Endpoint: BUILDX_API_ENDPOINT -> NEXT_PUBLIC_BUILDX_API_ENDPOINT -> NEXT_PUBLIC_API_ENDPOINT
• API key: BUILDX_API_KEY -> NEXT_PUBLIC_BUILDX_API_KEY -> NEXT_PUBLIC_API_KEY
• Project ID: BUILDX_PROJECT_ID -> NEXT_PUBLIC_BUILDX_PROJECT_ID

When running config:setup, CLI auto-detects these values and asks for confirmation before using them.

Method 3: Command Line Options

npx buildx-cli config:setup --endpoint https://api.example.com --api-key your-api-key

View Current Configuration

npx buildx-cli config:show

Clear Configuration

npx buildx-cli config:clear

Commands

Authentication

auth:login

Logs in with token or username/password interactively.

npx buildx-cli auth:login

Browser-session login (uses your existing Studio login):

npx buildx-cli auth:login --browser

The CLI will show a verification code. Open the verification page in any browser/device, sign in, and enter that code.

Token login (useful when authenticating from another machine):

npx buildx-cli auth:login --token <your-token>

auth:logout

Clears stored authentication.

npx buildx-cli auth:logout

auth:status

Shows current auth state and user details (if available).

npx buildx-cli auth:status

Projects

projects:list

Lists available projects for the authenticated account.

npx buildx-cli projects:list

projects:set-default <project-id>

Sets default project used by commands when --project-id is not provided.

npx buildx-cli projects:set-default hello-world

projects:current

Shows currently selected default project.

npx buildx-cli projects:current

Users

user:list

Lists users in project scope.

npx buildx-cli user:list --project-id hello-world

user:create

Creates a user in project scope.

npx buildx-cli user:create --project-id hello-world --username demo --password secret --name "Demo User" --email [email protected]

Data Commands

data:list <collection-id>

List documents from a collection.

npx buildx-cli data:list employees --project-id hello-world --limit 20 --sort '{"createdAt":-1}'

data:get <collection-id> <document-id>

Get one document by ID.

npx buildx-cli data:get employees 65fabc... --project-id hello-world

data:create <collection-id>

Create one document from JSON.

npx buildx-cli data:create employees --project-id hello-world --data '{"name":"Alice","email":"[email protected]"}'

data:update <collection-id> <document-id>

Update one document from JSON.

npx buildx-cli data:update employees 65fabc... --project-id hello-world --data '{"name":"Alice Updated"}'

data:delete <collection-id> <document-id>

Delete one document.

npx buildx-cli data:delete employees 65fabc... --project-id hello-world

data:export <collection-id>

Export collection data to JSON file.

npx buildx-cli data:export employees --project-id hello-world --output ./employees.json --filter '{"status":"active"}'

data:import <collection-id>

Import JSON array into a collection.

npx buildx-cli data:import employees --project-id hello-world --input ./employees.json
npx buildx-cli data:import employees --project-id hello-world --input ./employees.json --mode upsert
npx buildx-cli data:import employees --project-id hello-world --input ./employees.json --mode upsert --upsert-key email
npx buildx-cli data:import employees --project-id hello-world --input ./employees.json --mode upsert --upsert-key tenant_id,employee_code

Schema Commands

schema:pull

Pulls schema artifacts from remote and writes local files.

Writes:

• types.ts
• collections.json (unless --skip-collections-code)
• collections.manifest.json
• SCHEMA_AS_CODE.md (generated usage guide for human/AI collaborators)

System-managed fields:

• when timestamps: true, pulled types.ts includes createdAt/updatedAt (BxDateTime)
• when auditable: true, pulled types.ts includes createdBy/updatedBy (BxAuth)
• these fields are excluded from collections sync payloads (won't be pushed back)

Key options:

• -p, --project-id <id>: project to sync from
• -t, --target-dir <path>: base output directory (recommended)
• -o, --output <path>: custom types path (when no --target-dir)
• --collections-file <path>: custom collections JSON path (when no --target-dir)
• --filter <pattern...>: include only matching collection IDs
• --include-buildx: include buildx_* collections
• --skip-collections-code: skip collections JSON/manifest output
• --no-annotate-types: disable @bx.* annotations injection into pulled types.ts
• --dry-run: print full file content previews without writing files
• -f, --force: overwrite even if local file drift is detected

npx buildx-cli schema:pull --project-id hello-world --target-dir ./.sandbox/buildx-cli
npx buildx-cli schema:pull --project-id hello-world --dry-run

schema:sync is still available as a compatibility alias (deprecated).

schema:push

Pushes local collections.json back to remote project.

Reads:

• collections.json
• collections.manifest.json (for drift checks)

Behavior:

• validates minimum shape (collection_id, form_schema)
• compares local checksum vs remote checksum
• skips remote-drift conflicts unless --force
• excludes system-managed fields (createdAt, updatedAt, createdBy, updatedBy) from push

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --collections-file <path> (when no --target-dir)
• --filter <pattern...>
• --dry-run
• -f, --force

npx buildx-cli schema:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run

schema:types:convert

Converts a local types.ts file into collections JSON first, so you can review before push.

Reads:

• types.ts (or --types-file)
• optional base collections.json to preserve metadata (used when present)

Writes:

• collections.json (or --collections-file)

Key options:

• -t, --target-dir <path>
• --types-file <path>
• --collections-file <path>
• --base-collections-file <path>
• --no-allow-lossy (strict mode: require base metadata file)
• --filter <pattern...>
• --dry-run

Field annotations (JSDoc in types.ts) are supported:

• @bx.title <text>
• @bx.description <text>
• @bx.required or @bx.required false
• @bx.ref <collection_id_or_enum_key>
• @bx.choices value1:Label 1|value2:Label 2 (for Choices/MultipleChoices)

System-managed fields:

• createdAt, updatedAt, createdBy, updatedBy in types.ts are ignored by convert output and never synced back

Example:

export type Employees = {
  /** @bx.title Employment status @bx.choices active:Active|on_leave:On Leave */
  status?: BxChoices;
  /** @bx.required */
  employee_id?: BxText;
  /** @bx.ref departments @bx.title Department */
  department?: Partial<Departments> | BxDataObject;
};

npx buildx-cli schema:types:convert --target-dir ./.sandbox/buildx-cli --dry-run
npx buildx-cli schema:types:convert --target-dir ./.sandbox/buildx-cli
npx buildx-cli schema:push --collections-file ./.sandbox/buildx-cli/collections.json --project-id hello-world --dry-run

schema:list

Lists remote collections.

Key options:

• -p, --project-id <id>
• --filter <pattern...>
• --include-buildx

npx buildx-cli schema:list --project-id hello-world --filter "user*"

schema:diff

Diffs local collections against remote by collection_id.

Reads:

• local collections.json

Output markers:

• = same
• ~ changed
• + local-only
• - remote-only

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --collections-file <path> (when no --target-dir)
• --filter <pattern...>
• --include-buildx

npx buildx-cli schema:diff --project-id hello-world --target-dir ./.sandbox/buildx-cli

Function Commands

function:pull

Pulls function context schema and function source code from remote.

Writes:

• function-context.d.ts
• functions/*.ts
• functions/functions.manifest.json
• FUNCTION_AS_CODE.md (generated usage guide for human/AI collaborators)

Behavior:

• writes a compact function-context.d.ts by default (use --full-context to keep full remote schema)
• preserves remote function code as-is by default (safe with existing runtime)
• optional --module-wrap can normalize arrow-function code into module format (export default) for local tooling
• skips overwriting local edited files unless --force
• supports dry-run file content previews

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --context-output <path> (when no --target-dir)
• --functions-dir <path> (when no --target-dir)
• --filter <pattern...>
• --full-context
• --module-wrap
• --no-validate-code
• --no-lint
• --dry-run
• -f, --force

npx buildx-cli function:pull --project-id hello-world --target-dir ./.sandbox/buildx-cli
npx buildx-cli function:pull --project-id hello-world --dry-run

function:sync is still available as a compatibility alias (deprecated).

function:push

Pushes local function source files back to remote.

Reads:

• functions/*.ts
• functions/functions.manifest.json

Behavior:

• checks remote drift against manifest baseline
• validates local function code compatibility before push (can bypass via --no-validate-code)
• runs basic syntax lint before push (can bypass via --no-lint)
• skips conflicts unless --force

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --functions-dir <path> (when no --target-dir)
• -n, --name <function-name> for a single function
• --filter <pattern...>
• --no-validate-code
• --no-lint
• --dry-run
• -f, --force

npx buildx-cli function:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run

function:list

Lists remote function names.

Key options:

• -p, --project-id <id>
• --filter <pattern...>

npx buildx-cli function:list --project-id hello-world --filter "send*"

function:diff

Diffs local function sources against remote.

Reads:

• local functions/*.ts
• functions/functions.manifest.json

Output markers:

• = same
• ~ changed
• + local-missing
• - remote-missing
• ! remote-drift

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --functions-dir <path> (when no --target-dir)
• -n, --name <function-name>
• --filter <pattern...>

npx buildx-cli function:diff --project-id hello-world --target-dir ./.sandbox/buildx-cli

Configuration Commands

config:setup

Interactive API configuration (endpoint, api key).

npx buildx-cli config:setup

config:show

Displays current resolved configuration (use this to inspect configured API endpoint).

npx buildx-cli config:show

config:clear

Clears all saved CLI configuration.

npx buildx-cli config:clear

Configuration Sources

The CLI checks for configuration in this order:

1. Stored Configuration (via config:setup)
2. Environment Variables (BUILDX_API_ENDPOINT, BUILDX_API_KEY)
3. .env File (in current directory)

Configuration File Location

• Global config: ~/.config/buildx-cli-nodejs/config.json

Environment Variables

• BUILDX_API_ENDPOINT - Your API endpoint URL
• BUILDX_API_KEY - Your API key
• BUILDX_PROJECT_ID - Default project ID (optional)
• NEXT_PUBLIC_BUILDX_API_ENDPOINT - Alias for API endpoint
• NEXT_PUBLIC_API_ENDPOINT - Alias for API endpoint
• NEXT_PUBLIC_BUILDX_API_KEY - Alias for API key
• NEXT_PUBLIC_API_KEY - Alias for API key
• NEXT_PUBLIC_BUILDX_PROJECT_ID - Alias for default project ID

API Endpoints

The CLI interacts with the following API endpoints:

• POST /auth/login - User authentication
• GET /auth/me - Get current user info
• GET /projects - List user projects
• GET /project/:project_id/collections/schema - Fetch project schema types
• GET /project/:project_id/collections - Fetch collections as code
• POST /project/:project_id/collections - Upsert collection
• GET /project/:project_id/functions/context/schema/info - Fetch function context schema info
• GET /project/:project_id/functions - List functions
• GET /project/:project_id/functions/:function_name - Fetch function source
• POST /project/:project_id/functions/:function_name - Upsert function source

Development

Project Structure

src/
├── commands/          # CLI commands
│   ├── auth/         # Authentication commands
│   ├── config/       # Configuration commands
│   ├── projects/     # Project management commands
│   └── sync.ts       # Schema synchronization
├── services/          # Business logic services
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
├── config/           # Configuration management
└── index.ts          # Main entry point

Available Scripts

yarn build          # Build the project
yarn dev            # Run in development mode
yarn start          # Run built version
yarn test           # Run tests
yarn lint           # Run linter
yarn format         # Format code

Building

yarn build

Development Mode

yarn dev

Examples

CI/CD Pipeline

# Set environment variables
export BUILDX_API_ENDPOINT=https://api.example.com
export BUILDX_API_KEY=$CI_API_KEY
export BUILDX_PROJECT_ID=$CI_PROJECT_ID

# Run schema pull
npx buildx-cli schema:pull --project-id $BUILDX_PROJECT_ID --output ./src/types/api.ts

Local Development

# Setup once
npx buildx-cli config:setup

# Use regularly
npx buildx-cli projects:list
npx buildx-cli schema:pull --project-id my-project
npx buildx-cli function:pull --project-id my-project

Monorepo Local Shortcuts (No Publish)

From monorepo root:

yarn cli:build
yarn cli --help

Isolated test output:

yarn cli -- schema:pull --project-id my-project --target-dir ./.sandbox/buildx-cli
yarn cli -- function:pull --project-id my-project --target-dir ./.sandbox/buildx-cli

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE file for details.