CLI — interfejs wiersza poleceń#

KSeFka dostarcza CLI (ksefka) do zarządzania fakturami, kontrahentami i danymi bezpośrednio z terminala lub skryptów. Większość komend wymaga licencji PRO (bez niej działają m.in. status, authorize i lista produktów). Każda instalacja ma 30 dni okresu próbnego, wspólnego z aplikacją i MCP; rusza przy pierwszym uruchomieniu aplikacji albo pierwszej komendzie CLI.

Instalacja#

CLI jest dołączone do instalatora KSeFka, ale nie włącza się samo. Otwórz Ustawienia → CLI i kliknij "Zainstaluj CLI" — dopiero wtedy polecenie ksefka pojawia się w terminalu. Na Windows instalator aplikacji dodaje katalog instalacji do zmiennej PATH, więc nic więcej nie trzeba ustawiać.

Kolejne wersje CLI aplikacja podmienia sama, o ile CLI jest już zainstalowane.

Weryfikacja instalacji:

ksefka --version

Opcje globalne#

Opcja	Opis
`--env <środowisko>`	Środowisko KSeF: `test`, `demo`, `production` (domyślnie: `production`)
`--company <nip>`	NIP firmy, gdy masz skonfigurowanych kilka firm
`--help`	Wyświetl pomoc dla komendy

Jak znaleźć pomoc#

Każda komenda ma wbudowaną dokumentację:

ksefka --help                    # lista wszystkich komend
ksefka <komenda> --help          # szczegóły konkretnej komendy

Komendy#

Komenda	Opis
Faktury
`list-invoices`	Lista faktur z filtrowaniem
`get-invoice`	Szczegóły faktury z pozycjami
`create-invoice`	Utwórz fakturę z pliku JSON lub stdin
`finalize`	Przenieś fakturę roboczą do stanu "gotowa do wysłania"
`unfinalize`	Cofnij finalizację faktury do wersji roboczej
`copy-invoice`	Skopiuj fakturę jako nowy szkic z dzisiejszą datą
`open`	Otwórz fakturę w aplikacji desktopowej
`payment-file`	Wygeneruj plik przelewów (Elixir-0) dla faktur otrzymanych — PRO, 1 darmowy eksport
Kontrahenci
`list-contractors`	Lista kontrahentów z wyszukiwaniem
`get-contractor`	Szczegóły kontrahenta
`create-contractor`	Dodaj kontrahenta z pliku JSON lub stdin
`update-contractor`	Zaktualizuj dane kontrahenta
`delete-contractor`	Usuń (dezaktywuj) kontrahenta
Produkty
`list-products`	Lista produktów/usług z katalogu
`get-product`	Szczegóły produktu
`create-product`	Dodaj produkt do katalogu — flagi `--vat-exemption-reason-type` i `--vat-exemption-reason` zapisują podstawę zwolnienia przy stawce zw.; dostępne też w `update-product`
Raporty
`monthly-summary`	Podsumowanie miesięczne (przychody/koszty)
`dashboard-stats`	Statystyki bieżącego miesiąca
Inne
`mcp`	Uruchom serwer MCP (stdio)

Wejście JSON#

Komendy tworzące obiekty (np. create-invoice, create-contractor) przyjmują dane jako:

# z pliku
ksefka create-invoice --file faktura.json

# ze stdin (pipe)
cat faktura.json | ksefka create-invoice --file -

# lub przekierowanie
ksefka create-invoice --file - < faktura.json

Strukturę JSON znajdziesz w pomocy komendy: ksefka create-invoice --help.

Kody wyjścia#

Komendy zwracają wynik jako JSON na stdout, w polu data. Skrypt rozpoznaje, co się stało, po kodzie wyjścia:

0 — komenda wykonała pracę w całości
1 — komenda nie wykonała pracy; na stdout zamiast data jest { "error": "..." }
2 — błędne wywołanie (nieznana flaga, brak argumentu); opis na stderr, nic na stdout
3 — komenda wykonała część pracy. Wynik jest na stdout jak przy kodzie 0, a podsumowanie problemów na stderr. Obecnie tak kończy się tylko process-recurring, gdy choć jeden harmonogram został bez faktury: data zawiera wynik każdego harmonogramu, obok są liczniki generated_count i failed_count, a stderr wymienia nieudane harmonogramy z powodem.

# cron: alarm, gdy process-recurring nie wykonał pracy albo któryś harmonogram został bez faktury
ksefka process-recurring > /tmp/cykliczne.json || echo "process-recurring: kod $?" | mail -s "KSeFka" ja@firma.pl