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>

6. Pull AI functions:

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

7. Pull templates:

   npx buildx-cli template: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

Per-command endpoint override:

• Many commands support -u, --api-url <url>.
• --api-url overrides only the current command request target.
• Saved config is not changed.
• API key and auth are still resolved from existing config/env.

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

Filter by product key (project.product.key):

npx buildx-cli projects:list --product-key approval

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

projects:metadata:get

Get project metadata (default path: metadata.product_constants), optionally export to JSON file.

npx buildx-cli projects:metadata:get --project-id hello-world
npx buildx-cli projects:metadata:get --project-id hello-world --path product_constants --output ./project-metadata.json

projects:metadata:update

Update project metadata constants + optional locale fields.

# set constants
npx buildx-cli projects:metadata:update --project-id hello-world --set API_BASE_PATH=/v1 --set FEATURE_FLAG_X=on

# import constants from JSON object
npx buildx-cli projects:metadata:update --project-id hello-world --import ./metadata.json

# replace all constants then import
npx buildx-cli projects:metadata:update --project-id hello-world --replace --import ./metadata.json

# unset keys
npx buildx-cli projects:metadata:update --project-id hello-world --unset FEATURE_FLAG_X

# update locale together
npx buildx-cli projects:metadata:update --project-id hello-world --default-language en-US --timezone Asia/Bangkok

Notes:

• Metadata key format is enforced: A-Z0-9_
• Duplicate keys in --set are rejected

projects:locale:validate

Validate locale format before saving.

npx buildx-cli projects:locale:validate --default-language en-US --timezone UTC

project:init

Initialize a new Buildx project and optional app scaffold.

Modes:

• plain: creates standalone project via POST /projects.
• product: tries POST /product/:product_key/projects, then falls back to plain when product creation is denied (for example non-root auth).

Key options:

• -i, --interactive: prompt for missing options (recommended for first-time setup)
• --project-id <id>: target project ID (required unless interactive prompt is used)
• --name <name>: project name (required unless interactive prompt is used)
• --description <text>: project description (optional)
• --product-key <key>: enable product mode first, with fallback to plain mode
• --app <none|next|expo|react>: app scaffold target (default none)
• --react-stack <vite|next|expo-web>: required when --app react
• --out-dir <path>: output workspace directory (default ./<project-id>)
• --overwrite: allow writing into non-empty output directory
• --use-existing: allow using existing project_id without creating a new backend project
• --dry-run: compute output without writing files or calling APIs
• --json: print machine-readable result

Examples:

# backend only (plain mode)
npx buildx-cli project:init --project-id hello-world --name "Hello World"

# interactive guided mode
npx buildx-cli project:init --interactive

# product mode first, fallback to plain when not allowed
npx buildx-cli project:init --project-id hello-world --name "Hello World" --product-key approval

# backend + Next.js app
npx buildx-cli project:init --project-id hello-world --name "Hello World" --app next

# backend + Expo app
npx buildx-cli project:init --project-id hello-world --name "Hello World" --app expo

# existing backend project id (reuse backend, scaffold local files)
npx buildx-cli project:init --project-id hello-world --name "Hello World" --app next --use-existing

Existing project behavior:

• CLI checks existing project IDs before create.
• If project_id already exists:
  • interactive mode asks for confirmation to continue with existing backend.
  • with --use-existing, CLI skips confirmation and continues directly.
  • with --json and no --use-existing, CLI exits with error (no interactive prompt in JSON mode).

Next.js starter behavior (--app next):

• public/private route split remains (app/(public) and app/(private)).
• root app shell includes a reusable navbar.
• includes built-in theme mode setup (light|dark|system) with toggle.
• includes built-in locale setup (en|th) with selector.
• default web UI stack is HeroUI (@heroui/react) as primary component framework.
• generated provider wiring does not import/wrap HeroUIProvider (compatibility with current HeroUI export surface).
• generated auth wiring supports dual mode:
  • buildx mode (root auth API, no project scope)
  • project mode (project-scoped auth API with project id)
  • auto mode (uses project id only when provided)
