CLI

itemshop — create, run locally and deploy your shop site from the terminal.

The itemshop CLI ships in the @itemshop/sdk package (Node.js 20 or newer). You don’t need to install it globally — npx is enough. In a project that has the SDK in package.json, npx itemshop works without extra setup.

Commands

Command	What it does
itemshop login [--key <key>] [--shop <id>]	Saves an API key (and a default shop) on your computer. The key is prompted for if you don’t pass it.
itemshop logout	Removes the saved profile.
itemshop init [dir] [--template bento]	Creates a project from a template. Default bento; --repo points to another GitHub repository or a local path, --ref to a branch or tag.
itemshop dev [--port] [--host] [--locale]	Runs the site locally (the project’s Vite or a static server) with window.__ITEMSHOP__ injected and your shop’s real data.
itemshop deploy [--prod] [-m <message>] [--no-wait]	Packs the project, uploads it as a revision, builds and deploys a preview. --prod promotes the preview to production.
itemshop pull [dir] [--rev draft|<id>] [--force]	Downloads the site files (the draft by default). Refuses to overwrite a non-empty folder without --force.
itemshop skills list / skills add <id>	Catalogue and installation of agent skills (into .claude/skills/<id> by default, another folder: --dir).
itemshop mcp config --agent <agent>	Prints the MCP configuration for an agent (claude-code, codex, opencode, cursor, gemini). See Connecting agents.

Global options: --shop <id>, --api-base <url> (default https://itemshop.dev), --profile <name>, -h, -v.

The production Storefront API rejects localhost, 127.0.0.1 and [::1] as Origin and returnUrl. During itemshop dev you read shop data normally, but test a full purchase on a preview (preview-<id>.itemshop.site) or a local backend install.

A typical flow

1. Create an API key

   In the panel, under API keys, create a key with the site:read and site:write permissions. See API with a key.

2. Log in

   npx itemshop login --shop <shop-id>
   

   The key goes to ~/.config/itemshop/config.json (mode 0600; %APPDATA%\itemshop on Windows). Passing --shop verifies the key against that shop.

3. Start a project or pull an existing one

   npx itemshop init my-shop --template bento   # new, from a template
   npx itemshop pull ./my-shop                  # or the current draft from the panel
   
4. Work locally

   cd my-shop
   npm install
   npx itemshop dev
   
5. Deploy

   npx itemshop deploy            # preview (address printed in the terminal)
   npx itemshop deploy --prod     # and straight to production
   

   If the shop has no site yet, deploy creates it on the first run.

Not uploaded: node_modules, .git, .itemshop, .env and .env.*, *.log, .DS_Store and cache folders (.vite, .turbo, .cache). The rest must fit the limits. The CLI picks the shop and key in this order: flags → environment variables → the project’s .itemshop/project.json → profile.

Environment variables

Variable	Meaning
ITEMSHOP_API_KEY	API key (takes precedence over the saved profile) — for CI.
ITEMSHOP_SHOP_ID	The shop the command acts on.
ITEMSHOP_API_BASE	API address (e.g. for a self-hosted install).
ITEMSHOP_PROFILE	Profile name in the config file.
ITEMSHOP_CONFIG	Custom config file path.
ITEMSHOP_TEMPLATES_REPO, ITEMSHOP_SKILLS_REPO	Another templates or skills repository.

In CI (GitHub Actions)

.github/workflows/deploy.yml

name: Deploy shop
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @itemshop/sdk deploy --prod -m "CI ${{ github.sha }}"
        env:
          ITEMSHOP_API_KEY: ${{ secrets.ITEMSHOP_API_KEY }}
          ITEMSHOP_SHOP_ID: ${{ vars.ITEMSHOP_SHOP_ID }}

A key with site:write can replace your shop’s site. Keep it in CI secrets, never in the repository. If it leaks, revoke it in the panel.

itemshop pull and the AI editor

The AI editor and the CLI work on the same project. If you change the site in both places, run itemshop pull before working locally and deploy from the up-to-date version — otherwise you overwrite changes made in the panel (they stay in the revision history).

TypeScript SDK

Storefront, React and the API client.

Build & hosting

What happens after deploy.