Komendy CLI — Referencja

Pełna lista poleceń dostępnych w DoSwiftly CLI (@doswiftly/cli) dla dewelopera storefrontu.

Generowane ze źródła

Ta referencja jest generowana bezpośrednio z drzewa komend @doswiftly/cli — komendy, flagi, argumenty i ich opisy nie mogą się rozjechać z faktyczną implementacją CLI. Koncepcyjny przewodnik (instalacja, tryby init, priorytet adresu API, workflow wdrażania) znajdziesz w Przeglądzie CLI.

Język opisów

Opisy komend i flag pochodzą wprost z doswiftly --help i są w języku angielskim — to wspólne źródło prawdy dla terminala, pakietu npm i tej referencji (gwarancja braku rozjazdu, analogicznie do referencji typów GraphQL). Przewodniki koncepcyjne w portalu pozostają po polsku.

Audience

Tag	Odbiorca
🛒	Deweloper storefrontu — buduje sklepy, używa CLI do `init` / `dev` / `deploy` / `preview`
🔧	Deweloper szablonów — zarządza rejestrem szablonów platformy

Poniższa referencja obejmuje wyłącznie komendy 🛒.

Komendy domyślne

Niektóre grupy mają komendę domyślną (oznaczoną w referencji jako domyślna komenda): doswiftly deploy ≡ doswiftly deploy run, doswiftly preview ≡ doswiftly preview create, doswiftly migrate ≡ doswiftly migrate check.

Flagi globalne

Dostępne dla każdego polecenia CLI.

Flaga	Opis
`-v, --version`	Output the current version
`--verbose`	Enable verbose output
`--quiet`	Suppress non-error output

Inicjalizacja

doswiftly init

Initialize a new DoSwiftly project

doswiftly init [options] [name]

Argument	Wymagany
`[name]`	Nie

Flaga	Opis
`-p, --project-id <id>`	DoSwiftly project ID
`-t, --template <template>`	Project template
`--pm <manager>`	Package manager to use (pnpm, npm, yarn, bun)
`-l, --language <language>`	Language (TypeScript or JavaScript)
`--styling <library>`	Styling library (Tailwind v4, Tailwind v3, CSS Modules, None)
`--ui-library <library>`	UI library (shadcn/ui, Radix UI, Headless UI, None)
`--dry-run`	Show what would be created without making changes
`--no-remote`	Use only local templates (skip API)
`--create-template`	Create a new template project for the registry (SaaS developer)

Kontekst

doswiftly whoami

Show current user, project, and environment info

doswiftly whoami

Uwierzytelnianie

doswiftly auth github

Connect GitHub account via device flow

doswiftly auth github

doswiftly auth login

doswiftly auth login [options]

Flaga	Opis
`-p, --profile <name>`	Target profile (default: active profile)

doswiftly auth logout

Logout from DoSwiftly (clears active profile)

doswiftly auth logout [options]

Flaga	Opis
`-p, --profile <name>`	Target profile (default: active profile)

doswiftly auth token

Generate a deploy token for CI/CD

doswiftly auth token [options]

Flaga	Opis
`--deploy`	Generate a deploy-scoped token

Rozwój

doswiftly dev

Start development server

doswiftly dev [options]

Flaga	Domyślnie	Opis
`-p, --port <port>`	—	Port number (default: 3000)
`-H, --host <host>`	`localhost`	Hostname
`--strict-port`	—	Fail if port is already in use instead of auto-fallback
`--no-open`	—	Do not open browser

Konfiguracja

doswiftly config domain add

Add a custom domain to the shop

doswiftly config domain add <hostname>

Argument	Wymagany
`<hostname>`	Tak

doswiftly config domain list

List all custom domains with status

doswiftly config domain list

doswiftly config domain remove

Remove a custom domain from the shop

doswiftly config domain remove <hostname>

Argument	Wymagany
`<hostname>`	Tak

Aktualizacja CLI

doswiftly update

Check for CLI updates

doswiftly update

Środowiska

doswiftly env add

Add a new environment profile

doswiftly env add [name]

Argument	Wymagany
`[name]`	Nie

doswiftly env delete

Delete an environment profile

doswiftly env delete [name]

Argument	Wymagany
`[name]`	Nie

doswiftly env generate

Generate .env.local from active profile

doswiftly env generate

doswiftly env list

List all environment profiles

doswiftly env list

doswiftly env set

Set a custom environment variable on the active profile

doswiftly env set <key> <value>

Argument	Wymagany
`<key>`	Tak
`<value>`	Tak

