ARC CLI — Przewodnik po komendach

ARC CLI to narzędzie wiersza poleceń do interakcji z Arc Cloud. Zarządzaj projektami, zadaniami, wiki i skillami bezpośrednio z terminala.

• Kod źródłowy: clients/arc-cli.ts
• Klient API: clients/lib/api.ts
• Kompilacja: scripts/build-arc.sh (skompilowany binary)

Instalacja i konfiguracja

Konfiguracja jest zapisywana w ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

Autoryzacja przez device code flow. Otwiera przeglądarkę do potwierdzenia.

arc login                          # domyślny serwer: https://arc-os.co
arc login https://my-server.com    # własny serwer

Po uruchomieniu CLI wyświetli URL oraz jednorazowy kod. Otwórz URL w przeglądarce, potwierdź autoryzację — CLI automatycznie pobierze token.

arc login --token <token>

Bezpośrednia autoryzacja tokenem (do automatyzacji lub gdy device flow jest niedostępny).

arc login --token eyJhbGciOiJIUzI1NiI...

CLI weryfikuje token przez API przed zapisaniem.

arc logout

Usuwa credentials z ~/.arc/config.json i czyści blok ARC z CLAUDE.md (jeśli istnieje).

arc logout

arc projects

Lista dostępnych projektów na serwerze.

arc projects

Wynik:

Available projects:

  Name                   Type           Status
  --------------------------------------------------
  arc-v2                 bot            running
  my-project             bot            unknown

Uruchamianie sesji

arc <project> [mode]

Inicjalizuje sesję Claude z pełnym kontekstem projektu. Odpowiednik arc start <project> [mode].

arc my-project dev             # tryb dev (domyślny)
arc my-project prod            # tryb prod
arc --role clceo my-project    # z rolą CEO

Co się dzieje przy uruchomieniu:

