CLI Command Reference

🚧
Applies to Tapcart CLI ^2.0.0 (semver caret — any 2.x release). Every command and flag on this page targets @tapcart/tapcart-cli@^2.0.0. Check your version with tapcart --version.

A scannable reference for every Tapcart CLI command, argument, and flag. For narrative walk-throughs and concepts, see the App Studio Quick Start.

Install / upgrade

npm install -g @tapcart/tapcart-cli   # install or upgrade to the latest 2.x
tapcart --version                     # verify (expect 2.x)

📘
Custom blocks and the Tapcart CLI require the Tapcart Enterprise plan.

Typical workflow

tapcart auth login
tapcart project create -a <appId> -p my-app
cd my-app
tapcart block create HelloWorld
tapcart dev block HelloWorld          # preview locally at http://localhost:4995
tapcart block push HelloWorld --live  # publish to App Studio

Global flags

Available on every command:

Flag	Alias	Description
`--verbose`	`-V`	Verbose logging
`--quiet`	`-q`	Suppress all logging
`--json`		Machine-readable JSON to stdout, suppresses other output (scripts/agents)
`--yes`	`-y`	Skip confirmation prompts (assume yes) — required for non-interactive/agent use
`--help`	`-h`	Show help for any command
`--version`		Print the CLI version

Run tapcart completion to generate a bash/zsh shell-completion script, then follow the printed instructions to load it in your shell rc file.

Auth

tapcart auth login     # log in via Auth0 in your browser
tapcart auth logout    # clear saved credentials

Project setup

Command	Description
`tapcart project create`	Scaffold a new blocks project (config, `package.json`, `blocks/`, `components/`, editor IntelliSense)
`tapcart types sync`	Write/refresh `.tapcart/types` + `jsconfig.json` so your editor gives block IntelliSense

project create flags:

Flag	Alias	Description
`--app-id`	`-a`	Your Tapcart App ID (App Studio → Settings). Prompted if omitted
`--folder-path`	`-p`	Folder to create the project in. Prompted if omitted

tapcart project create -a <appId> -p my-project
cd my-project

Dev server

tapcart dev                    # browser picker: choose a block, component, or layout
tapcart dev block <target>     # preview a block (folder name or block ID)
tapcart dev component <target> # preview a component (folder name or component ID)
tapcart dev layout <target>    # preview a layout (layout ID or screen type)

Flag	Alias	Default	Description
`--port`	`-p`	`4995`	Port to host the local dev server on

Default preview URL: http://localhost:4995. Block code hot-reloads; manifest.json / manifestConfig.json do not.

Blocks

Command	Description
`tapcart block create <folder-name>`	Scaffold a new block into `./blocks/<folder-name>`
`tapcart block pull [blocks..]`	Pull latest version(s). Targets = folder names or block IDs; omit to pick interactively
`tapcart block push [blocks..]`	Push block(s) to App Studio. Targets = folder names or block IDs; omit to pick interactively
`tapcart block versions list [block]`	List local + remote versions (interactive table)
`tapcart block versions set [block]`	Set the active (live) version

block pull flags:

Flag	Alias	Type	Description
`--all`	`-a`	boolean	Pull every block, plus any new ones not yet local
`--version`	`-v`	number	Pull a specific 1-based version (single block only)

block push flags:

Flag	Alias	Type	Description
`--all`	`-a`	boolean	Push every local block
`--live`	`-l`	boolean	Publish as live to all users (prompts to confirm; add `--yes` to skip)
`--message`	`-m`	string	Update message recorded with the push (default `Tapcart CLI push`)

block versions set flag: --version / -v (number) — version number to set as active (1-based).

tapcart block create HelloWorld
tapcart dev block HelloWorld
tapcart block pull --all
tapcart block push HelloWorld -m "Fix CTA spacing"
tapcart block push HelloWorld --live --yes
tapcart block versions set HelloWorld -v 3

📘
block push runs a non-blocking ESLint pass first — warnings print but never block the push.

Components

Same shape as blocks — swap block for component. Pushed components become global App Studio components.

Command	Description
`tapcart component create <folder-name>`	Scaffold a new component into `./components/<folder-name>`
`tapcart component pull [components..]`	Pull latest version(s); omit to pick interactively
`tapcart component push [components..]`	Push component(s); omit to pick interactively
`tapcart component versions list [component]`	List local + remote versions
`tapcart component versions set [component]`	Set the active (live) version

Flags mirror blocks:

component pull: --all / -a, --version / -v <n> (1-based)
component push: --all / -a, --live / -l, --message / -m <msg>
component versions set: --version / -v <n> (1-based)

tapcart component create ProductCard
tapcart dev component ProductCard
tapcart component pull --all
tapcart component push ProductCard --live --yes

Dependencies

Command	Description
`tapcart dependency add <name> <version>`	Add a dependency to `tapcart.config.json` (validated against esm.sh)
`tapcart dependency remove <name>`	Remove a dependency locally
`tapcart dependency list`	List locally configured dependencies
`tapcart dependency push`	Push local dependency config to the app
`tapcart dependency pull`	Pull remote dependency config, overwriting local

dependency add flag: --force / -f — overwrite an existing dependency without prompting.

tapcart dependency add lodash 4.17.21
tapcart dependency push

Layouts

Author and preview local mock layouts under .tapcart/layouts.

Command	Description
`tapcart layout new <name>`	Create a new local layout
`tapcart layout add <use>`	Add a local block/component (by folder name) to a layout
`tapcart layout set <name> <handle> <key=value..>`	Set manifestConfig values on a block (dotted keys allowed)
`tapcart layout reorder <name> <from> <to>`	Move a block from one index to another
`tapcart layout remove <name> <handle>`	Remove a block by index or `as` handle
`tapcart layout tab add\|remove\|rename <name> ...`	Manage tabs on a tabbed layout
`tapcart layout list`	List local layouts
`tapcart layout show <name>`	Print a layout file
`tapcart layout validate [name]`	Validate one or all layouts against the schema + local folders

layout new flag: --tabbed — create a tabbed (tabbed-list) layout
layout add flags: --layout <name> (required if >1 layout exists), --tab <title>, --pos <i> (insert index, default end), --as <handle> (stable instance handle), --config <json> (partial manifestConfig)
layout set / reorder / remove accept --tab <title>
All layout commands accept --json

tapcart layout new home
tapcart layout add ProductGrid --layout home --as grid
tapcart layout set home grid columns=2 card.showPrice=true
tapcart dev layout home
tapcart layout validate home

Linting

tapcart lint [targets..]

Flag	Alias	Description
`--all`		Lint every block and component
`--fix`		Auto-fix problems
`--blocks`	`-b`	Block paths/folder names to lint (accepts multiple)
`--components`	`-c`	Component paths/folder names to lint (accepts multiple)

Targets are block or component folder names (the CLI checks ./blocks/<name> then ./components/<name>). Omit targets and flags to pick interactively. --all cannot be combined with explicit targets.

tapcart lint --all
tapcart lint HelloWorld --fix

Logs

tapcart log show        # last 100 lines of ~/.tapcart/cli.log
tapcart log show -n 20  # last 20 lines

log show flag: --number / -n <n> (default 100).

MCP server

tapcart mcp   # start the Tapcart MCP server over stdio for AI clients (Cursor, Windsurf, etc.)