doswiftly env use

Switch to a different environment profile

doswiftly env use [name]

Argument	Wymagany
`[name]`	Nie

Diagnostyka

doswiftly verify

Verify API connectivity and configuration

doswiftly verify

doswiftly doctor

Check CLI and project health

doswiftly doctor

doswiftly check

Run linting, type checking, and validation

doswiftly check

SDK

doswiftly sdk version

Check Storefront SDK version

doswiftly sdk version

Wdrażanie

doswiftly deploy logs

View deployment logs

doswiftly deploy logs <deploymentId>

Argument	Wymagany
`<deploymentId>`	Tak

doswiftly deploy rollback

Rollback to previous deployment

doswiftly deploy rollback [deploymentId]

Argument	Wymagany
`[deploymentId]`	Nie

doswiftly deploy rundomyślna komenda

Deploy storefront to Cloudflare Workers

doswiftly deploy run [options]

Flaga	Domyślnie	Opis
`--type <type>`	`PRODUCTION`	Deployment type (PRODUCTION, PREVIEW, STAGING)
`--provider <provider>`	—	Cloud provider deprecated
`--branch <branch>`	—	Git branch to deploy
`--message <message>`	—	Deployment message

doswiftly deploy status

Check deployment status

doswiftly deploy status [deploymentId]

Argument	Wymagany
`[deploymentId]`	Nie

doswiftly deploy validate

Validate project before deployment (no install required)

doswiftly deploy validate

codegen

doswiftly codegen initdomyślna komenda

Scaffold codegen config and install required dev dependencies

doswiftly codegen init

Środowiska podglądu

doswiftly preview createdomyślna komenda

Create a preview deployment

doswiftly preview create [options]

Flaga	Domyślnie	Opis
`--branch <branch>`	—	Git branch to preview
`--ttl <hours>`	`168`	Time to live in hours (default: 168 / 7 days)

doswiftly preview list

List all preview deployments

doswiftly preview list

doswiftly preview logs

View preview build logs

doswiftly preview logs <previewId>

Argument	Wymagany
`<previewId>`	Tak

doswiftly preview open

Open preview URL in browser

doswiftly preview open <previewId>

Argument	Wymagany
`<previewId>`	Tak

doswiftly preview stop

Stop a preview deployment

doswiftly preview stop <previewId>

Argument	Wymagany
`<previewId>`	Tak

Szablony

doswiftly template info

Show template details

doswiftly template info <name>

Argument	Wymagany
`<name>`	Tak

doswiftly template list

List available templates

doswiftly template list

Narzędzia

doswiftly inspect

Make a test request to an API endpoint

doswiftly inspect [options] <endpoint>

Argument	Wymagany
`<endpoint>`	Tak

Flaga	Domyślnie	Opis
`-X, --method <method>`	`GET`	HTTP method
`-H, --header <header...>`	—	Request headers (key:value format)
`-d, --body <body>`	—	Request body (JSON)
`-v, --verbose`	—	Show full request/response details

doswiftly proxy

Start a local proxy server for API debugging

doswiftly proxy [options]

Flaga	Domyślnie	Opis
`-p, --port <port>`	`3001`	Proxy server port

Migracje szablonów

doswiftly migrate apply

Apply pending template updates

doswiftly migrate apply [options]

Flaga	Opis
`--dry-run`	Show what would be changed without applying
`--force`	Continue on errors

doswiftly migrate checkdomyślna komenda

Check for template updates

doswiftly migrate check

doswiftly migrate diff

Show differences between local project and template

doswiftly migrate diff

doswiftly upgrade

Check for and apply template updates

doswiftly upgrade [options]

Flaga	Opis
`--check`	Only check for updates (do not apply)
`--dry-run`	Show what would be changed without applying
`--force`	Apply updates without confirmation, continue on errors
`--diff`	Show differences between local project and template

Troubleshooting — kody błędów deploymentu

Gdy doswiftly deploy run zwróci kod błędu (lub doswiftly deploy status <id> pokaże errorCode na rekordzie), użyj poniższej tabeli do interpretacji. Pole errorMessage na deploymencie zawiera szczegółowy kontekst (request id, klasa wyjątku, parametry) — pobierzesz go zawsze przez doswiftly deploy status <id>.

