Built.js CLI

Usage

npx create-built-app [command]

Available Commands

define

Creates a mermaid sitemap in the root of your project. This sitemap will be used by the AI model to create files and templates for the theme or plugin in the design command.

npx create-built-app define

design

Creates data files and templates using the mermaid sitemap in the root of the project. This command has several options to run specific tools:

npx create-built-app design [options]

Options:

• --templates: Run only the templates tool
• --collections: Run only the collections tool
• --global: Run only the global tool
• --layout: Run only the layout tool
• --modules: Run only the modules tool
• --sections: Run only the sections tool
• --schemas: Run only the schemas tool
• --page-content-types: Run only the pageContentTypes tool
• --template-descriptions: Run only the templateDescriptions tool
• --pages: Run only the pages tool

publish

Imports your theme or plugin into Built Studio where they can be used to create sites.

npx create-built-app publish [options]

Options:

• -t, --type <type>: Type of project (theme or plugin), defaults to 'theme'

init

Creates the necessary files in a fresh Next.js app, used for themes, plugins and sites.

npx create-built-app init

setup

Sets up your site with Sanity data.

npx create-built-app setup

update

Updates your theme or plugin. To be run whenever updates are made to data in the public/data directory.

npx create-built-app update [options]

Options:

• --plugins: Include plugins in the update
• --screenshots: Update screenshots for all sections
• -p, --port <number>: Specify the port number of the Next.js app

new

Creates new Built.JS resources.

npx create-built-app new <type>

Supported types:

• theme: Create a new theme
• plugin: Create a new plugin
• template: Create a new template

Creating a Theme

When creating a theme, you'll be prompted for:

• Theme name
• Theme description (used as AI prompt)
• Username (must be alphanumeric with hyphens)

Creating a Plugin

When creating a plugin, you'll be prompted for:

• Plugin name
• Plugin description (used as AI prompt)
• Username (must be alphanumeric with hyphens)

Creating a Template

When creating a template, you'll be prompted for:

• Section name (optional, leave empty to process all sections)
• Template UI description (used as AI prompt)

Environment Setup

Here are the environment variables required for specific commands:

Required Environment Variables

For define and design commands to create themes and plugins using your own AI model:

• OPENAI_API_KEY: Your OpenAI API key for AI-powered template generation
• UNSPLASH_ACCESS_KEY: Your Unsplash API key for image generation (optional)

For set up of Sanity data for a site:

• NEXT_PUBLIC_SANITY_PROJECT_ID: The Sanity project ID
• NEXT_PUBLIC_SANITY_WRITE_TOKEN: The Sanity project's write token

Best Practices

1. Use the --help flag to see command-specific options
2. When creating new resources, provide detailed descriptions for better AI-generated results
3. Keep your project data up to date using the update command
4. Use the publish command to make your theme or plugin available in Built Studio