title: "CLI" description: "Command-line interface for creating and managing Fireberry apps"

Fireberry CLI

The Fireberry CLI (@fireberry/cli) is your command-line tool for creating, deploying, and managing Fireberry apps.

Resources:

• npm package
• GitHub repository

Installation

npm install -g @fireberry/cli@latest

After installation, authenticate with your API token:

fireberry init

App Versioning

Every app version is in one of three states:

Rules:

• There is at most one Draft and one Live version per app at any time.
• Version numbers are sequential integers (V1, V2, V3…), incrementing on each deploy cycle.

Typical lifecycle:

fireberry create    → creates Draft V1
fireberry push      → updates Draft V1
fireberry deploy    → Draft V1 becomes Live; run again later to deploy V2, V3, etc.
fireberry install   → makes the Live version available to your org (run once)

After the first deploy, updating your app is just push + deploy. A new Draft is created automatically when you push against a Live version.

Commands

Marketplace commands:

fireberry init

Stores your API token for authentication.

fireberry init [tokenid]

Examples:

# Interactive — prompts for token
fireberry init

# Direct — pass token as argument
fireberry init abc123xyz

Token storage location:

fireberry create

Scaffolds a new Fireberry app with your first component using Vite + React.

fireberry create [name]

What it does:

1. Creates app directory and manifest.yml
2. Registers app with Fireberry backend
3. Prompts for your first component:
   • Component name
   • Component type (record, side-menu, or global-menu)
   • Type-specific settings
4. Scaffolds a Vite + React project for the component
5. Installs dependencies (@fireberry/sdk, @fireberry/ds)
6. Builds the component

Example:

fireberry create my-awesome-app

Generated structure:

my-awesome-app/
├── manifest.yml
└── my-awesome-app-component/
    ├── src/
    │   ├── App.jsx
    │   ├── main.jsx
    │   └── App.css
    ├── dist/
    ├── package.json
    ├── vite.config.js
    └── node_modules/

Output example:

Creating app "my-awesome-app"...
✔ App directory "my-awesome-app" created!
📁 Location: /path/to/my-awesome-app
App ID: 1f3a3eca-d551-4cd0-a1d7-4a1f2e431e26

Adding component "my-awesome-app-component"...
Creating Vite React app...
✔ Component created
Installing dependencies...
✔ Dependencies installed
Building component...
✔ Component built

✔ Successfully created component "my-awesome-app-component"!
Component ID: 864fbfb2-e7ca-4e9e-8532-9f02b1e7936f
Type: record
Path: my-awesome-app-component/dist

🎉 Your app is ready!

Next steps:
   cd my-awesome-app
   fireberry push      # Upload to your Draft
   fireberry deploy    # Publish Draft as Live
   fireberry install   # Install on your account (once)

⚠️

Warning

App names must match the pattern ^[a-zA-Z0-9_-]+$. Spaces and special characters are not allowed.

fireberry create-component

Adds a new component to an existing Fireberry app.

fireberry create-component [name] [type]

What it does:

1. Prompts for type-specific settings
2. Creates Vite + React project in [component-name] directory with appropriate template by type
3. Installs dependencies
4. Builds the component
5. Updates manifest.yml with new component

Type-Specific Prompts:

Example:

# Interactive mode
fireberry create-component

# With parameters
fireberry create-component analytics-panel global-menu

Output example:

Creating Vite React app for "analytics-panel"...
Running npm create vite@latest...
✔ analytics-panel created
Installing dependencies...
✔ Dependencies installed
Installing Fireberry packages...
✔ Fireberry packages installed
Configuring component...
Building component...
✔ Component built
Adding component to manifest...

✔ Successfully created component "analytics-panel"!
Component ID: 9f02b1e7-8532-864f-bb2e-7936fca4e9e8
Type: global-menu
Path: analytics-panel/dist

Your component "analytics-panel" is ready!
   cd analytics-panel
   npm run dev    # Start development server
   npm run build  # Build for production

Component templates:

• Record components: Include SDK initialization, context access, example button with API call
• Other components: Simple structure with Design System theming, ready for customization

📘

Note

Each component gets its own node_modules, package.json, and Vite configuration. This allows components to have different dependencies if needed.

fireberry push

Uploads your component changes to the current Draft version.

fireberry push

Requirements:

• Must run from your app's root directory (where manifest.yml is located)
• All component paths must exist and contain index.html

What it does:

1. Validates your manifest.yml
2. Validates component settings for each type
3. Packages each component (tar.gz)
4. Uploads to the current Draft on Fireberry servers

📘

Note

