# Deep dive into Crane CLI

Crane is a **command line interface** for creating, building, and deploying custom sections within the Lightspeed E-Commerce ecosystem. 

Follow this article to learn all CLI features provided by this tool.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before using Crane CLI, you need:

1. **Node.js 22.x** - Recommended for best compatibility
2. **Lightspeed Application** - Contact your Partner Manager for:
   * Application credentials (client ID and secret)
   * Test site access for verification
   * Required permissions

### Installation <a href="#installation" id="installation"></a>

Install Crane and its dependencies in your project:

```bash
npm install vite vue @lightspeed/crane@latest @lightspeed/eslint-config-crane@latest
```

### Commands <a href="#commands" id="commands"></a>

Find a list of available Crane CLI commands below.&#x20;

{% hint style="success" %}
**To push changes to Ecwid:**

Call `build` and `deploy` commands every time you need to push some changes into your Crane app.
{% endhint %}

#### Initialize a New Application <a href="#initialize-a-new-application" id="initialize-a-new-application"></a>

Create a new Crane application:

```bash
npx @lightspeed/crane@latest init --app app-name
```

{% hint style="info" icon="keyboard" %}
**Interactive Prompt**

If you omit the `app-name`, you'll be prompted to enter it interactively.
{% endhint %}

This creates:

* Application folder with default resources
* Configuration files
* Assets and TypeScript files
* One example section in `sections/example-section`

**Example with specified app name:**

```bash
npx @lightspeed/crane@latest init --app my-app
cd my-app
```

**Example with no specified app name:**

```bash
npx @lightspeed/crane@latest init --app
## Please specify a name for your app: ›
```

#### Create a New Section <a href="#create-a-new-section" id="create-a-new-section"></a>

Add a custom section to your application:

{% hint style="warning" %}
**Working Directory**

Run this command from your application folder (created with `init --app`).
{% endhint %}

```bash
npx @lightspeed/crane@latest init --section section-name
```

{% hint style="info" icon="keyboard" %}
**Interactive Prompt**

If you omit the `section-name` name, you'll be prompted to enter it interactively.
{% endhint %}

Creates section files in `sections/<section-name>` directory.

**Example:**

```bash
npx @lightspeed/crane@latest init --section my-custom-section
```

By providing the `--blank` flag, you can create a section with the minimum required files for the section to work.

```bash
npx @lightspeed/crane@latest init --section my-custom-section --blank
```

#### Create a new template <a href="#build-the-application" id="build-the-application"></a>

{% hint style="warning" %}
**Working Directory**

Run this command from your application folder (created with `init --app`).
{% endhint %}

```bash
npx @lightspeed/crane@latest init --template template-name
```

{% hint style="info" icon="keyboard" %}
**Interactive Prompt**

If you omit the `template-name` name, you'll be prompted to enter it interactively.
{% endhint %}

Creates section files in `sections/<template-name>` directory.

**Example:**

```bash
npx @lightspeed/crane@latest init --section my-custom-template
```

#### Build the Application <a href="#build-the-application" id="build-the-application"></a>

Build your application for deployment:

```bash
npx @lightspeed/crane@latest build
```

Creates `dist` and `node_modules` directories with compiled output.

#### Preview Locally <a href="#preview-locally" id="preview-locally"></a>

Start a local development server:

```bash
npx @lightspeed/crane@latest preview
```

Features:

* Opens preview URL in your terminal
* Hot reload - build once, refresh browser to see changes
* No need to restart after subsequent builds

#### Deploy to Lightspeed <a href="#deploy-to-lightspeed" id="deploy-to-lightspeed"></a>

Deploy your application to production:

```bash
npx @lightspeed/crane@latest deploy
```

{% hint style="warning" %}
**Prerequisites**

Ensure `crane.config.json` is properly configured before deploying.
{% endhint %}

#### Get Help <a href="#get-help" id="get-help"></a>

Display available commands and options:

```bash
npx @lightspeed/crane@latest --help
```

### Configuration <a href="#configuration" id="configuration"></a>

#### crane.config.json <a href="#crane-config-json" id="crane-config-json"></a>

Configure your application credentials in `crane.config.json`:

```json
{
  "app_client_id": "{your_client_id}",
  "app_secret_key": "{your_client_secret}"
}
```

{% hint style="warning" icon="sliders" %}
Find the `client_id` and `client_secret` values for your custom application to the file. Find these values at the bottom of the [**Ecwid admin > #develop-apps > Details**](https://my.ecwid.com/#develop-apps) page.
{% endhint %}

{% hint style="danger" %}
**Keep Credentials Safe**

Never commit `crane.config.json` with real credentials to version control. Add it to `.gitignore`.
{% endhint %}

### Complete Workflow Example <a href="#complete-workflow-example" id="complete-workflow-example"></a>

Here's a typical workflow for creating and deploying a Crane application:

#### 1. Create Application <a href="#id-1-create-application" id="id-1-create-application"></a>

```bash
npx @lightspeed/crane@latest init --app my-store-app
cd my-store-app
```

#### 2. Add Custom Templates <a href="#id-2-add-custom-templates" id="id-2-add-custom-templates"></a>

```bash
npx @lightspeed/crane@latest init --template custom-template
```

#### 3. Add Custom Sections (Optional) <a href="#id-3-add-custom-sections-optional" id="id-3-add-custom-sections-optional"></a>

```bash
npx @lightspeed/crane@latest init --section product-showcase
npx @lightspeed/crane@latest init --section custom-cart
```

#### 4. Configure Credentials <a href="#id-4-configure-credentials" id="id-4-configure-credentials"></a>

Edit `crane.config.json`:

```json
{
  "app_client_id": "your-client-id-here",
  "app_secret_key": "your-secret-key-here"
}
```

#### 5. Develop and Preview <a href="#id-5-develop-and-preview" id="id-5-develop-and-preview"></a>

```bash
# Build your application
npx @lightspeed/crane@latest build

# Start preview server
npx @lightspeed/crane@latest preview
```

Open the preview URL in your browser and test your sections.

#### 6. Deploy <a href="#id-6-deploy" id="id-6-deploy"></a>

```bash
npx @lightspeed/crane@latest deploy
```

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Build Failures <a href="#build-failures" id="build-failures"></a>

If the build command fails:

```bash
npm install
npx @lightspeed/crane@latest build
```

#### HTTP 401 Error During Deployment <a href="#http-401-error-during-deployment" id="http-401-error-during-deployment"></a>

**Cause:** Invalid credentials

**Solution:** Verify `crane.config.json` has correct `app_client_id` and `app_secret_key`

#### HTTP 403 Error During Deployment <a href="#http-403-error-during-deployment" id="http-403-error-during-deployment"></a>

**Cause:** Insufficient permissions

**Solution:** Contact your Partner Manager to grant the necessary permissions

#### Preview Not Working <a href="#preview-not-working" id="preview-not-working"></a>

**Cause:** Build artifacts are missing or outdated

**Solution:**

```bash
npx @lightspeed/crane@latest build
npx @lightspeed/crane@latest preview
```

### Use Crane CLI in your project <a href="#next-steps" id="next-steps"></a>

* [Install Crane to your system](/site-themes/develop-site-themes/getting-started/install-crane-to-your-system.md)
* [Start with Crane app](/site-themes/develop-site-themes/getting-started/start-with-crane-app.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/getting-started/deep-dive-into-crane-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.