Tapcart CLI

The Tapcart CLI is a command-line interface for managing and developing blocks.

MCP (Model Context Protocol)

The Tapcart CLI includes an MCP server intended for AI clients (Cursor, Windsurf, etc.) that can call Tapcart CLI functionality via task-first tools.

Running the MCP server

Run the MCP server over stdio:

tapcart mcp

Notes:

• The MCP server is long-running and keeps the terminal busy until you stop it (Ctrl+C).
• The MCP server runs in the context of the current working directory. When using MCP tools, pass projectPath when you need to target a specific Tapcart project.

AI client configuration example

When configuring an AI client to launch this MCP server, you generally want the command to be tapcart with args mcp, and set environment variables explicitly:

{
  "command": "tapcart",
  "args": ["mcp"],
  "env": {
    "TAPCART_ENV": "production"
  }
}

Environment defaults

The MCP server (and CLI) use TAPCART_ENV to determine which Tapcart environment to target.

Recommended default:

export TAPCART_ENV=production

Safety guardrails for remote writes

Tools that perform remote writes use a single toggle:

• mode: "plan" | "apply"

Behavior:

• mode="plan" (default): no remote mutations occur. The tool returns what it would do.
• mode="apply": the tool performs the remote write.

Long-running / interactive CLI workflows

Some workflows are interactive or start a dev server. The MCP server exposes instruction-only tools that return exact terminal commands instead of spawning processes:

• tapcart_blocks_dev_instructions
• tapcart_components_dev_instructions
• tapcart_layout_dev_instructions

MCP tool index

Project & auth

• tapcart_project_info (read)
• tapcart_auth_status (read)
• tapcart_auth_login_instructions (instructions)
• tapcart_auth_logout (local-write)

Local development helpers

• tapcart_blocks_createLocal (local-write)
• tapcart_components_createLocal (local-write)
• tapcart_log_show (read)
• tapcart_lint (read; if fix=true then local-write gated by mode)

Blocks

• tapcart_blocks_listRemote (read)
• tapcart_blocks_pull (read + local-write)
• tapcart_blocks_push (remote-write gated by mode)
• tapcart_block_versions_list (read)
• tapcart_block_versions_set (remote-write gated by mode)

Components

• tapcart_components_listRemote (read)
• tapcart_components_pull (read + local-write)
• tapcart_components_push (remote-write gated by mode)
• tapcart_component_versions_list (read)
• tapcart_component_versions_set (remote-write gated by mode)

Dependencies

• tapcart_dependencies_listLocal (read)
• tapcart_dependencies_addLocal (local-write)
• tapcart_dependencies_removeLocal (local-write)
• tapcart_dependencies_pullRemote (read + local-write)
• tapcart_dependencies_pushRemote (remote-write gated by mode)

MCP recipes

Recipe: first-time setup

1. tapcart_project_info (confirm tapcartEnv, apiBaseUrl, appId)

2. If not authenticated: tapcart_auth_login_instructions then run the command in a terminal

3. Pull your blocks locally:

• tapcart_blocks_pull with all=true

Recipe: edit a block and publish safely

1. Pull the latest version of a block:

• tapcart_blocks_pull with labels=["MyBlock"]

2. Edit local files under ./blocks/<block>/ (e.g. code.jsx)

3. Plan a push:

• tapcart_blocks_push with labels=["MyBlock"] and mode="plan"

4. Apply the push:

• tapcart_blocks_push with labels=["MyBlock"] and mode="apply"

5. (Optional) Set a specific version live:

• tapcart_block_versions_set with label="MyBlock", version=<n>, mode="plan" then mode="apply"

Recipe: update dependencies

1. Add locally:

• tapcart_dependencies_addLocal with name, version

2. Plan remote push:

• tapcart_dependencies_pushRemote with mode="plan"

3. Apply remote push:

• tapcart_dependencies_pushRemote with mode="apply"

Get started developing Blocks

1. Create your project

cd ~/Desktop # or anywhere on your device
npm init @tapcart/tapcart-app@latest [-- -a <application_id> -f <project_name>]

• Project name: Give it a name, like my-test-store
• Application ID: This is found in the Tapcart Dashboard, on the Setting page, under the "Tapcart CLI API Key" section

This will create a new Tapcart project in a folder named my-test-store (or whatever you named it). The project consists of:

my-test-store/
 |--- .tapcart.config.json # This is where the Tapcart CLI stores its configuration
 |--- blocks/ # This is where your blocks will be stored
 |--- components/ # This is where your global components will be stored
 |--- package.json # This is the package file for your project
 |--- yarn.lock # This is the lock file for your project

2. Install Dependencies

Navigate into your project directory:

cd my-test-store
yarn || npm install

3. Authenticate with the Tapcart CLI

You must authenticate with the Tapcart CLI before you can use it. You can do this by running the following command:

yarn tapcart auth login

This will open a browser window where you can log in to your Tapcart account. After logging in, the CLI will store your authentication token locally, allowing you to use the CLI commands without needing to log in again.

4. (Optional) Pull down existing blocks

Now pull down the blocks

yarn tapcart block pull -a

You'll see all your blocks pulled down into new folders. In them, you'll see the following files:

