CLI

itemshop — twórz, uruchamiaj lokalnie i wdrażaj stronę sklepu z terminala.

CLI itemshop jest częścią pakietu @itemshop/sdk (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 (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.

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

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.

2. Zaloguj się

   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

   npx itemshop init moj-sklep --template bento   # nowy z szablonu
   npx itemshop pull ./moj-sklep                  # albo aktualny szkic z panelu
   
4. Pracuj lokalnie

   cd moj-sklep
   npm install
   npx itemshop dev
   
5. Wdróż

   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. 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)

.github/workflows/deploy.yml

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 }}

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

Storefront, React i klient API.

Build i hosting

Co dzieje się po deploy.