# CLI - Monolynx z terminala

> Cała platforma z terminala - bez klikania w UI

Klient wiersza poleceń monolynx (alias mnx) daje dostęp do projektów, ticketów, sprintów, wiki i odczytu grafu zależności kodu prosto z terminala. Komendy wykonują te same operacje co narzędzia MCP, a wyjście w formacie JSON jest gotowe do potoku - wystarczy jq, żeby wpiąć Monolynx w skrypty, hooki Gita i zadania CI.

## Funkcje

- **Instalacja jedną komendą**: pipx install monolynx-cli, uv tool install monolynx-cli albo pip install monolynx-cli. Na macOS i Linuksie także przez Homebrew z tapu monolynx/tap. Wymagany Python 3.10+.
- **Cztery formaty wyjścia**: Przełącznik -o wybiera table, json, yaml albo csv. Poza terminalem (potok, plik) CLI samo przełącza się na JSON, więc nie trzeba pamiętać o fladze.
- **Potoki z jq**: Listy ticketów zwracają kopertę paginacji {items, page, per_page, total, total_pages}, np. monolynx -o json ticket list | jq '.items[] | .key'. Dane idą na stdout, stopka strony na stderr.
- **Profile dla wielu instancji**: Plik config.toml przechowuje dowolną liczbę profili (endpoint, projekt, token). Przełączasz je przez --profile, MONOLYNX_PROFILE albo config set general.active_profile.
- **Kody wyjścia dla CI**: 0 sukces, 1 błąd API, 2 błąd użycia lub walidacji, 3 błąd autoryzacji, 4 błąd sieci. Skrypt reaguje na kod zamiast parsować komunikaty.
- **Logowanie w przeglądarce lub tokenem**: monolynx auth login otwiera przeglądarkę i loguje przez OAuth. Na runnerze CI albo przez SSH użyj monolynx auth login --token osk_... lub zmiennej MONOLYNX_TOKEN.
- **Alias mnx i parytet z MCP**: Pakiet instaluje dwie równoważne komendy: monolynx i mnx. Grupy project, member, ticket, sprint i wiki pokrywają te same operacje co narzędzia MCP, bo obie strony korzystają z jednej warstwy serwisów.
- **Graf zależności w terminalu**: Grupa graph czyta graf kodu z modułu Połączenia: monolynx graph nodes, node, query, path i stats, przez endpointy API v2 /graph. Tylko odczyt - zapis grafu robi wyłącznie synchronizacja przez MCP.

## Jak to działa

1. **Zainstaluj CLI**: pipx install monolynx-cli, uv tool install monolynx-cli albo pip install monolynx-cli. Homebrew: brew install monolynx/tap/monolynx, albo najpierw brew tap monolynx/tap, a potem brew install monolynx.
2. **Zaloguj się**: monolynx auth login otwiera przeglądarkę i loguje przez OAuth. Bez przeglądarki: monolynx auth login --token osk_..., z tokenem wygenerowanym w profilu.
3. **Zobacz swoje projekty**: monolynx project list wypisuje projekty, do których masz dostęp. Domyślny projekt ustawisz przez monolynx config set profile.default.project <slug>.
4. **Pracuj na ticketach**: monolynx --project <slug> ticket list pokazuje tickety projektu, a ticket create, ticket update i ticket comment add zmieniają ich stan bez otwierania dashboardu.
5. **Wepnij w skrypt lub potok**: Wyjście JSON przekaż do jq, a kody wyjścia do instrukcji case. Tak zbudujesz hook Gita, zadanie CI albo raport w cronie.

## AI i MCP

CLI korzysta z REST API i tej samej warstwy serwisów co narzędzia MCP, więc agent AI i człowiek w terminalu wykonują te same operacje na tych samych danych. Poniżej reprezentatywny wybór komend z każdej grupy.

**Dostępne komendy:**

