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

$3

Install the CLI globally to use it from anywhere:

``bash
npm install -g bild-cli
`

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

`bash
bild --help
`

$3

Install the CLI locally in your project:

`bash
npm install bild-cli
`

When installed locally, use it via npx:

`bash
npx bild --help
`

Or add it to your package.json scripts:

`json
{
"scripts": {
"bild": "bild"
}
}
`

Then run:

`bash
npm run bild --help
`

$3

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

Quick Start

1. Install the CLI:
`bash
npm install -g bild-cli
`

2. Initialize configuration:
`bash
bild init
`

3. Authenticate with BILDIT CMS:
`bash
bild login
# Example: bild login https://firebasestage.belk.com
`

4. List available apps:
`bash
bild list-apps
`

5. Add a code library item:
`bash
bild library add hero.jsx --app-id --template-id hero --image ./preview.png
`

Usage

$3

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

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

$3

You can also use the CLI without installing it globally:

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

$3

Add to your package.json:

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

Then run:

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

Commands

$3

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

`bash
bild init
`

Prompts for:
- BILDIT CMS instance URL
- Default App ID (optional)
- Default API Key (optional)
- React version

$3

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

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

The authentication token is stored securely using the system keychain.

$3

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

`bash


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 \
--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

Add all files from a folder

bild library add ./components --app-id
`

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

Aliases: bild library create (same as add)

$3

Update an existing code library item in BILDIT CMS.

`bash


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 \
--code-type jsx \
--type Homepage \
--name HeroStandard \
--image ./preview-new.png
`

Options:
- --app-id - App ID (uses defaultAppId from config if not provided)
- --template-id - Template ID (if not provided, will show list to select)
- --cid - Code library ID (if not provided, will show list to select)
- --code-type - Code type: jsx, tsx, or html (detected from file extension)
- --type - Code library type (keeps existing if not provided)
- --description - Description (keeps existing if not provided)
- --name - Display name (keeps existing if not provided)
- --image - 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

$3

List all available apps and websites in the BILDIT CMS.

`bash
bild list-apps
`

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

$3

List all code library items for a specific app.

`bash


Use default app from config

bild list-code-libs

Specify app ID

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

Options:
- --app-id - App ID (uses defaultAppId from config if not provided)

$3

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

`bash
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

$3

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

`bash


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 - Source app ID (required)
- --to - Target app ID(s) (required, can specify multiple)

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

$3

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

`bash


Update all future-dated unpublished banners

bild update-banners herostandard7 --app-id

Update banners within date range

bild update-banners herostandard7 \
--app-id \
--start-date 2024-01-01 \
--end-date 2024-12-31

Override published banner restriction

bild update-banners herostandard7 \
--app-id \
--override
`

Options:
- --app-id - App ID (required)
- --start-date - Start date filter (ISO format)
- --end-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:

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

Features

$3

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)

$3

Integrated linting checks:
- ESLint with React/JSX rules
- Tailwind CSS class validation
- Template syntax validation ($(variable:Type))

$3

Automatically captures screenshots of code library components using Playwright:
- Maximum width: 500px
- Maintains aspect ratio
- Supports URL or local file rendering

$3

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

$3

`bash
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
`

$3

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

$3

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

$3

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

$3

`bash
bild list-apps
`

$3

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

$3

`bash
bild use


Follow the interactive prompt to select an app


`

Troubleshooting

$3

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

$3

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

$3

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