MyBlock/
 |--- code.jsx
 |--- config.json
 |--- manifest.json
 |--- manifestConfig.json
 |--- mockData.json

• code.jsx: This is the React component code for the block
• config.json: This holds high-level metadata about the block, such as its label and tags. Each block's label is its unique identifier. Supported fields are: label, tags, dependencies.
• manifest.json: This holds core config elements for the block, such as configurable CSS elements. This data will be available in the right rail in the dashboard.
• manifestConfig.json: This holds information about which manifest options are selected.
• mockData.json: This is a JSON file that contains mock data for the block. This will be used when developing the block locally. You should add mock data to this file in a structure that matches our documented app variables.

5. Create a new block

yarn tapcart block create HelloWorld

6. Run the new block (or an existing block that was pulled down)

yarn tapcart block dev -b HelloWorld

This will open http://localhost:4995 by default

Make changes to the block in code.jsx and observe the changes in your browser in real time.

Importing Software Dependencies

You can import software dependencies into your block. This is done by adding the dependencies to your project via tapcart dependency add command. For example:

yarn tapcart dependency add lodash 4.17.21

This will add the lodash library to your app's dependencies. You must specify which blocks you want to add the dependency to. This is done by editing the block's config.json file.

{
  "dependencies": ["lodash"]
}

Then, you can import the dependency in your block's code.jsx file:

import * as _ from 'lodash';

Note: The Tapcart ecosystem does not support React component libraries like @mui/material. For UI components, you should use the Tapcart component library.

Pushing Dependencies

You must push your dependencies to your application configuration before they will work in the dashboard or the mobile app. You can do this by running:

yarn tapcart dependency push

This will push the dependencies to your application configuration.

7. Push the block to your block bank

When you're satisfied with your changes, push the block to your block bank. Then head over to the dashboard where you'll be able to see it.

yarn tapcart block push -b HelloWorld

Pushing your block by default does not make it live. You'll need set the version as live after pushing, or use the --live flag when pushing.

tapcart block versions list -b HelloWorld
✔ Block versions:
┌─────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 679d443708d1e5fa9938651a │ active       │ -            │
└─────────┴──────────────────────────┴──────────────┴──────────────┘

tapcart block versions set -b HelloWorld -v 1
✔ Block version set to 1
┌─────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 679d443708d1e5fa9938651a │ active       │ live         │
└─────────┴──────────────────────────┴──────────────┴──────────────┘

Or, to do it all in one step:

tapcart block push -b HelloWorld --live

[!WARNING] Running push --live will create a new version of the block and set it as live. If you push without the --live flag, it is recommended to set the version as live via block versions command to avoid creating duplicate versions.

Working with Global Components

Global components are reusable React components that can be shared across multiple blocks. The Tapcart CLI provides commands to create, develop, push, and pull global components.

Creating a Component

Create a new global component:

tapcart component create ProductCard

This will create a new component in the components directory with the following structure:

components/ProductCard/
 |--- code.jsx
 |--- config.json
 |--- manifest.json
 |--- manifestConfig.json
 |--- mockData.json

Developing a Component

Run a local development server for your component:

yarn tapcart component dev -c ProductCard

This will start a development server where you can preview and test your component with hot-reloading.

Pushing Components

Push your component to the Tapcart dashboard:

yarn tapcart component push -c ProductCard

You can also push multiple components at once:

yarn tapcart component push -c ProductCard Button

Or push all components:

yarn tapcart component push -a

Pulling Components

Pull down the latest version of a component:

yarn tapcart component pull ProductCard

Pull a specific version of a component:

yarn tapcart component pull -c ProductCard --version 2

Pull multiple components:

yarn tapcart component pull -c ProductCard Button

Or pull all components:

yarn tapcart component pull -a

Managing Component Versions

The component versions command has the same structure as the block versions command:

# List all versions of a component
tapcart component versions list -c MyComponent

# Set a specific version as the active version on the server
yarn tapcart component versions set -c MyComponent -v 2

# Set a specific version as the active version locally without changing the server
yarn tapcart component pull -c MyComponent --version 1

Note that the version index is 1-based, so set MyComponent 1 sets the first version as active.

When listing component versions, you'll see both the local version (marked as "active" in the LocalVersion column) and the remote version (marked as "live" in the RemoteVersion column).

Layouts

Layouts are collection of blocks that create a page - for example your home page. You can develop blocks in a layout context using the Tapcart CLI. You can spin up the layout development server with the following command:

yarn tapcart layout dev

yarn tapcart layout dev -s home #layout types are documented in the CLI help menu
yarn tapcart layout dev home -b HelloWorld # Spins up the home layout development server using local HelloWorld block
yarn tapcart layout dev home --all # Spins up the home layout development server using all local blocks

By default, the dev server will render the layout with the server version of blocks. If you want to use the local versions, you can pass the --all|-a flag to override all blocks, or --block=BlockFolder to override a specific block.

Help

Open the help menu for any command with the -h (or --help) option.

# Examples
yarn tapcart -h
yarn tapcart block -h
yarn tapcart component -h
yarn tapcart layout -h

CLI Version

See your version of the Tapcart CLI.

# Example
yarn tapcart -v # shorthand for --version