• starter card layout uses CardContent (not CardBody) for current HeroUI package compatibility.
• auth screens use shared UI pack components without forcing full-screen background, so page/layout background is controlled by the generated app.

Expo starter behavior (--app expo):

• scaffold base runs npx create-expo-app@latest (TypeScript template) first.
• dependency install step now follows detected package manager from user agent/lockfile (pnpm, yarn, bun, npm) instead of forcing npm install.
• mobile-first scaffold with HeroUI Native (heroui-native) provider and starter controls.
• starter provider defaults disable animated-style helper noise for custom-style scaffolds:
  • isAnimatedStyleActive={false}
  • config.devInfo.stylingPrinciples=false
• starter uses SafeAreaView from react-native-safe-area-context (not deprecated react-native export).
• includes required heroui-native peer dependencies: uniwind, tailwind-merge, tailwind-variants, react-native-gesture-handler, @gorhom/bottom-sheet.
• includes react-native-worklets dependency required by current react-native-reanimated chain.
• keeps auth state split (public/private view) and uses shared Buildx auth provider wiring.
• generated auth wiring supports dual mode (buildx|project|auto) with project-id forwarding on auth actions.
• includes starter auth flows on mobile:
  • sign-in (username/password)
  • sign-up (name/email/tel support)
  • EOTP request + verify
  • forgot/reset password
• private change-password form
• after Buildx dependency rewiring, CLI runs install to ensure added packages are available immediately.
• CLI also runs expo install for native compatibility packages (react-native-reanimated, react-native-safe-area-context, react-native-screens, react-native-svg, react-native-worklets, react-native-gesture-handler, @gorhom/bottom-sheet) to align with Expo SDK expectations.
• generated Expo app includes global.css setup for Uniwind + HeroUI Native styles and wraps app with GestureHandlerRootView.
• generated global.css includes fallback static theme tokens for HeroUI Native hover color variables to avoid Uniwind missing-variable warnings in minimal starter usage.

project:add-pack

Add Buildx pack dependencies into an existing project package.

Key options:

• --pack <ui-packs|sdk>: pack to install
• --version <version>: optional version override
• --dir <path>: target project directory (default current directory)
• --manager <bun|pnpm|npm|yarn>: force package manager
• --json: print machine-readable result

Examples:

# add UI packs with default version
npx buildx-cli project:add-pack --pack ui-packs

# add sdk in specific directory with pnpm
npx buildx-cli project:add-pack --pack sdk --manager pnpm --dir ./my-project

Generated auth-aware structure:

• Next.js scaffold source:
  • project:init --app next runs npx create-next-app@latest first (TypeScript + App Router)
  • then applies Buildx auth/public-private route wiring and maintenance scripts
  • then runs dependency install to ensure added Buildx/HeroUI packages are present before first dev
• Next.js template uses route groups for separation:
  • app/(public)/... (sign-in/sign-up/forgot-password)
  • app/(private)/... (protected dashboard)
  • rewrites root app/layout.tsx and starter shell to include provider wiring (auth + theme + locale)
  • starter root app/page.tsx includes generic Dashboard, Sign in, and Sign up links with usage description
• Expo template uses auth-state route split in App.tsx:
  • project:init --app expo runs npx create-expo-app@latest first
  • public screen tree for unauthenticated users
  • private screen tree for authenticated users
  • mobile-first baseline with heroui-native provider
• Generated auth mode env defaults:
  • NEXT_PUBLIC_BUILDX_AUTH_MODE / EXPO_PUBLIC_BUILDX_AUTH_MODE / VITE_BUILDX_AUTH_MODE (default: auto)
  • NEXT_PUBLIC_BUILDX_PROJECT_ID / EXPO_PUBLIC_BUILDX_PROJECT_ID / VITE_BUILDX_PROJECT_ID used as default project scope in project mode
  • in project mode, generated auth forms pass projectId explicitly to auth actions
  • in buildx mode, generated auth provider forces root scope (no project id)
