Built.js CLI

Usage

npx create-built-app [command]

Available Commands

new

Creates new Built.js resources.

npx create-built-app new <type> [name]

Supported types:

• theme: Create a new theme
• plugin: Create a new plugin
• site: Create a new site from an existing theme

Regular Theme Creation:

npx create-built-app new theme

Creates a theme from scratch using AI prompts. You'll be prompted for:

• Theme name
• Theme description (used as AI prompt in the define and design commands and if using --fromUrl)
• Username (must be alphanumeric with hyphens)

URL-Based Theme Creation:

npx create-built-app new theme --fromUrl "https://example.com"

Creates a theme by analyzing an existing website. You'll be prompted for:

• Theme name
• Username (must be alphanumeric with hyphens)

When to use each approach:

• Regular creation: When you have a clear vision and want to describe your theme concept
• URL-based creation: When you want to replicate or adapt an existing website's design

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 Site from Theme

Creates a new site by downloading site files from the Built.js based on an existing theme project.

npx create-built-app new site "Site Name"

Requirements:

• Must be run from a directory containing a theme project
• Theme project must have public/data/theme.json with a valid namespace
• Valid API key for Built.js

Output: Creates a directory named built-site-<kebab-case-name> (e.g., "My Site" → built-site-my-site) containing the downloaded site files.

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

Options:

• --url <url>: Generate sitemap from a URL using vision AI
• --from-config: Generate sitemap from existing config files

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

create

Creates templates for specific sections.

npx create-built-app create <section-name>
npx create-built-app create --all

Options:

• --all: Create templates for all sections

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
5. When creating sites, ensure you're in the correct directory with a valid theme project
6. Use descriptive site names that will work well when converted to directory names

Examples

Create a theme from a prompt

# 1. Create the core files of a theme
npx create-built-app new theme
 
# Follow the CLI commands in the generated theme's README.md file...
 
# 2. Generate sitemap from the theme's description
npx create-built-app define
 
# Review your sitemap...
 
# 3. Create all the theme files based on the sitemap
npx create-built-app design

Create a theme from an existing url

# 1. Create the core files of a theme
npx create-built-app new theme
 
# Follow the CLI commands in the generated theme's README.md file...
 
# 2. Define sitemap from URL
npx create-built-app define --url https://example.com
 
# Review your sitemap...
 
# 3. Create all the theme files based on the sitemap
npx create-built-app design --url https://example.com

Create a site from a theme

# Navigate to the parent directory of the theme project...
 
# 1. Publish to Built Studio
npx create-built-app publish
 
# 2. Create site from theme
npx create-built-app new site "My Awesome Site"
 
# This creates: built-site-my-awesome-site/
 
# Follow the CLI commands in the generated site's README.md file...