BILD CLI

Command-line tool for managing BILDIT CMS code library items. Upload, transpile, version, and manage code library components for React and Next.js applications.

Installation

Global Installation (Recommended)

Install the CLI globally to use it from anywhere:

npm install -g bild-cli

After installation, you can use the bild command from any directory:

bild --help

Local Installation

Install the CLI locally in your project:

npm install bild-cli

When installed locally, use it via npx:

npx bild --help

Or add it to your package.json scripts:

{
  "scripts": {
    "bild": "bild"
  }
}

Then run:

npm run bild --help

Requirements

• Node.js version 20 or higher
• npm or yarn package manager

Quick Start

1. Install the CLI:

   npm install -g bild-cli

2. Initialize configuration:

   bild init

3. Authenticate with BILDIT CMS:

   bild login <cms-url>
   # Example: bild login https://firebasestage.belk.com

4. List available apps:

   bild list-apps

5. Add a code library item:

   bild library add hero.jsx --app-id <app-id> --template-id hero --image ./preview.png

Usage

Using npm

After installing globally with npm install -g bild-cli, you can use bild from any directory:

bild --help
bild list-apps
bild library add my-component.jsx

Using npx (without installation)

You can also use the CLI without installing it globally:

npx bild-cli --help
npx bild-cli list-apps
npx bild-cli library add my-component.jsx

Using as npm script

Add to your package.json:

{
  "scripts": {
    "bild": "bild",
    "bild:add": "bild library add",
    "bild:update": "bild library update",
    "bild:list": "bild list-apps"
  }
}

Then run:

npm run bild --help
npm run bild:add hero.jsx --app-id my-app
npm run bild:list

Commands

bild init

Initialize the configuration file (~/.bild.json) with default settings.

bild init

Prompts for:

• BILDIT CMS instance URL
• Default App ID (optional)
• Default API Key (optional)
• React version

bild login [url]

Authenticate with BILDIT CMS using OAuth. Opens a browser for authentication.

bild login
bild login https://your-cms-instance.web.app

The authentication token is stored securely using the system keychain.

bild library add <files...>

Add/create a new code library item in BILDIT CMS. Supports individual files or folders.

# Add single file (will prompt for missing info)
bild library add hero.jsx

# Add file with all options
bild library add hero.jsx \
  --app-id <app-id> \
  --template-id hero \
  --code-type jsx \
  --type Homepage \
  --name HeroStandard \
  --description "Hero banner component" \
  --image ./preview.png

# Add multiple files
bild library add hero.jsx footer.jsx --app-id <app-id>

# Add all files from a folder
bild library add ./components --app-id <app-id>

Options:

• --app-id <id> - App ID (uses defaultAppId from config if not provided)
• --template-id <id> - Template ID (extracted from filename if not provided)
• --code-type <type> - Code type: jsx, tsx, or html (detected from file extension)
• --type <type> - Code library type (default: "Homepage")
• --description <desc> - Description for the code library item
• --name <name> - Display name (defaults to template ID)
• --image <url> - Image URL or local file path (will be uploaded if local file)

Aliases: bild library create (same as add)

bild library update <files...>

Update an existing code library item in BILDIT CMS.

# Update (will prompt to select item if template-id not provided)
bild library update hero.jsx

# Update with template-id (no prompt)
bild library update hero.jsx --template-id herostandard7

# Update with all options
bild library update hero.jsx \
  --template-id herostandard7 \
  --app-id <app-id> \
  --code-type jsx \
  --type Homepage \
  --name HeroStandard \
  --image ./preview-new.png

Options:

• --app-id <id> - App ID (uses defaultAppId from config if not provided)
• --template-id <id> - Template ID (if not provided, will show list to select)
• --cid <id> - Code library ID (if not provided, will show list to select)
• --code-type <type> - Code type: jsx, tsx, or html (detected from file extension)
• --type <type> - Code library type (keeps existing if not provided)
• --description <desc> - Description (keeps existing if not provided)
• --name <name> - Display name (keeps existing if not provided)
• --image <url> - Image URL or local file path (keeps existing if not provided)

Supported file types:

• .js, .jsx, .ts, .tsx, .html
• Template files (.template.jsx)

What happens during upload:

1. File is read and code type is detected
2. Code is linted (ESLint + Tailwind validation)
3. Code is transpiled for Next.js/React compatibility
4. Screenshot is captured (if no image provided)
5. Code library is created/updated in CMS
6. New version is created automatically

bild list-apps

