Projektowanie CLI dla AI Agentów: JSON, kody wyjścia i oczekiwanie

CLI dla AI agenta to nie tylko narzędzie wiersza poleceń dla człowieka, które przypadkiem można wywoływać z poziomu modelu. To operational protocol. Agent potrzebuje deterministycznych danych wejściowych, ustrukturyzowanych danych wyjściowych, znaczących kodów wyjścia, stabilnych kategorii błędów oraz sposobu oczekiwania, aż asynchroniczna infrastruktura osiągnie stan końcowy.

Bez takiego kontraktu agent musi wnioskować o powodzeniu na podstawie komunikatów w rodzaju „wdrażanie rozpoczęte”. To niebezpieczne, ponieważ zaakceptowane żądanie może później zakończyć się niepowodzeniem podczas builda, health checks, uruchamiania kontenera lub przełączania ruchu.

Dlaczego zgadywanie powodzenia wdrożenia jest niebezpieczne?

Większość operacji infrastrukturalnych jest asynchroniczna. API może zaakceptować wdrożenie i zwrócić jego ID w ciągu kilku milisekund, podczas gdy właściwy build potrwa kilka minut. Jeśli agent zgłosi powodzenie w momencie akceptacji, każdy kolejny krok będzie opierał się na fałszywym założeniu.

Rozważmy tę różnicę:

Zdarzenie	Co potwierdza	Czego nie potwierdza
Żądanie zaakceptowane	Platforma zrozumiała żądanie	Kod się zbudował
Build zakończony	Utworzono image lub artifact	Aplikacja się uruchomiła
Health gate zakończony powodzeniem	Nowa instancja odpowiada zgodnie z wymaganiami	Działają procesy biznesowe
Ruch przełączony	Release stał się aktywny	Czy pozostanie zdrowy
Obserwacja uptime	Usługa pozostaje osiągalna	Czy każda funkcja działa poprawnie

Człowiek może zauważyć tę różnicę na dashboardzie. Agent działający za pośrednictwem tekstu musi mieć ją zakodowaną w interfejsie.

Kontrakt poleceń Dockup oddziela kolejkowanie od zakończenia operacji. deploy bez --wait zwraca wynik natychmiast z waited:false; deploy z --wait blokuje wykonanie do momentu powodzenia, niepowodzenia lub przekroczenia limitu czasu:

dockup deploy production/api --wait --json

Domyślny limit czasu wynosi 900 sekund. Polecenie kończy się kodem 0 dopiero po pomyślnym osiągnięciu stanu końcowego. Jeśli wynik nie oznacza powodzenia, polecenie kończy się wartością różną od zera oraz kodem deploy_failed lub deploy_timeout.

Co ustrukturyzowane CLI JSON daje AI agentowi?

Ustrukturyzowany JSON zastępuje interpretowanie prozy nazwanymi polami. Agent może bezpośrednio odczytać status, deploymentId, target lub code, zamiast polegać na interpunkcji, kolorach, szerokości kolumn albo użytym sformułowaniu.

Pomyślny wynik można przetworzyć jako dane:

{
  "ok": true,
  "target": "production/api",
  "deploymentId": "dep_123",
  "waited": true,
  "status": "success",
  "durationMs": 142381,
  "url": "https://api.dockup.tech"
}

Błąd korzysta z tego samego kształtu transportowego:

{
  "ok": false,
  "error": "Deployment failed",
  "code": "deploy_failed"
}

Najważniejsza zasada projektowa mówi, że JSON jest zapisywany do stdout, natomiast ostrzeżenia, które nie mogą zakłócać parsowania, trafiają do stderr. Logi w trybie follow korzystają z NDJSON — jeden obiekt JSON w każdym wierszu — dzięki czemu wywołujący może przetwarzać strumień przyrostowo, bez oczekiwania na jedną dużą tablicę.

Dockup stosuje --json w całym interfejsie poleceń. Przy 135 poleceniach wymaganie, by agent odgadywał flagi na podstawie pamięci, byłoby kruche. Dokumentacja CLI i dołączony skill dostarczają agentowi zgodnych z wersją instrukcji dotyczących poleceń.

Najważniejszą właściwością projektową nie jest sprytne odkrywanie możliwości. Chodzi o to, aby agent otrzymywał aktualne, ustrukturyzowane wskazówki operacyjne i nie wymyślał flagi na podstawie starego promptu.

Jak rzeczywiste kody wyjścia sterują automatyzacją wdrożeń?

Kod wyjścia systemu operacyjnego to najbardziej przenośny sygnał powodzenia dostępny dla skryptów shellowych, runnerów CI i coding agents. Kod 0 oznacza, że polecenie osiągnęło zdefiniowany rezultat. Wartość różna od zera oznacza, że wywołujący musi przejść do obsługi odzyskiwania, eskalacji lub zakończenia działania.

Ten fragment shell jest celowo pozbawiony udziwnień:

if dockup deploy production/api --wait --json > result.json; then
  echo "deployment reached success"
else
  dockup logs production/api --build --json
  exit 1
fi