push targets the Draft version only. If no Draft exists (because the last version is already Live), a new Draft is created automatically before uploading. To make your changes visible to org users, run fireberry deploy after pushing.

Example output:

✔ Manifest loaded successfully
✔ 2 components validated and zipped

Components ready to push:
  1. record-view (864fbfb2...) - 45.23 KB
  2. side-panel (9f02b1e7...) - 12.87 KB

✔ Components pushed successfully

fireberry deploy

Promotes the current Draft to Live, making it available to org users.

fireberry deploy

Requirements:

• Must run from your app's root directory
• A Draft version must exist (run fireberry push first)

What it does:

1. Promotes the current Draft to Live
2. Deprecates the previous Live version (only from the second deploy onward — on first deploy there is no prior Live version to deprecate)

Example output:

✔ Manifest loaded successfully
✔ App "my-awesome-app" deployed successfully
  Version 1 is now Live

📘

Note

After deploying, the next fireberry push will automatically create a new Draft (V2, V3, etc.) — you don't need to do anything extra.

fireberry install

Installs your app on your Fireberry account.

fireberry install

Requirements:

• Must run from your app's root directory
• A Live version must exist (run fireberry push then fireberry deploy first)

📘

Note

You only need to run install once. After that, use fireberry push + fireberry deploy to update your app — installed users will automatically get the new Live version.

fireberry debug

Enables debugging a component with your local development server. Changes appear instantly with hot module replacement.

fireberry debug <component-id> <url>
fireberry debug <component-id> --stop

Requirements:

• Must run from your app's root directory
• A Live version must exist — run fireberry push then fireberry deploy first

Starting debug mode:

1. Start your component's dev server:

cd my-component
npm run dev
# Runs on http://localhost:5173

2. Enable debug mode:

fireberry debug abc-123-def-456 localhost:5173

Output:

Loading manifest...
✔ Manifest loaded
Starting debug mode for component abc-123-def-456...
✔ Debug mode started!
  Component: abc-123-def-456
  URL: localhost:5173

  To stop debugging, run: fireberry debug abc-123-def-456 --stop

What happens:

• Fireberry loads the component from your local dev server instead of production
• Changes appear instantly thanks to Vite's hot module replacement

Stopping debug mode:

fireberry debug abc-123-def-456 --stop

Output:

Loading manifest...
✔ Manifest loaded
Stopping debug mode...
✔ Debug mode stopped for component: abc-123-def-456

The component reverts to loading from the production build specified in your manifest.

Finding component IDs:

Component IDs are in your manifest.yml:

components:
  - type: record
    title: my-component
    id: "abc-123-def-456" # This is your component ID
    path: my-component/dist

📘

Learn More

See Local Development for a complete debugging workflow guide.

Validation:

fireberry delete

Permanently deletes your app from Fireberry.

fireberry delete

The CLI will ask for confirmation:

? Are you sure you want to delete app my-awesome-app (1f3a3eca...)?
  This action cannot be undone. (y/N)

❗️

Danger

Deletion is permanent and irreversible. The app will be removed from all accounts where it was installed.

Marketplace Apps

The fireberry marketplace commands publish apps to the public Fireberry marketplace, where any organization can find and install them. This is a separate track from the private-app flow (create → push → deploy → install), which publishes only to your own organization.

The expected flow

You don't start a marketplace app from scratch. Develop your private app first, and once you're satisfied with it, fork it and publish the fork:

cd my-app                                                 # 1. your finished private app
fireberry marketplace clone /Users/me/apps/my-app-market  # 2. fork → new app id
cd /Users/me/apps/my-app-market                           # 3. publish from the clone
fireberry marketplace deploy

Cloning is a one-time step per marketplace app; after that you publish updates with marketplace deploy from the cloned folder.

❗️

Two different apps, two different manifests

The clone is not another version of your private app — it's a separate entity with its own app.id and its own component IDs. Deploying to the marketplace never converts, moves, or promotes the private app.

So you maintain two manifest.yml files in two folders: one for the private app, one for the marketplace app. Run push, deploy, install, and debug in the private folder, and marketplace deploy in the clone — every command acts on the manifest in the current directory. Code changes must be applied and published in each folder separately.

fireberry marketplace clone

Copies the current app into a new folder with a fresh identity, so the copy is an independent app rather than a duplicate of the same one. App and component IDs must be unique across Fireberry, so a plain cp -r would leave you with two folders claiming to be the same app — this is the safe way to fork one.

fireberry marketplace clone [dest-folder]

Requirements: Must be run inside an app directory — it reads manifest.yml from the current directory. No token is needed; clone makes no API calls, so the new app doesn't exist server-side until you deploy it.

What it does:

