> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

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

The `itemshop` CLI ships in the [`@itemshop/sdk`](https://andcze.mintlify.site/en/developers/sdk/typescript) 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](https://andcze.mintlify.site/en/developers/agent-skills.md) (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](https://andcze.mintlify.site/en/site/agents.md). |

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

> [!NOTE]
>
> 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](https://andcze.mintlify.site/en/developers/api-keys.md).

**2. Log in**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
cd my-shop
npm install
npx itemshop dev
```

**5. Deploy**

```bash theme={null}
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](https://andcze.mintlify.site/en/site/limits.md). 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)

```yaml .github/workflows/deploy.yml theme={null}
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 }}
```

> [!WARNING]
>
> 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](https://andcze.mintlify.site/en/developers/sdk/typescript.md)**
>
> Storefront, React and the API client.

> **[Build & hosting](https://andcze.mintlify.site/en/site/build-hosting.md)**
>
> What happens after `deploy`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.