• Scaffold layout is single-level:
  • app package files are generated at workspace root (no apps/web nesting)
  • buildx/ artifacts are generated at root level alongside app files

UI package dependency resolution:

• generated apps depend on package from env BUILDX_UI_PACKS_PACKAGE
• default package name is buildx-react-ui-packs
• default package version/tag is latest (override via BUILDX_UI_PACKS_VERSION)
• set a scoped package before seeding when unscoped npm name is unavailable:
  • BUILDX_UI_PACKS_PACKAGE=@your-scope/buildx-react-ui-packs npx buildx-cli project:init ...

Notes:

• Next scaffold requires npm registry connectivity for create-next-app.
• Use --dry-run to preview file plan without running scaffold commands.
• After backend bootstrap, project:init automatically runs initial pull via CLI:
  • schema:pull --target-dir <workspace>/buildx/generated
  • function:pull --target-dir <workspace>/buildx
  • ai-function:pull --target-dir <workspace>/buildx/ai-functions
  • template:pull --target-dir <workspace>/buildx/templates so starter artifact docs/structure are available immediately.
• Generated projects are package-manager agnostic (no forced packageManager lock in generated package.json).
• Next app/globals.css is normalized with Tailwind @source to include UI pack classes from node_modules (prevents missing utilities like grid-cols-2 from shared components).
• Next starter includes @heroui/react by default.
• Expo starter includes heroui-native by default.

Standard Artifact Guideline

Use this as the standard workflow for project artifacts after project:init.

Scope and location:

• schema artifacts: buildx/generated/*
• function artifacts: buildx/functions/*
• AI function artifacts: buildx/ai-functions/*
• template artifacts: buildx/templates/*

Initial sync baseline:

• project:init auto-pulls all artifact groups (schema, function, ai-function, template).

Daily standard loop (recommended):

1. Pull latest remote artifacts first.
2. Edit local files.
3. Diff against remote.
4. Push with --dry-run.
5. Push for real after review.

# 1) pull latest (all artifact groups)
npx buildx-cli schema:pull --project-id <project-id>
npx buildx-cli function:pull --project-id <project-id>
npx buildx-cli ai-function:pull --project-id <project-id>
npx buildx-cli template:pull --project-id <project-id>

# 2) diff before push
npx buildx-cli schema:diff --project-id <project-id> --details
npx buildx-cli function:diff --project-id <project-id>
npx buildx-cli ai-function:diff --project-id <project-id>
npx buildx-cli template:diff --project-id <project-id>

# 3) dry-run push
npx buildx-cli schema:push --project-id <project-id> --dry-run
npx buildx-cli function:push --project-id <project-id> --dry-run
npx buildx-cli ai-function:push --project-id <project-id> --dry-run
npx buildx-cli template:push --project-id <project-id> --dry-run

# 4) push for real
npx buildx-cli schema:push --project-id <project-id>
npx buildx-cli function:push --project-id <project-id>
npx buildx-cli ai-function:push --project-id <project-id>
npx buildx-cli template:push --project-id <project-id>

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)

Source-of-truth behavior:

• collections.json is pulled from remote /project/:project_id/collections payload directly (with only lightweight normalization for internal keys).
• CLI does not reconstruct collections.json from types.ts during schema:pull.
• runtime cache payload under form_schema.*.propertiesScheme.schema is excluded from pull/push sync artifacts.
• embedded Object/List/Row array children are sanitized during pull normalization (invalid child entries without a stable name are removed from exported collections.json).
• collection-level configurations is preserved for push/pull sync (including configurations.soft_delete.* values).

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)
• validates nested embedded field schema recursively:
  • Object/List/Row require propertiesScheme.children
  • array children must be object items with non-empty name
  • nested children are validated transitively
• compares local checksum vs remote checksum
• skips remote-drift conflicts unless --force
• excludes system-managed fields (createdAt, updatedAt, createdBy, updatedBy) from push
• preserves collection-level runtime configurations from collections.json (for example soft-delete settings under configurations.soft_delete)

Key options:

• -p, --project-id <id>
• --product-key <key> push to all projects where project.product.key matches (cannot be used with --project-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
npx buildx-cli schema:push --product-key approval --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)
• @bx.type <SchemaType> (force schema field type, useful for unions)
• @bx.default <json>
• @bx.format <json_or_string>
• @bx.validate <json_or_string>
• @bx.props <json-object> (merge custom keys into propertiesScheme)

Required behavior:

• converter does not auto-assume required: true from non-optional TypeScript syntax by default.
• use @bx.required (or @bx.required false) for explicit required control.
• converter output is validated with the same recursive schema rules used by schema:push before writing collections.json.

System-managed fields:

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

Embedded object fidelity:

• inline object/list members are restored as structured children (not collapsed to item: Text).
• nested relation refs are normalized to collection IDs (for example Partial<Workflows> -> workflows).
• when merging with base collections.json, nested child metadata is preserved by child name when possible.
• dynamic object/list fallback stays as BxObject / BxList at type layer and Object / List in collection schema layer.
• dynamic mixed fallback uses BxMixed at type layer and Mixed in collection schema layer.
• temporary compatibility: string[] / BxText[] converts to MultipleChoices instead of generic List.
• schema:pull annotation style:
  • emits multiline JSDoc tags for readability
  • emits @bx.type only for lossy relation kinds (ReverseReference, ReverseReferences, Virtual)
  • enforces remote Mixed fields to BxMixed (not BxText) from source-of-truth collections payload

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
• stores manifest checksums using deterministic source checksum parity (normalized CRLF -> LF and trim) so local/remote comparisons stay stable
• 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
• uses deterministic source checksum parity between local and remote source
• skips push when local source is unchanged from remote source checksum
• 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>
• --product-key <key> push to all projects where project.product.key matches (cannot be used with --project-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
npx buildx-cli function:push --product-key approval --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

Comparison behavior:

• computes deterministic source checksums on normalized content (CRLF -> LF, trim) for both local and remote sources
• prints git-like unified patch blocks in default output for changed/missing functions

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --functions-dir <path> (when no --target-dir)
• -n, --name <function-name>
• --filter <pattern...>
• --no-patch (show summary/status only)

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

function:revisions <function-name>

Lists function revisions and shows which revision is live plus alias mapping.

Key options:

• -p, --project-id <id>
• -u, --api-url <url>
• --json

npx buildx-cli function:revisions process-order --project-id hello-world

function:publish <function-name> [revision]

Publishes a revision to alias (default alias: live). If revision is omitted, CLI publishes the latest revision.

Key options:

• -p, --project-id <id>
• -u, --api-url <url>
• --alias <alias> (default: live)

npx buildx-cli function:publish process-order --project-id hello-world
npx buildx-cli function:publish process-order r12 --project-id hello-world
npx buildx-cli function:publish process-order 12 --project-id hello-world --alias stable

Best practices:

• Use aliases as stable pointers for environments/traffic, not raw revision numbers in app code.
• Revision identifier is system-managed (r1, r2, ...). You cannot set revision id manually.
• If you want deployment traceability by git commit, use git hash as an alias (for example: a1b2c3d4 -> r42).
• Recommended alias convention:
  • live: production traffic
  • stable: last known good release
  • canary: limited rollout / verification
• Typical release flow:
  1. Save function in Studio/CLI (creates new revision automatically)
  2. Validate with function:invoke --revision rN
  3. Promote by alias: function:alias:set <fn> canary rN
  4. Promote to production: function:publish <fn> rN --alias live
  5. Fast rollback: function:alias:set <fn> live <previous-revision>
• For routine publish operations, run function:publish <fn> without revision to move the latest revision to live.
• Keep revision IDs immutable and treat alias changes as deployment events (track in release notes/ops logs).
• Use function:revisions <fn> to list revision id, checksum (short), and alias mapping in one place.

Git-hash alias example:

# Point alias named by git hash to a revision
npx buildx-cli function:alias:set process-order a1b2c3d4 r42 --project-id hello-world

# Publish latest revision to a git-hash alias
npx buildx-cli function:publish process-order --project-id hello-world --alias a1b2c3d4

# Inspect mapping + checksum
npx buildx-cli function:revisions process-order --project-id hello-world

function:alias:set <function-name> <alias> <revision>

Sets alias pointer directly to a revision.

Key options:

• -p, --project-id <id>
• -u, --api-url <url>

npx buildx-cli function:alias:set process-order canary r15 --project-id hello-world

AI Function Commands

ai-function:pull

Pulls AI function rows from buildx_ai_functions (fallback compatibility: buildx_ai_function).

Writes:

• buildx/ai-functions/functions.json
• buildx/ai-functions/functions.manifest.json

Key options:

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

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

ai-function:push

Pushes local AI function JSON back to buildx_ai_functions (fallback compatibility: buildx_ai_function).

Reads:

• buildx/ai-functions/functions.json
• buildx/ai-functions/functions.manifest.json (for drift detection)

Behavior:

• checks remote drift against local manifest baseline
• supports push-by-name and wildcard filter
• skips missing remote row unless --allow-create

Key options:

• -p, --project-id <id>
• -t, --target-dir <path>
• --data-file <path> (when no --target-dir)
• --manifest-file <path> (when no --target-dir)
• -n, --name <function-name>
• --filter <pattern...>
• --allow-create
• --dry-run
• -f, --force

npx buildx-cli ai-function:push --project-id hello-world --dry-run
npx buildx-cli ai-function:push --project-id hello-world --name summarize_order --force

ai-function:diff

Diffs local AI functions against remote collection.

Output markers:

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

npx buildx-cli ai-function:diff --project-id hello-world

Template Commands

template:pull

Pulls templates from buildx_templates.

Writes:

• buildx/templates/templates.json
• buildx/templates/templates.manifest.json

npx buildx-cli template:pull --project-id hello-world

template:push

Pushes local templates JSON back to buildx_templates.

Reads:

• buildx/templates/templates.json
• buildx/templates/templates.manifest.json (for drift detection)

npx buildx-cli template:push --project-id hello-world --dry-run

template:diff

Diffs local templates against remote buildx_templates.

npx buildx-cli template:diff --project-id hello-world

function:invoke <function-name>

Invokes function with optional revision or alias.

Key options:

• -p, --project-id <id>
• -u, --api-url <url>
• -X, --method <method>
• --revision <revision>
• --alias <alias>
• --data <json>
• --data-file <path>

npx buildx-cli function:invoke process-order --project-id hello-world --alias live --data '{"order_id":"A001"}'
npx buildx-cli function:invoke process-order --project-id hello-world --revision r12 --data-file ./payload.json

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
• GET /project/:project_id/functions/:function_name/revisions - List function revisions
• POST /project/:project_id/functions/:function_name/revisions/:revision/publish - Publish function revision
• PUT /project/:project_id/functions/:function_name/aliases/:alias - Update function alias
• POST /project/:project_id/functions/run/:function_name - Invoke function

CLI Output Formats (All Commands)

Detailed command-by-command examples (normal + --json): see OUTPUT_EXAMPLES.md.

General rules:

• Success output is human-readable by default unless command has explicit JSON mode.
• Error output is plain text: Error: <message> and exits non-zero.
• Commands with --json print JSON to stdout for automation.
• Commands that return documents (data:list/get/create/update/delete) are already JSON by default.

Authentication

• auth:login:
  • default: human-readable status lines
  • --json: { success, method, username, tokenMasked, expiresAt }
• auth:logout:
  • default: human-readable confirmation
  • --json: { success, authenticated }
• auth:status:
  • default: human-readable session summary
  • --json: { success, authenticated, user?, tokenMasked?, expiresAt? }

Projects

• projects:list:
  • default: human-readable list
  • --json: { success, projects[], total, defaultProjectId }
• projects:set-default:
  • default: human-readable confirmation
  • --json: { success, defaultProjectId, project }
• projects:current:
  • default: human-readable summary
  • --json: { success, defaultProject }
• projects:metadata:get: prints pretty JSON for selected metadata path.
  • --output <file> writes JSON file and prints success line.
• projects:metadata:update:
  • default: human-readable summary (default_language, timezone, key count)
  • --json: updated project payload JSON
  • --dry-run: payload JSON only
• projects:locale:validate: success line + JSON validation result.

Configuration

• config:setup:
  • default: interactive + human-readable summary
  • --json: { success, api: { endpoint, apiKeyMasked } }
• config:show:
  • default: human-readable configuration report
  • --json: structured config payload (api, auth, projects, sync, configPath, envSources)
• config:clear:
  • default: human-readable confirmation
  • --json: { success, cleared }

Users

• user:list:
  • default: tab-separated table (id, username, name, email) + total
  • --json: raw users array JSON
• user:create:
  • default: human-readable confirmation
  • --json: created user JSON

Schema

• schema:pull / schema:sync:
  • default: file write summary
  • --dry-run: file preview blocks (JSON/text)
  • --json: { success, command, project_id, output, dryRun }
• schema:push:
  • default: per-collection lines + pushed/skipped summary
  • --json: { success, pushed, skipped, results[] }
• schema:list:
  • default: one collection_id per line + total
  • --json: { success, total, collections[] }
• schema:diff markers:
  • = same
  • ~ changed
  • + local-only
  • - remote-only
  • --json: { success, summary, results[] }
• schema:types:convert:
  • default: conversion summary + output path
  • --dry-run: generated JSON preview
  • --json: { success, dryRun, output, collections_count, warnings[] }

Functions

• function:pull / function:sync:
  • default: file write summary
  • --dry-run: context/source/manifest preview blocks
  • --json: { success, command, project_id, output, dryRun }
• function:push:
  • default: per-function lines + pushed/skipped summary
  • --dry-run: would-push + manifest preview
  • --json: { success, pushed, skipped, results[] }
• function:list:
  • default: one function name per line + total
  • --json: { success, total, functions[] }
• function:logs:
  • default: timestamp status message lines + shown count
  • --json: raw log rows JSON
• function:diff markers:
  • = same
  • ~ changed
  • + local-missing
  • - remote-missing
  • ! remote-drift
  • --json: { success, summary, results[] }
• function:revisions:
  • default: one line per revision with
    • live marker ([live])
    • revision + revision_id
    • short checksum (source_checksum first 12 chars)
    • createdAt
    • alias mapping (aliases=...)
  • --json: array entries with keys:
    • revision
    • revision_id
    • checksum
    • createdAt
    • live
    • aliases
• function:publish:
  • default: confirmation + live revision + aliases object
  • [revision] omitted => auto uses latest revision
  • --json: { success, function, publishedRevision, alias, live_revision_id, aliases }
• function:alias:set:
  • default: confirmation line with alias target
  • --json: { success, function, alias, revision, aliases }
• function:invoke:
  • object/array response: pretty JSON
  • text response: plain text
  • --raw: raw response output

Data

• data:list: pretty JSON response.
• data:get: pretty JSON response.
• data:create: pretty JSON response.
• data:update: pretty JSON response.
• data:delete: pretty JSON response.
• data:export: writes JSON file + summary line.
  • --json: { success, collection_id, project_id, count, output }
• data:import:
  • default: summary (created, updated)
  • --dry-run: simulated summary lines
  • --json: structured import result (success, collection_id, project_id, mode, batch, dryRun, created, updated, match?)

Revision/Alias Definition (Important)

• Function revision is system-managed and immutable (r1, r2, ...).
• You cannot set custom revision id (for example git hash) as revision.
• If you need git-traceable deployment labels, use alias names as git hash values.
• Example:
  • function:alias:set process-order a1b2c3d4 r42
  • function:revisions process-order (to inspect mapping + checksum)

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.