1. Copies everything from the app folder, skipping node_modules and the destination itself.
2. Rewrites the destination's manifest.yml with a new app UUID and a new UUID for every component.

Everything else carries over unchanged — app name, description, icon, and each component's title, path, type, and settings.

It refuses to run if the destination equals the source, exists as a non-directory, or exists and is non-empty.

⚠️

Pass a full path — a bare folder name will fail

The destination is resolved relative to the current directory, which is your app folder — so a bare name like market-app lands inside the app you're cloning, and an app can't be copied into itself:

$ pwd
/Users/me/fireberry/version-test/sara-version-test
$ fireberry marketplace clone
? Destination folder: market-app
✖ Failed to clone app into "market-app"
Error: Cannot copy '/Users/me/fireberry/version-test/sara-version-test' to a subdirectory
of itself, '/Users/me/fireberry/version-test/sara-version-test/market-app'.

Pass the full path to a folder outside the app instead:

Bash

fireberry marketplace clone /Users/me/fireberry/version-test/market-app

⚠️

node_modules is the only exclusion

.git, .env files, and built dist/ output are all copied — check the clone for secrets before sharing it. Component titles are copied too; only IDs change, so rename them in the new manifest if you want them distinguishable.

fireberry marketplace deploy

Publishes the current app's built components to the public Fireberry marketplace.

fireberry marketplace deploy

cd /Users/me/apps/my-app-market    # the cloned app, not the private one
fireberry marketplace deploy

Requirements: a token from fireberry init, a manifest.yml in the working directory, and components already built — each entry's path must point at existing build output.

What it does:

1. Loads manifest.yml, and validates and reads app.icon if it's set.
2. Validates every component and packages each build as tar.gz — checks that each path exists, that all component IDs are unique, and that each type has its required settings.
3. Prints a per-component summary (title, ID, size in KB), then POSTs to /services/developer/app/marketplace/deploy with { components, manifest, icon }.

Required settings by component type:

Icon rules (when app.icon is set): must be .svg/.png/.jpg/.jpeg, non-empty, and ≤ 500 KB. Its size is reported on success.

⚠️

Run this from the cloned folder

marketplace deploy publishes whatever app the current directory's manifest.yml describes. Run it inside your private app folder and you publish your private app's identity to the public marketplace.

An app with no components is an error, not a graceful skip — validation fails with No components found in manifest and the deploy aborts. The same applies to push.

push vs. deploy vs. marketplace deploy

These three commands sound similar and are the easiest place to go wrong:

marketplace deploy and push send identical payloads — they differ only in destination endpoint, and therefore in which app the payload lands on. Since each reads the manifest.yml in the current directory, running the right command from the wrong folder publishes the wrong app. Confirm which folder you're in before deploying: the private app is updated with push + deploy, and the clone with marketplace deploy.

Manifest Reference

The manifest.yml file defines your app configuration.

Structure

app:
  id: "uuid"
  name: "string"
  description: "string"
  icon: "string"

components:
  - type: "record"
    title: "string"
    id: "uuid"
    path: "string"
    settings: { ... }

App Properties

❗️

One manifest per app identity

Private apps and marketplace apps use the same manifest format, but they are separate apps with separate app.id values — so each keeps its own manifest.yml in its own folder. See Marketplace Apps.

Component Properties

Component Settings by Type

Record Component:

settings:
  iconName: "task" # Icon in toolbar
  iconColor: "#7aae7f" # Hex color
  objectType: 5 # Object type (0 - for all types)
  height: "M" # Component height: S, M, L, or XL

Side Menu Component:

settings:
  iconName: "settings" # Icon in nav
  width: "M" # S, M, or L

Global Menu Component:

settings:
  displayName: "Analytics" # Menu item text

📘

See Also

Component Types for detailed settings documentation.

Multi-Component Example

An app can have multiple components:

app:
  id: "1f3a3eca-d551-4cd0-a1d7-4a1f2e431e26"
  name: "Complete App"
  description: "An app with all component types"

components:
  - type: record
    title: Record Viewer
    id: "comp-1"
    path: record-viewer/dist
    settings:
      iconName: "task"
      iconColor: "#7aae7f"
      objectType: 5
      height: "M"

  - type: side-menu
    title: Quick Actions
    id: "comp-2"
    path: quick-actions/dist
    settings:
      iconName: "lightning"
      width: "M"

  - type: global-menu
    title: Analytics
    id: "comp-3"
    path: analytics/dist
    settings:
      displayName: "Analytics"

Troubleshooting

Next Steps

• Local Development — Master the debug workflow
• SDK — Access context and data in your app
• Design System — Build UIs with Fireberry components
• Component Types — Understand component configurations