Saplo CLI

Oficjalne narzędzie wiersza poleceń Saplo. Instalujesz raz, deployujesz wielokrotnie - z terminala, skryptów CI/CD lub potoku GitHub Actions.

Instalacja

Wymagany Node.js 18+.

$ npm install -g @saplo/cli

Sprawdź wersję po instalacji:

$ saplo --version

Logowanie

Przed pierwszym użyciem uwierzytelnij się tokenem API:

$ saplo login

CLI wyświetli adres https://panel.saplo.pl/cli-auth - otwórz go w przeglądarce, zaloguj się i skopiuj token. Wklej go do terminala po prompcie.

Możesz też podać token bezpośrednio (tryb nieinteraktywny, CI):

$ saplo login --token saplo_live_abc123

Token jest zapisywany do ~/.saplo/config.json (chmod 600).

Szybki start

Trzy komendy wystarczają do pierwszego deployu:

# 1. Wejdź do katalogu projektu i wygeneruj saplo.yaml
$ cd moj-projekt
$ saplo init

# 2. (opcjonalnie) podlinkuj do istniejącej aplikacji w panelu
$ saplo link

# 3. Wdróż
$ saplo deploy

saplo init sam wykrywa stack na podstawie plików w katalogu i generuje gotowy saplo.yaml. Jeśli nie podlinkujesz wcześniej aplikacji, saplo deploy automatycznie wyszuka aplikację o podanej nazwie lub utworzy nową - bez ręcznego klikania w panelu.

Autodetekcja stacka

Komenda saplo init wykrywa stack na podstawie plików w katalogu:

package.json z zależnościami: next, nuxt, vue, svelte, react, astro...
manage.py - Django
Dockerfile - Docker
index.html bez package.json - static
menadżer pakietów: pnpm-lock.yaml / yarn.lock / domyślnie npm

Referencja komend

`saplo login`

Uwierzytelnienie za pomocą tokenu API.

$ saplo login [--token <token>]

Flaga	Opis
-t, --token	Token API (tryb nieinteraktywny)

# Interaktywne - CLI wyświetli adres panelu
$ saplo login

# CI/CD - token z env
$ saplo login --token "$SAPLO_TOKEN"

`saplo whoami`

Pokazuje zalogowanego użytkownika i szczegóły tokenu.

$ saplo whoami

Authenticated as:
  User:    jan@example.com
  Token:   deploy-token
  Scopes:  deploy, read
  API URL: https://api.saplo.pl

`saplo init`

Inicjalizuje saplo.yaml w bieżącym katalogu.

$ saplo init [--stack <stack>] [--name <nazwa>] [--app-id <id>] [--force]

Flaga	Opis
-s, --stack	Stack (pomija autodetekcję)
-n, --name	Nazwa aplikacji (slug)
--app-id	Podlinkuj od razu do istniejącego ID aplikacji
-f, --force	Nadpisz istniejący `saplo.yaml`

Z TTY (terminal) - interaktywny wizard z pytaniami; wykryty stack jest zaznaczony na liście. Bez TTY (CI, pipe, skrypt) - nieinteraktywny; używa flag i autodetekcji.

# Wizard interaktywny - wykryje stack i zapyta o nazwę
$ saplo init

# Nieinteraktywny, np. w CI
$ saplo init --stack nextjs --name moja-aplikacja

# Nadpisz istniejący plik
$ saplo init --force

`saplo link`

Podłączenie bieżącego katalogu do istniejącej aplikacji w Saplo. Zapisuje ID do .saplo/project.json.

$ saplo link [--app-id <id>]

Flaga	Opis
-a, --app-id	ID aplikacji (pomija wybór z listy)

# Lista aplikacji z wyborem interaktywnym
$ saplo link

# Bezpośrednie podłączenie po ID
$ saplo link --app-id 42

`saplo deploy`

Wdraża bieżący katalog na Saplo.