Nie wyszukuje w stdout słowa „success”. Nie zakłada, że odpowiedź HTTP 202 oznacza gotowość produkcji. Przekazuje CLI definicję powodzenia i propaguje błąd do procesu nadrzędnego.

Rzeczywiste kody wyjścia są równie ważne dla jednorazowych poleceń uruchamianych wewnątrz kontenera. Polecenie PRO exec Dockup zwraca stdout, stderr oraz rzeczywisty kod wyjścia polecenia:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Agent może dzięki temu odróżnić zakończoną migrację od polecenia, które jedynie się uruchomiło. To podstawowa zasada guardrails produkcyjnych dla AI agentów.

Jak oczekiwanie na stan końcowy zastępuje kruche polling?

Ręcznie napisane pętle polling wprowadzają ukryte decyzje dotyczące polityki: jak często wykonywać polling, które stany są końcowe, jak długo czekać, czy przejściowy błąd sieci powinien resetować licznik oraz co zrobić po ponownym uruchomieniu kontenera.

Agent jest szczególnie podatny na błędne decyzje, ponieważ może nie znać kompletnej state machine platformy. To platforma powinna odpowiadać za semantykę oczekiwania.

Dockup udostępnia dwa przydatne wzorce:

dockup deploy production/api --wait --timeout 1800 --json
dockup push --json

deploy --wait jawnie oczekuje na zakończenie. push domyślnie czeka po wykonaniu push i uruchomieniu release; --no-wait wyłącza to zachowanie. Oba polecenia zwracają kod wyjścia odzwierciedlający wynik końcowy.

Śledzenie logów działa według tej samej zasady:

dockup logs production/api --build -f --json

Strumień kończy się, gdy build osiągnie stan powodzenia lub niepowodzenia. Końcowy obiekt NDJSON oznacza done:true, a nieudany build kończy się kodem różnym od zera. Wywołujący nie musi implementować drugiego mechanizmu pollingu.

Aby sprawdzić dostępność aplikacji po wdrożeniu, polecenie uptime Dockup zwraca kontrole wykonywane co minutę, średni czas odpowiedzi oraz p95:

dockup uptime production/api --hours 24 --json

Oczekiwanie i monitoring to odrębne pojęcia. --wait odpowiada na pytanie, czy to wdrożenie osiągnęło stan końcowy; uptime pokazuje, jak działająca usługa zachowywała się w czasie.

Które kody błędów agent powinien rozumieć?

Stabilne kategorie błędów pozwalają agentowi podjąć ograniczone działanie bez interpretowania każdego możliwego komunikatu. Dockup udostępnia między innymi takie kody:

Kod błędu	Znaczenie	Bezpieczna reakcja agenta
not_logged_in	Brak użytecznego tokenu	Zatrzymaj działanie i poproś o uwierzytelnienie
not_linked	Brak celu .dockup dla push	Ustal cel lub przekaż go jawnie
no_target	Nie udało się zidentyfikować usługi	Uruchom services --json
needs_confirm	Destrukcyjne działanie nie ma zatwierdzenia	Poproś człowieka o potwierdzenie
deploy_trigger_failed	Nie udało się rozpocząć wdrożenia	Zgłoś błąd API
deploy_failed	Build lub wdrożenie zakończyło się niepowodzeniem	Odczytaj logi builda
deploy_timeout	Operacja nadal trwa po upływie limitu oczekiwania	Zgłoś niepewność lub świadomie wydłuż oczekiwanie

Komunikat błędu nadal dostarcza przydatnego kontekstu, ale to kod steruje pierwszą gałęzią obsługi. Dzięki temu automatyzacja pozostaje odporna na bardziej precyzyjne sformułowania lub lokalizację.

Potwierdzenie również jest częścią protokołu. Destrukcyjne polecenie nie powinno uruchamiać się po cichu tylko dlatego, że wywołujący działa w trybie nieinteraktywnym. Dockup odmawia wykonania takich operacji bez --yes i zwraca needs_confirm. Autonomiczny agent otrzymuje pytanie, a nie przeszkodę do obejścia.

Model bezpieczeństwa omawiamy szerzej w artykule o najlepszych praktykach bezpieczeństwa.

Jaki jest minimalny kontrakt CLI gotowego do użycia w produkcji?

Gotowe do produkcji CLI dla AI agenta powinno spełniać niewielki, ale rygorystyczny kontrakt:

1. Każda operacja odczytu i zapisu ma format machine-readable.
2. Błąd powoduje zakończenie procesu kodem różnym od zera.
3. Asynchroniczne mutacje mogą oczekiwać na udokumentowany stan końcowy.
4. Wartości sekretów nigdy nie są zwracane przez polecenia odczytu.
5. Destrukcyjne działania wymagają jawnego potwierdzenia.
6. Błędy mają stabilne kody odpowiednie do rozgałęziania logiki.
7. Pakiet CLI i instrukcje dla agenta pozostają zgodne z wersją.
8. Mutacje są zapisywane w audit trail.