List all available apps and websites in the BILDIT CMS.

bild list-apps

Displays:

• App/Website ID
• Name
• Type (App for React Native, Website for React/Next.js)
• Description (if available)

bild list-code-libs

List all code library items for a specific app.

# Use default app from config
bild list-code-libs

# Specify app ID
bild list-code-libs --app-id my-app

Options:

• --app-id <id> - App ID (uses defaultAppId from config if not provided)

bild use

Select and set a default app or website from the available list.

bild use

This will:

1. Fetch all available apps and websites
2. Show an interactive list to select from
3. Update your ~/.bild.json config with the selected app ID

bild copy <template-id>

Copy a code library item from one app to one or more target apps.

# Copy to single target app
bild copy herostandard7 --from PaintingBanner --to belk-dev-web

# Copy to multiple target apps
bild copy herostandard7 --from PaintingBanner --to app1 app2 app3

Options:

• --from <app-id> - Source app ID (required)
• --to <app-ids...> - Target app ID(s) (required, can specify multiple)

Note: The template-id argument must come before the options.

bild update-banners <template-id>

Update banners that use a specific code library template with the latest version.

# Update all future-dated unpublished banners
bild update-banners herostandard7 --app-id <app-id>

# Update banners within date range
bild update-banners herostandard7 \
  --app-id <app-id> \
  --start-date 2024-01-01 \
  --end-date 2024-12-31

# Override published banner restriction
bild update-banners herostandard7 \
  --app-id <app-id> \
  --override

Options:

• --app-id <id> - App ID (required)
• --start-date <date> - Start date filter (ISO format)
• --end-date <date> - End date filter (ISO format)
• --override - Update published banners (default: only unpublished)

Banner filtering:

• Only updates banners that use the specified template ID
• Only updates unpublished banners (unless --override is used)
• Only updates banners with future-dated schedules
• Respects date range filters if provided

Configuration

Configuration is stored in ~/.bild.json:

{
  "cmsUrl": "https://your-cms-instance.web.app",
  "defaultAppId": "your-app-id",
  "defaultApiKey": "your-api-key",
  "reactVersion": "18.2.0"
}

Features

Code Transpilation

Code is automatically transpiled using Babel to ensure compatibility with Next.js and React applications. Supports:

• JavaScript (.js)
• JSX (.jsx)
• TypeScript (.ts, .tsx)
• HTML (.html)

Linting

Integrated linting checks:

• ESLint with React/JSX rules
• Tailwind CSS class validation
• Template syntax validation ($(variable:Type))

Screenshot Capture

Automatically captures screenshots of code library components using Playwright:

• Maximum width: 500px
• Maintains aspect ratio
• Supports URL or local file rendering

Version Management

Automatic versioning:

• Versions are auto-incremented (v1, v2, v3...)
• Stored at /apps/{appId}/codelibs/{cid}/versions/{versionId}
• Each version includes raw code, compiled code, and preview image

Error Handling

The CLI provides user-friendly error messages for common issues:

• Authentication errors
• API errors
• Validation errors
• File not found errors

Examples

Add a new code library item

bild library add src/components/HeroStandard.jsx \
  --app-id my-app \
  --template-id herostandard \
  --code-type jsx \
  --type Homepage \
  --name HeroStandard \
  --image ./hero-preview.png

Update an existing code library item

bild library update src/components/HeroStandard.jsx \
  --template-id herostandard7 \
  --app-id my-app \
  --image ./hero-preview-new.png

Copy component across apps

bild copy herostandard7 --from app1 --to app2 app3 app4

Update banners for upcoming campaign

bild update-banners herostandard7 \
  --app-id my-app \
  --start-date 2024-02-01 \
  --end-date 2024-02-29

List available apps and websites

bild list-apps

List code library items for an app

bild list-code-libs --app-id my-app

Set default app

bild use
# Follow the interactive prompt to select an app

Troubleshooting

Authentication Issues

If you encounter authentication errors:

1. Run bild login again to refresh your token
2. Ensure the CMS URL is correct
3. Check that your browser can access the CMS instance

Firebase Access Issues

Some commands require direct Firebase access. If you encounter errors:

• Ensure your authentication token has proper permissions
• Verify the Firebase database URL format
• Check that the app ID exists in the CMS

Transpilation Errors

If code fails to transpile:

• Check for syntax errors in your code
• Ensure all imports are valid
• Verify React version compatibility

Contributing

This CLI tool follows the BILDIT CMS contributing guidelines for code quality and linting standards.

License

ISC