1. Zapytanie GET /api/cli/init/:project/:mode — pobieranie CLAUDE.md, worker config, skilli
2. Session-start picker (issue #115) — interaktywny wybór aktywnego issue dla sesji: otwarte issues (sortowanie P0→P3 + najnowsze pierwsze, fuzzy filter gdy >10), ostatnio zamknięte (z reopen-confirm przy wyborze), [n] utwórz nowe, [q] pomiń z double-confirm. Wybrany id jest zapisywany w ~/.arc/sessions/<project>-<worker>.json jako active_issue_id
3. Wstrzyknięcie kontekstu do lokalnego CLAUDE.md (blok ARC Cloud + blok Active issue: #N — Title)
4. ARC_ACTIVE_ISSUE_ID=<id> — zmienna środowiskowa przekazywana do podprocesu Claude — narzędzie Bash widzi ją dla arc issue log bez re-prompt
5. Czyszczenie przestarzałych wpisów .mcp.json (jeśli są)
6. Uruchomienie podprocesu claude z interaktywnością TTY
7. Start background watchera (zob. "Monitorowanie sesji")

Parametry:

Bypass dla trybu nieinteraktywnego: ARC_ISSUE_ID=42 arc my-project dev pomija picker i używa podanego id (dla CI/skryptów).

Przełączanie w trakcie sesji: arc issue switch <id> (z równoległego terminala) przełącza aktywny issue — zapisuje switched_away na poprzednim + switched_in na nowym. Bieżąca sesja pobierze nowe id po restarcie.

arc continue <project> [mode]

Wznawia ostatnią sesję Claude Code (okno 24-godzinne). Automatycznie przywraca active_issue_id bez re-prompt.

arc continue my-project             # wznów poprzednią sesję + active issue
arc continue my-project --reselect-issue   # wymuś ponowne uruchomienie pickera

arc tour

Interaktywny 5-krokowy onboarding w terminalu (odpowiednik web checklist). Postęp synchronizuje się z pulpitem webowym.

arc tour

Zarządzanie zadaniami (Issues)

arc issues [--status <filter>]

Lista zadań projektu.

arc issues                    # tylko otwarte (domyślne)
arc issues --status closed    # tylko zamknięte
arc issues --status all       # wszystkie zadania

Wynik:

3 issue(s):
- #12 [P1] Add dark mode [ux, frontend]
- #15 [P2] Fix login timeout
- #18 [P0] Critical: DB migration

arc issue create --title "..." [options]

Utwórz nowe zadanie.

arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"
arc issue create --title "Fix bug" --body "Detailed description here" --priority P0

Parametry:

arc issue update <id> [options]

Zaktualizuj istniejące zadanie.

arc issue update 12 --status closed
arc issue update 15 --priority P0 --title "Critical: Fix login timeout"
arc issue update 18 --body "Updated description with more context"

Parametry:

Wymagany jest przynajmniej jeden parametr do aktualizacji.

arc issue log <id> "<text>" [--author <name>]

Dodaj wpis postępu do zadania (activity log).

arc issue log 12 "Started implementation"
arc issue log 12 "Dark mode toggle works" --author "developer"

Parametry:

Backend (POST /api/mcp/issues/:project/:id/log) przyjmuje opcjonalne pola type (whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) i ts (ISO-8601 dla wpisów z datą wsteczną, wpisy z datą przyszłą są przycinane do now). Używane wewnętrznie przez session-start picker (#115) i arc retro (#117).

arc issue switch <id>

Przełącz aktywny issue dla bieżącej sesji (issue #115). Zapisuje do ~/.arc/sessions/<project>-<worker>.json, wpisuje switched_away na poprzednim issue + switched_in na nowym.

arc issue switch 42
arc issue switch 42 --worker consultant   # dla konkretnego workera (domyślnie: developer)

Walidacja: issue musi istnieć + być open. Jeśli jest zamknięty — najpierw arc issue update <id> --status open.

arc retro <project> [options]

Rekonstruuje issues z historii sesji + git log (issue #117). Skanuje ~/.arc/sessions/<project>-*.json, czyta pierwszy prompt użytkownika z transkryptu JSONL, zbiera commity przez git log --since=started_at --until=ended_at.

arc retro gapap                       # dry-run — wyświetla plan
arc retro gapap --apply               # tworzy issues
arc retro gapap --since 2026-01-01    # tylko po tej dacie
arc retro gapap --worker consultant   # tylko dla jednego workera

Co jest automatycznie pomijane:

Co się dzieje przy --apply:

1. createIssue dla każdego kandydata (priority=P2, label=retro)
2. Wpisy aktywności z datą wsteczną: session_start (started_at) + auto_summary na commit (timestamp commita) + session_end (ended_at) — przez POST /log z polem ts
3. Sesje >30 dni z commitami → status=closed od razu. Ostatnie niezakończone → status=open.

Skille i wiedza

arc skill <name>

Załaduj skill z Cloud. Wyświetla instrukcje skilla i evals (jeśli są).

arc skill consultant_system
arc skill crm-api-reference

Wymagana zmienna ARC_PROJECT (ustawiana automatycznie przy arc start).

Jeśli skill nie zostanie znaleziony, CLI wyświetli listę dostępnych.

arc kb search "<query>"

Wyszukiwanie w wiki projektu. Dopasowanie słów kluczowych po nazwach plików, zwraca do 5 najlepszych wyników (treść przycinana do 2000 znaków).

arc kb search "deployment"
arc kb search "arc-cli"

arc learnings

Zgromadzone reguły i korekty ze wszystkich sesji projektu.

arc learnings

Wynik:

- [cli] Always validate project name before API calls
- [deploy] Test nginx config before reload

Wiki i Roadmap

arc wiki update --file <name> --content "..."

Utwórz lub zaktualizuj stronę wiki projektu.

arc wiki update --file "architecture" --content "# Architecture\n\nMain components..."
arc wiki update --file "deploy-guide" --content "$(cat my-doc.md)"

Parametry:

Wynik: Wiki created: architecture.md (342 bytes) lub Wiki updated: ...

arc roadmap sync --phase <id> --status <text> [--notes "..."]

Zaktualizuj status fazy w roadmapie projektu.

arc roadmap sync --phase 45 --status "IN PROGRESS"
arc roadmap sync --phase 44 --status "DONE" --notes "All analytics redesigned"

Parametry:

Raportowanie

arc report --summary "..." [options]

Wyślij raport sesji do Arc Cloud.

arc report --summary "Implemented dark mode with system preference detection"
arc report --summary "Fixed auth bug" --files "auth.ts,middleware.ts" --decisions "Switched to HMAC tokens"

Parametry:

Documentation Enforcement (Phase 49.1-49.2.1)

ARC ma wbudowany system, który utrzymuje dokumentację na bieżąco bez ręcznych przypomnień. Działa razem z pre-push git hookiem (scripts/check-docs-coverage.ts).

arc wrapup

Checklista tylko do odczytu — pokazuje, które dokumenty wymagają aktualizacji dla nieprzesłanych commitów.

arc wrapup

Deleguje do scripts/check-docs-coverage.ts. Mapowanie:

arc wrapup --generate

Automatycznie generuje szkieletowe wpisy dla brakujących dokumentów. Zapisuje TODO-oznaczone szablony w:

• learnings.md — timestamp + automatycznie wykryty zakres (api/backend/frontend/infra/process)
• docs/ROADMAP.md — nagłówek Phase NN + podsumowanie commita
• docs/status/current-state.json — podbicie wersji + dodanie zmiany na początku

arc wrapup --generate
# następnie: przejrzyj przez `git diff`, zamień TODO na prawdziwą treść, commit

Znaczniki TODO celowo nie przejdą recenzji — generowana jest struktura, nie treść.

arc wrapup --from-summary "<text>"

Zapisuje badania/decyzję/odkrycie bezpośrednio w learnings.md bez commita kodu. Zamyka ślepy punkt dla pracy bez commitów kodu (analiza wydajności, porównanie brokerów, przegląd kompromisów).

arc wrapup --from-summary "Decision: rejected Redis for single-VPS — broker overhead unjustified for 10KB/msg, 1-to-1 FIFO. fs.watch sufficient."

CLI automatycznie klasyfikuje:

• Typ: decision / lesson / finding / spike (podpowiedzi regex)
• Zakres: infra / perf / security / api / frontend / process

Format wpisu:

- [2026-04-28T15:00:00.000Z] [perf] Decision: ...

GitHub Integration (Phase 49.3)

Powiadomienia oparte na webhookach + feed w UI dla powiązanych repozytoriów GitHub.

arc github link <project> <owner/repo>

Powiąż repozytorium z projektem. Zwraca URL webhooka, sekret i instrukcje krok po kroku dla GitHub repo Settings → Webhooks.

arc github link arc-v2 SerhiiInUa/citadel-v2

Wynik:

✓ Repo linked.

Webhook URL:    https://arc-os.co/api/webhooks/github
Webhook secret: <32-byte hex>

Setup instructions:
  1. Go to https://github.com/SerhiiInUa/citadel-v2/settings/hooks
  2. Click "Add webhook"
  3. Payload URL: https://arc-os.co/api/webhooks/github
  4. Content type: application/json
  5. Secret: <secret>
  6. Events: Push, Pull requests, Workflow runs, Issues

arc github links [project]

Lista powiązanych repozytoriów dla projektu (domyślnie: zmienna środowiskowa ARC_PROJECT).

arc github links arc-v2

arc github unlink <project> <id>

Usuń powiązanie po id (z arc github links).

arc github unlink arc-v2 3

Obsługiwane zdarzenia: push, pull_request, workflow_run, issues (95% przypadków użycia).

Co otrzymujesz po konfiguracji:

• Powiadomienie Telegram do właściciela projektu przy każdym zdarzeniu (ikona + podsumowanie + link GitHub)
• Feed w sidebarze Workspace ContextRail (polling co 30s, ostatnie 8 zdarzeń)

Szczegółowy przewodnik konfiguracji: GitHub Integration Setup.

Pamięć neuronowa

arc memory refresh

Pełna resynchronizacja wszystkich źródeł wiedzy projektu z NotebookLM.

arc memory refresh

Wynik:

Refreshing neural memory...
Synced: 12 | Errors: 0

Sources:
  - wiki/architecture.md
  - wiki/deploy-guide.md
  - issues/open

Timeout: 30 sekund (zwiększony ze względu na rozmiar synchronizacji).

arc memory fetch-artifact [--type <artifact_type>]

Pobierz artefakt z NotebookLM (przegląd audio itd.).

arc memory fetch-artifact                          # audio_overview domyślnie
arc memory fetch-artifact --type audio_overview    # jawne wskazanie typu

Timeout: 60 sekund.

Zmienne środowiskowe

Ustawiane automatycznie przy arc start, ale można je podać ręcznie do używania podkomend poza sesją.

Przykład ręcznego użycia (poza arc start):

export ARC_PROJECT=my-project
export ARC_SERVER_URL=https://arc-os.co
export ARC_TOKEN=eyJhbGciOiJIUzI1NiI...
arc issues
arc learnings

Monitorowanie sesji

Przy arc start automatycznie uruchamiany jest background watcher, który:

1. Znajduje nowy plik .jsonl w ~/.claude/projects/{normalized-cwd}/
2. Co 3 sekundy czyta nowe linie z transkryptu
3. Parsuje wiadomości user i assistant
4. Wysyła je na POST /api/cli/chat-log/:project (fire-and-forget)
5. Treść jest przycinana do 10 000 znaków na wiadomość

Watcher jest niekrytyczny — błędy są ignorowane, sesja działa dalej nawet gdy CRM jest niedostępny.

Przykłady użycia

Typowy przepływ pracy

# 1. Zaloguj się (jednorazowo)
arc login

# 2. Przejrzyj dostępne projekty
arc projects

# 3. Uruchom sesję
arc my-project dev

# --- Wewnątrz sesji Claude: ---

# 4. Przejrzyj otwarte zadania
arc issues

# 5. Utwórz nowe zadanie
arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"

# 6. Loguj postęp
arc issue log 42 "Started implementation"
arc issue log 42 "Toggle component ready, testing system preference detection"

# 7. Aktualizuj wiki
arc wiki update --file "architecture" --content "# Architecture\n\nUpdated with dark mode module..."

# 8. Aktualizuj roadmap
arc roadmap sync --phase 45 --status "IN PROGRESS"

# 9. Załaduj skill w razie potrzeby
arc skill crm-api-reference

# 10. Przejrzyj learnings
arc learnings

# 11. Zamknij zadanie
arc issue update 42 --status closed

# 12. Wyślij raport
arc report --summary "Implemented dark mode with system preference detection" \
  --files "theme.ts,App.tsx,DarkModeToggle.tsx" \
  --decisions "Used CSS custom properties for theming"

Synchronizacja pamięci

arc memory refresh
arc memory fetch-artifact --type audio_overview

Praca z wieloma projektami

# Sesja dla pierwszego projektu
arc project-alpha dev

# W innym terminalu — sesja dla drugiego
arc project-beta dev --role clceo

Timeouty