Skill Dockup zamienia te zasady w domyślne zachowanie dla Claude Code i Codex. Instruuje agenta, aby używał JSON, uwierzytelniał się za pomocą DOCKUP_TOKEN, odkrywał dokładne cele, wdrażał z --wait, chronił dane uwierzytelniające i zatrzymywał się po otrzymaniu needs_confirm.

Porównaj ten model z szerszymi koncepcjami opisanymi w artykule agent skills vs MCP. Skill dostarcza wiedzy operacyjnej, natomiast CLI pozostaje wykonywalnym interfejsem, którego status zakończenia i dane wyjściowe definiują prawdę.

Macierz testów dla polecenia używanego przez agenta

Zanim udostępnisz agentowi dowolne polecenie infrastrukturalne, przetestuj więcej niż tylko ścieżkę poprawnego wykonania:

Test	Oczekiwane zachowanie
Poprawne żądanie	Wynik JSON i kod wyjścia 0
Nieprawidłowy token	Stabilny kod uwierzytelniania i kod wyjścia różny od zera
Nieznany cel	Stabilny kod celu i brak mutacji
Długotrwałe wdrożenie	Oczekiwanie na stan końcowy lub timeout
Nieudane wdrożenie	Kod wyjścia różny od zera oraz możliwe do zdiagnozowania ID wdrożenia
Brak zgody na działanie destrukcyjne	needs_confirm, brak usunięcia
Odczyt sekretu	Widoczne metadane klucza, wartość zamaskowana
Ostrzeżenie podczas danych wyjściowych JSON	Ostrzeżenie na stderr, poprawny JSON na stdout

Ta macierz jest cenniejsza niż dopracowany progress spinner. Formatowanie dla człowieka można nałożyć później; deterministycznego kontraktu maszynowego nie da się odtworzyć po fakcie.

Dokumentacja Dockup CLI pokazuje konkretne polecenia stojące za tym modelem, natomiast artykuł development wspomagany przez AI wyjaśnia szerszą zmianę: przejście od ręcznego używania narzędzi do workflow sterowanych przez agenta.

Traktuj observability jako część kontraktu polecenia

Mutacja wykonywana przez agenta powinna zwracać identyfikatory umożliwiające późniejsze dochodzenie. Odpowiedź dotycząca wdrożenia powinna zawierać cel i ID wdrożenia; utworzona baza danych powinna mieć stabilny slug; snapshot volume powinien mieć własne ID. Bez tych odwołań agent może opisać zdarzenie, ale nie może niezawodnie go sprawdzić, ponowić ani odwrócić.

Audit trail dopełnia kontrakt. Ustrukturyzowane dane wyjściowe opisują jedno wywołanie, natomiast rekordy audytowe łączą wiele wywołań w czasie. Razem pozwalają operatorom ustalić, czy agent działał na zamierzonym zasobie oraz czy późniejsze polecenie naprawcze odnosiło się do tego samego zdarzenia produkcyjnego.

Interfejs powinien być przewidywalny

Niezawodne CLI dla AI agenta nie powinno zaskakiwać w przypadku powodzenia, błędu, timeoutu ani ponowienia.

Końcowy test interfejsu

CLI dla AI agenta musi zgłaszać błędy zgodnie z rzeczywistością.

Przenieś workflow na produkcję

Najpierw przetestuj kontrakt z poziomu shella: sprawdź parsowanie JSON, pomyślne zakończenie, wymuszone niepowodzenie, timeout oraz zablokowaną operację destrukcyjną, zanim przekażesz agentowi dostęp do produkcji.

npm install -g dockup-cli
dockup skill install

Pierwsze polecenie instaluje CLI. Drugie instaluje zgodny skill Dockup dla Claude Code i Codex. Zacznij bezpłatnie na app.dockup.ai.

FAQ

Co sprawia, że CLI nadaje się do użycia przez AI agentów?

Potrzebuje ustrukturyzowanych danych wyjściowych, rzeczywistych kodów wyjścia, oczekiwania na stan końcowy, stabilnych kodów błędów, maskowania sekretów oraz jawnego potwierdzania operacji destrukcyjnych.

Dlaczego JSON jest lepszy od danych wyjściowych CLI sformatowanych dla człowieka?

JSON zapewnia stabilne nazwy i typy pól. Agent nie musi wnioskować o znaczeniu na podstawie kolorów, tabel, interpunkcji ani zmieniającej się prozy.

Dlaczego zaakceptowane żądanie wdrożenia nie oznacza powodzenia?

Akceptacja potwierdza jedynie, że platforma umieściła operację w kolejce. Późniejszy build, uruchomienie, health gate i przełączenie ruchu nadal mogą zakończyć się niepowodzeniem.

Jaki jest domyślny limit czasu oczekiwania na wdrożenie Dockup?

Domyślny limit czasu dla dockup deploy --wait wynosi 900 sekund. Można go zmienić za pomocą udokumentowanej opcji --timeout.

Jak agent powinien reagować na needs_confirm?

Powinien zatrzymać działanie i poprosić o jawne potwierdzenie. Kod oznacza, że żądane działanie jest destrukcyjne i celowo nie zostało wykonane.