Kod	Etap	HTTP	Znaczenie	Co zrobić
`MANIFEST_ERROR`	3 (`PUT /:id/manifest`)	500	Catch-all dla nie-walidacyjnego błędu przy zapisie manifestu (DB, kolizja statusu, runtime). Nie dotyczy złej treści manifestu — treść jest walidowana upfront i zwraca 400 bez statusu FAILED	`doswiftly deploy status <id>` → przeczytaj `errorMessage`. Jeśli powtarzalne — zgłoś z `deployId`
`UPLOAD_ERROR`	4 (upload artefaktu)	500	Niepowodzenie przy przetwarzaniu artefaktu (rozpakowanie archiwum, walidacja bundla Workera, zapis assetów). Przetwarzanie biegnie w tle po przyjęciu artefaktu, więc błąd może pojawić się już po zakończeniu wysyłki	`doswiftly deploy status <id>`. Czasami transient — spróbuj ponownie. Jeśli powtarzalne — zgłoś z `deployId`
`STORAGE_LIMIT_EXCEEDED`	4 (upload artefaktu)	402	Przekroczono limit przestrzeni dyskowej planu	Upgrade planu lub zwolnij miejsce, następnie retry
`ARTIFACT_TOO_LARGE`	4 (upload artefaktu)	413	Artefakt buildu przekracza limit rozmiaru ustawiony przez platformę — sprawdzany dwukrotnie: przed wysyłką (rozmiar zadeklarowany) i po niej (rozmiar rzeczywisty)	Sprawdź zawartość katalogu buildu — najczęstsze przyczyny to duże pliki statyczne (`public/*.mp4`, niezoptymalizowane obrazy) lub zależności deweloperskie wciągnięte do bundla
`WORKER_SIZE_LIMIT`	5 (`POST :id/deploy`)	422	Skrypt workera przekracza limit Cloudflare (10 MB compressed)	Sprawdź `node_modules` w bundle — `external` w `wrangler.toml` lub `serverComponentsExternalPackages` w Next.js config
`CF_API_ERROR`	5 (`POST /:id/deploy`)	502	Błąd od Cloudflare API podczas tworzenia/aktualizacji workera	Transient — retry. Jeśli powtarzalne — sprawdź Cloudflare status page i zgłoś
`CF_RATE_LIMIT`	5 (`POST /:id/deploy`)	429	Cloudflare rate limit	Poczekaj 60-120 s i retry
`BUILD_TIMEOUT`	2 (`build` step CI)	504	Build trwał dłużej niż dozwolony window	Zoptymalizuj build (cache, parallel, bundler config) — dla `pnpm install` rozważ `--prefer-offline`
`BUILD_FAILED`	2 (`build` step CI)	422	Build zwrócił non-zero exit code	Sprawdź logi w GitHub Actions — typowe: brakujące env, missing types, TS errors
`DOMAIN_CONFLICT`	konfiguracja	409	Domena jest już przypisana do innego sklepu	Wymaga manualnej deatachacji — zgłoś z nazwą domeny
`DOMAIN_VERIFICATION_FAILED`	konfiguracja	422	Weryfikacja domeny (DNS / TXT record) nie powiodła się	Sprawdź wpisy DNS, poczekaj na propagację (do 24 h), retry
`PREVIEW_LIMIT`	przy preview deploy	429	Aktywnych preview deploymentów > limit planu	Zatrzymaj stare preview (`doswiftly preview stop <previewId>`) lub upgrade planu
`DEPLOYMENT_IN_PROGRESS`	nowy deploy	409	Inny deployment trwa dla tego sklepu	Poczekaj na zakończenie poprzedniego (`doswiftly deploy status`) — auto-cancel po 30 min stale window
`STALE_TIMEOUT`	auto-cancel	408	Deployment utknął w `PENDING/BUILDING/UPLOADING` powyżej 30 min i został automatycznie oznaczony jako FAILED	Najczęściej: payload zbyt duży, CLI crash, network drop. Stwórz nowy deploy

Diagnostyka

# Pełne info o deploymencie (w tym errorMessage)
doswiftly deploy status <deployId>

# Logi z CI (deploy.yml)
gh run view <run-id> --log

Jeśli errorCode to MANIFEST_ERROR lub UPLOAD_ERROR, a errorMessage nie wskazuje konkretnej przyczyny — zgłoś issue z deployId, wersją CLI (doswiftly --version) i fragmentem logu z GitHub Actions.

Wersja Node w GitHub Actions

Jeśli widzisz w logach Wrangler requires at least Node.js v22.0.0 — workflow w starszych projektach pinują node-version: 20. Edytuj .github/workflows/deploy.yml, zmień node-version: 20 na 22 i scommituj. Nowsze projekty są generowane już z node: 22.

