> ## 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 — twórz, uruchamiaj lokalnie i wdrażaj stronę sklepu z terminala.

CLI `itemshop` jest częścią pakietu [`@itemshop/sdk`](https://andcze.mintlify.site/pl/developers/sdk/typescript) (Node.js 20 lub nowszy). Nie musisz go instalować globalnie — wystarczy `npx`. W projekcie z SDK w `package.json` działa też `npx itemshop` bez dodatkowej konfiguracji.

## Komendy

| Komenda | Co robi |
| - | - |
| `itemshop login [--key <klucz>] [--shop <id>]` | Zapisuje klucz API (i domyślny sklep) na Twoim komputerze. Klucz jest pytany interaktywnie, gdy go nie podasz. |
| `itemshop logout` | Usuwa zapisany profil. |
| `itemshop init [katalog] [--template bento]` | Tworzy projekt z szablonu. Domyślnie `bento`; `--repo` wskazuje inne repozytorium GitHub lub lokalną ścieżkę, `--ref` gałąź lub tag. |
| `itemshop dev [--port] [--host] [--locale]` | Uruchamia stronę lokalnie (Vite projektu albo serwer statyczny) z wstrzykniętym `window.__ITEMSHOP__` i prawdziwymi danymi Twojego sklepu. |
| `itemshop deploy [--prod] [-m <opis>] [--no-wait]` | Pakuje projekt, wgrywa go jako rewizję, buduje i wdraża podgląd. `--prod` promuje podgląd na produkcję. |
| `itemshop pull [katalog] [--rev draft\|<id>] [--force]` | Pobiera pliki strony (domyślnie szkic). Odmawia nadpisania niepustego katalogu bez `--force`. |
| `itemshop skills list` / `skills add <id>` | Katalog i instalacja [skilli agentowych](https://andcze.mintlify.site/pl/developers/agent-skills.md) (domyślnie do `.claude/skills/<id>`, inny katalog: `--dir`). |
| `itemshop mcp config --agent <agent>` | Wypisuje konfigurację MCP dla agenta (`claude-code`, `codex`, `opencode`, `cursor`, `gemini`). Zobacz [Podłączanie agentów](https://andcze.mintlify.site/pl/site/agents.md). |

Opcje globalne: `--shop <id>`, `--api-base <url>` (domyślnie `https://itemshop.dev`), `--profile <nazwa>`, `-h`, `-v`.

> [!NOTE]
>
> Produkcyjne Storefront API odrzuca adresy `localhost`, `127.0.0.1` i `[::1]` jako `Origin` i `returnUrl`. Podczas `itemshop dev` dane sklepu czytasz normalnie, ale pełny zakup przetestuj na podglądzie (`preview-<id>.itemshop.site`) albo na lokalnej instalacji backendu.

## Typowy przebieg

**1. Utwórz klucz API**

W panelu, w sekcji **Klucze API**, utwórz klucz z uprawnieniami `site:read` i `site:write`. Zobacz [API z kluczem](https://andcze.mintlify.site/pl/developers/api-keys.md).

**2. Zaloguj się**

```bash theme={null}
npx itemshop login --shop <id-sklepu>
```

Klucz trafia do `~/.config/itemshop/config.json` (prawa `0600`; w Windows `%APPDATA%\itemshop`). Podanie `--shop` sprawdza klucz na tym sklepie.

**3. Zacznij projekt albo pobierz istniejący**

```bash theme={null}
npx itemshop init moj-sklep --template bento   # nowy z szablonu
npx itemshop pull ./moj-sklep                  # albo aktualny szkic z panelu
```

**4. Pracuj lokalnie**

```bash theme={null}
cd moj-sklep
npm install
npx itemshop dev
```

**5. Wdróż**

```bash theme={null}
npx itemshop deploy            # podgląd (adres wypisany w terminalu)
npx itemshop deploy --prod     # i od razu na produkcję
```

Jeśli sklep nie ma jeszcze strony, `deploy` tworzy ją przy pierwszym wywołaniu.

Do wysyłki nie trafiają: `node_modules`, `.git`, `.itemshop`, `.env` i `.env.*`, `*.log`, `.DS_Store` i katalogi cache (`.vite`, `.turbo`, `.cache`). Reszta musi się zmieścić w [limitach](https://andcze.mintlify.site/pl/site/limits.md). Które sklep i klucz są używane, CLI ustala w kolejności: flagi → zmienne środowiskowe → plik `.itemshop/project.json` projektu → profil.

## Zmienne środowiskowe

| Zmienna | Znaczenie |
| - | - |
| `ITEMSHOP_API_KEY` | Klucz API (ma pierwszeństwo przed zapisanym profilem) — do CI. |
| `ITEMSHOP_SHOP_ID` | Sklep, na którym działa komenda. |
| `ITEMSHOP_API_BASE` | Adres API (np. dla własnej instalacji). |
| `ITEMSHOP_PROFILE` | Nazwa profilu w pliku konfiguracji. |
| `ITEMSHOP_CONFIG` | Własna ścieżka pliku konfiguracji. |
| `ITEMSHOP_TEMPLATES_REPO`, `ITEMSHOP_SKILLS_REPO` | Inne repozytorium szablonów lub skilli. |

## W CI (GitHub Actions)

```yaml .github/workflows/deploy.yml theme={null}
name: Deploy sklepu
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]
>
> Klucz z `site:write` może podmienić stronę sklepu. Trzymaj go w sekretach CI, nigdy w repozytorium. W razie wycieku unieważnij go w panelu.

## `itemshop pull` a AI edytor

AI edytor i CLI pracują na tym samym projekcie. Jeśli zmieniasz stronę w obu miejscach, przed pracą lokalną zrób `itemshop pull`, a `deploy` wykonuj z aktualnej wersji — inaczej nadpiszesz zmiany zrobione w panelu (zostaną w historii rewizji).

> **[SDK TypeScript](https://andcze.mintlify.site/pl/developers/sdk/typescript.md)**
>
> Storefront, React i klient API.

> **[Build i hosting](https://andcze.mintlify.site/pl/site/build-hosting.md)**
>
> Co dzieje się po `deploy`.


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