$ saplo deploy [--app-id <id>] [--no-logs] [--prebuilt]

Flaga	Opis
-a, --app-id	ID aplikacji (nadpisuje `.saplo/project.json`)
--no-logs	Nie streamuj logów buildu, tylko kolejkuj deploy
--prebuilt	Pomiń build po stronie serwera (wgraj gotowy output)

Kolejność ustalania ID aplikacji: --app-id > app_id w saplo.yaml > .saplo/project.json. Jeśli aplikacja nie istnieje, saplo deploy automatycznie ją tworzy.

# Standardowy deploy z logami
$ saplo deploy

# Deploy bez streamowania logów
$ saplo deploy --no-logs

# Upload gotowego builda (np. z GitHub Actions)
$ saplo deploy --prebuilt

Przebieg deployu:

Odczyt saplo.yaml
Spakowanie katalogu (tarball, z poszanowaniem .gitignore)
Upload do API
Streaming logów buildu (live)
Po sukcesie - wyświetlenie URL aplikacji

`saplo status`

Pokazuje aktualny stan aplikacji i listę ostatnich deployów.

$ saplo status [--app-id <id>]

moja-aplikacja (#42)
  Stack:    nextjs
  Status:   running
  URL:      https://moja-aplikacja.saploapp.pl
  Domains:  example.com

Current deployment:
  ID:       #18
  Status:   running
  Commit:   a1b2c3d4
  Duration: 45.2s

Recent deployments (5):
 * #18 running (45.2s)
   #17 success (43.1s)
   #16 failed
   #15 success (41.8s)
   #14 success (40.0s)

`saplo logs`

Wyświetla logi deployu.

$ saplo logs [--follow] [--deployment <id>] [--app-id <id>] [--tail <n>]

Flaga	Opis
-f, --follow	Śledź na bieżąco (polling)
-d, --deployment	ID konkretnego deployu (domyślnie: aktualny)
-a, --app-id	ID aplikacji
-n, --tail	Liczba ostatnich linii (domyślnie: 100)

# Ostatnie 100 linii aktualnego deployu
$ saplo logs

# Śledź na żywo
$ saplo logs --follow

# Logi konkretnego deployu
$ saplo logs --deployment 17

# Ostatnie 50 linii
$ saplo logs --tail 50

`saplo rollback`

Cofnięcie do poprzedniego deployu.

$ saplo rollback [<deployment_id>] [--app-id <id>]

Bez argumentu - automatycznie cofa do poprzedniego pomyślnego deployu.

# Automatyczny rollback do poprzedniej wersji
$ saplo rollback

# Rollback do konkretnego deployu
$ saplo rollback 15

`saplo open`

Otwiera URL aplikacji w domyślnej przeglądarce. Działa na macOS (open), Windows (start) i Linux (xdg-open).

$ saplo open [--app-id <id>]

`saplo env`

Zarządzanie zmiennymi środowiskowymi aplikacji.

`saplo env` (lista)

Wyświetla wszystkie zmienne środowiskowe. Wartości oznaczone jako sekrety są ukryte.

$ saplo env
# Environment variables (3):
#
#   DATABASE_URL=postgres://...
#   NODE_ENV=production
#   API_KEY=[secret]

`saplo env set`

Ustawia jedną lub więcej zmiennych. Zmienne są aktywne od następnego deployu.

$ saplo env set KEY=value [KEY2=value2 ...] [--app-id <id>]

$ saplo env set NODE_ENV=production

$ saplo env set DATABASE_URL=postgres://user:pass@host/db REDIS_URL=redis://...

# Wartość z użyciem cudzysłowów w shellu
$ saplo env set SECRET_KEY="moj tajny klucz z spacjami"

`saplo env rm`

Usuwa zmienną lub zmienne. Zmiany aktywne od następnego deployu.

$ saplo env rm STARA_ZMIENNA

$ saplo env rm KEY1 KEY2 KEY3

`saplo env pull`

Pobiera zmienne środowiskowe do lokalnego pliku .env. Sekrety są pomijane i wyświetlane jako komentarze.

$ saplo env pull [--output <plik>] [--force] [--app-id <id>]

Flaga	Opis
-o, --output	Ścieżka pliku wyjściowego (domyślnie: `.env.local`)
-f, --force	Nadpisz istniejący plik
-a, --app-id	ID aplikacji

# Pobierz do .env.local (domyślnie)
$ saplo env pull

# Pobierz do .env
$ saplo env pull --output .env --force

Dodaj plik wyjściowy do .gitignore - nie commituj zmiennych środowiskowych!

`saplo domain`

Zarządzanie własnymi domenami.

`saplo domain add`

Dodaje niestandardową domenę do aplikacji i wyświetla instrukcje konfiguracji DNS. Certyfikat SSL jest wystawiany automatycznie po propagacji DNS (zazwyczaj 1-5 minut).

$ saplo domain add example.com

$ saplo domain add www.example.com

`saplo domain ls`

$ saplo domain ls
# Custom domains:
#   example.com
#   www.example.com

`saplo domain rm`

$ saplo domain rm stara-domena.com

Pamiętaj o ręcznym usunięciu lub zaktualizowaniu rekordów DNS po stronie rejestratora.

Obsługiwane stacki

Stack	Opis	Domyślny port
nextjs	Next.js (SSR/SSG)	3000
react	React SPA (Vite / CRA, build statyczny)	80
vue	Vue 3 + Vite SPA (build statyczny)	80
nuxt	Nuxt 3 (Node SSR)	3000
sveltekit	SvelteKit + adapter-node (Node SSR)	3000
astro	Astro (build statyczny)	80
angular	Angular SPA (build statyczny)	80
django	Django + Gunicorn (Python)	8000
node	Dowolna aplikacja Node.js	3000
static	Czysty HTML/CSS/JS bez builda	80
docker	Dowolny Dockerfile (port z EXPOSE)	8080

Typowe scenariusze

Pierwszy deploy od zera

$ cd moj-projekt
$ saplo init        # wygeneruj saplo.yaml (autodetekcja stacka)
$ saplo deploy       # deploy - aplikacja zostanie utworzona automatycznie

Redeploy po zmianach

$ git add . && git commit -m "fix: poprawka"
$ saplo deploy

Rollback po wadliwym deployu

# Sprawdź dostępne deploye
$ saplo status

# Automatyczny rollback do poprzedniej wersji
$ saplo rollback

# Albo do konkretnego ID
$ saplo rollback 15

Zmienne środowiskowe w CI/CD

$ saplo env set DATABASE_URL="$DATABASE_URL" REDIS_URL="$REDIS_URL"
$ saplo deploy

Deploy z GitHub Actions

- name: Deploy to Saplo
  run: |
    npm install -g @saplo/cli
    saplo login --token "$"
    saplo deploy
  env:
    SAPLO_TOKEN: $

Pliki lokalne

Plik	Opis
saplo.yaml	Konfiguracja projektu, commituj do repozytorium
.saplo/project.json	ID podłączonej aplikacji, można commitować
~/.saplo/config.json	Token API i konfiguracja globalna (chmod 600)

Zmienne środowiskowe CLI

Zmienna	Opis
SAPLO_TOKEN	Token API (alternatywa dla `saplo login`)
SAPLO_API_URL	Niestandardowy adres API (domyślnie: `https://api.saplo.pl`)

Instalacja

Logowanie

Szybki start

Autodetekcja stacka

Referencja komend

saplo login

saplo whoami

saplo init

saplo link

saplo deploy

saplo status

saplo logs

saplo rollback

saplo open

saplo env

saplo env (lista)

saplo env set

saplo env rm

saplo env pull

saplo domain

saplo domain add

saplo domain ls

saplo domain rm