- `monolynx project list`: Lista projektów, do których masz dostęp.
- `monolynx project get`: Szczegóły projektu: rola, liczba członków i ticketów, aktywny sprint.
- `monolynx project summary`: Podsumowanie projektu: błędy, monitory, uptime, aktywny sprint, backlog.
- `monolynx member list`: Lista członków projektu.
- `monolynx member invite`: Zaproś osobę do projektu z rolą member lub admin.
- `monolynx ticket list`: Lista ticketów projektu z filtrami statusu, priorytetu, sprintu i terminu.
- `monolynx ticket get`: Szczegóły ticketu po UUID albo kluczu, np. MON-42.
- `monolynx ticket create`: Utwórz ticket z opisem, priorytetem, story points i kryteriami akceptacji.
- `monolynx ticket update`: Zmień status, priorytet, opis lub przypisanie ticketu - wysyłane są tylko podane pola.
- `monolynx ticket search`: Szukaj ticketów po frazie i filtrach.
- `monolynx ticket comment add`: Dodaj komentarz markdown do ticketu; treść może iść ze stdin.
- `monolynx ticket ac list`: Lista kryteriów akceptacji ticketu.
- `monolynx sprint list`: Lista sprintów projektu, opcjonalnie filtrowana statusem.
- `monolynx sprint start`: Uruchom sprint (w danym momencie aktywny może być tylko jeden).
- `monolynx sprint board`: Tablica Kanban aktywnego sprintu.
- `monolynx sprint burndown`: Burndown sprintu (domyślnie aktywnego).
- `monolynx wiki list`: Lista stron wiki projektu, opcjonalnie jako drzewo.
- `monolynx wiki get`: Pokaż stronę wiki z treścią albo tylko surowy markdown.
- `monolynx wiki create`: Utwórz stronę wiki z treścią z opcji, pliku lub stdin.
- `monolynx wiki edit`: Edytuj treść strony w $EDITOR; zapis tylko po zmianie.
- `monolynx wiki search`: Semantyczne wyszukiwanie po stronach wiki.
- `monolynx graph nodes`: Lista node'ów grafu zależności z filtrem po typie i fragmencie nazwy.
- `monolynx graph node`: Node z sąsiedztwem: sąsiednie node'y, krawędzie i głębokość, z filtrem relacji i typów.
- `monolynx graph query`: Graf albo podgraf projektu (node'y i krawędzie), opcjonalnie po typie i frazie.
- `monolynx graph path`: Najkrótsza ścieżka między dwoma node'ami.
- `monolynx graph stats`: Statystyki grafu: liczba node'ów i krawędzi, także per typ.
- `monolynx blog list`: Lista wpisów bloga z metadanymi, także szkice; filtr published albo draft.
- `monolynx blog get`: Wpis bloga: metadane, adresy publiczne i treść markdown.
- `monolynx blog meta`: Zmień metadane wpisu: slug, opis, autora, tagi, język, okładkę, datę weryfikacji.
- `monolynx blog lint`: Lint wpisu pod AI: problemy z linią i poziomem oraz ocena 0-100; kod wyjścia 1 przy błędzie.
- `monolynx blog publish`: Opublikuj wpis po lincie; błędy lintu to odmowa i kod wyjścia 1, chyba że --force. Komendy meta, publish i unpublish wymagają uprawnienia do edycji bloga (bez niego 403 i kod wyjścia 3).
- `monolynx blog unpublish`: Cofnij publikację wpisu: adres i wersja .md dają 404, data i slug zostają.

## Szczegóły techniczne

- **Framework**: Typer z tabelami renderowanymi przez Rich. Teksty pomocy i komunikaty są po polsku.
- **Pakiet**: monolynx-cli w PyPI, dwie binarki: monolynx i mnx (ten sam punkt wejścia). Python 3.10+.
- **Komunikacja**: Wyłącznie przez REST API v2 (/api/v2). Uwierzytelnianie OAuth 2.1 z PKCE albo token API osk_.
- **Wspólna warstwa serwisów**: Logika biznesowa żyje w src/monolynx/services/ i jest współdzielona przez narzędzia MCP oraz endpointy API v2, z których korzysta CLI.
- **Konfiguracja**: Plik config.toml w katalogu konfiguracyjnym użytkownika (uprawnienia 0600) z profilami. Kolejność: opcja, zmienna środowiskowa, plik, wartość domyślna.
- **Ponowienia i limity**: GET i DELETE ponawiane przy 429 i 5xx, POST i PATCH tylko przy 429. Maksymalnie 4 próby, timeout żądania ustawiasz przez --timeout.