Publikacja trusted documents nie powiodła się

Ten błąd występuje przed utworzeniem rekordu wdrożenia — doswiftly deploy status nie znajdzie dla niego deployId (jeszcze nie istnieje). CLI zawsze kończy nieudany krok komunikatem Deployment failed z treścią błędu i sugestią uruchomienia doswiftly deploy status, ale przy tej konkretnej awarii ta sugestia nic nie pokaże — sprawdzaj bezpośrednio komunikat w terminalu (lokalnie) albo w logu joba w GitHub Actions.

Dzieje się to na etapie publikacji trusted documents — zaraz po codegenie, zanim ruszy build. Manifest nieobecny (projekt bez skonfigurowanego codegenu) → krok jest cicho pomijany, to nie jest ten błąd. Manifest obecny, ale publikacja się nie udaje → deploy przerywa się natychmiast.

Typowe przyczyny:

Przyczyna	Co zrobić
Przejściowy błąd sieci lub API chwilowo niedostępne	Ponów `doswiftly deploy run`
Wygasły lub nieprawidłowy token deploy	Wygeneruj nowy: `doswiftly auth token --deploy`
Manifest przekracza limity publikacji (liczba operacji lub rozmiar pojedynczego zapytania)	Rzadkie w typowym projekcie — sprawdź, czy operacje nie generują nietypowo dużych zapytań

Wcześniej ten sam problem objawiał się dopiero w trakcie builda

Jeśli w starszych wdrożeniach widziałeś błąd budowania z NETWORK_ERROR albo komunikatem parsowania w stylu Unexpected token '<' podczas renderowania stron statycznych (SSG) — to był objaw dokładnie tego samego niezarejestrowanego documentId: strona odpytywała o zapytanie, którego API jeszcze nie znało, i w odpowiedzi dostawała stronę HTML zamiast danych JSON. Rejestracja manifestu przed buildem eliminuje ten scenariusz — awaria jest teraz widoczna od razu, zanim zacznie się kosztowny build, z jasnym komunikatem zamiast kryptycznego błędu parsowania w połowie renderowania.

Wysyłka artefaktu kończy się błędem 413

Objaw: deploy przerywa się na kroku Uploading artifact..., w logu widać odpowiedź HTTP 413 (Request Entity Too Large), a rekord wdrożenia zostaje w stanie UPLOADING albo FAILED. Zwykle pojawia się przy pierwszym naprawdę kompletnym buildzie — im większy katalog sklepu, tym większe archiwum.

Przyczyna: starsza wersja CLI wysyła artefakt buildu przez API, więc żądanie podlega limitom wielkości ciała po drodze. Aktualne CLI wysyła archiwum bezpośrednio do magazynu platformy pod podpisanym adresem i tych limitów nie dotyka — decyduje o tym platforma, a CLI przełącza tor automatycznie.

Co zrobić:

Zaktualizuj CLI do najnowszej wersji: npm i -g @doswiftly/cli@latest (lub pnpm add -g / yarn global add). Workflow generowany przez platformę wywołuje npx @doswiftly/cli@latest, więc wdrożenia z GitHub Actions dostają nowy tor bez żadnej zmiany w repozytorium.
Ponów doswiftly deploy run.
Jeśli po aktualizacji dostajesz ARTIFACT_TOO_LARGE zamiast 413 — to już limit rozmiaru artefaktu po stronie platformy, nie limit żądania. Odchudź build (duże pliki w katalogu publicznym, niezoptymalizowane obrazy, zależności deweloperskie w bundlu) albo skontaktuj się ze wsparciem w sprawie podniesienia limitu dla Twojego sklepu.

Zobacz także

Przegląd CLI — instalacja, tryby init, środowiska i workflow wdrażania
Codegen i odczyty cacheowane na brzegu — trusted documents, doswiftly codegen init

Audience​

Inicjalizacja

Kontekst

Uwierzytelnianie

Rozwój

Konfiguracja

Aktualizacja CLI

Środowiska

Diagnostyka

SDK

Wdrażanie

codegen

Środowiska podglądu

Szablony

Narzędzia

Migracje szablonów

Troubleshooting — kody błędów deploymentu​

Diagnostyka​

Publikacja trusted documents nie powiodła się​

Wysyłka artefaktu kończy się błędem 413​

Zobacz także​

Audience

Troubleshooting — kody błędów deploymentu

Diagnostyka

Publikacja trusted documents nie powiodła się

Wysyłka artefaktu kończy się błędem 413

Zobacz także