Arbeiten mit der Grepture CLI: Lokale Sessions

Du kannst nicht beheben, was du nicht siehst

Du iterierst an einem Prompt. Du aenderst eine Tool-Definition. Du wechselst das Modell. Das einzige Feedback, das du bekommst, ist die Antwort des Modells — und am Monatsende eine ueberraschende Rechnung. Du siehst die Requests nicht. Du siehst nicht, wann die Redaktion greift. Eine ausser Kontrolle geratene Tool-Schleife bemerkst du erst, wenn sie dich schon 40 Dollar gekostet hat.

Die Grepture CLI behebt diesen Dev-Loop mit einem einzigen Kommando. Sie oeffnet ein lokales AI-Gateway auf deinem Rechner, leitet deinen Traffic hindurch und zeigt jeden Request live im Terminal. Dieser Beitrag fuehrt durch den kompletten Workflow — einloggen, Session starten, SDK verbinden und den Traffic beobachten.

Installiere die CLI von npm:

npm install -g @grepture/cli

Dann authentifizieren:

grepture login

Das startet einen browserbasierten Device-Code-Flow. Die CLI zeigt einen kurzen User-Code an, oeffnet deinen Browser und pollt, bis du bestaetigst. Sobald das passiert ist, landet dein Token in ~/.grepture/credentials (Modus 0600) und du bist startklar.

Auf einer headless Maschine oder in CI ueberspringst du den Browser:

grepture login --token <dein-api-token>

Du musst das nur einmal pro Rechner machen. Die CLI haelt dich angemeldet, bis du grepture logout ausfuehrst.

Schritt 2: Eine Session starten

Das ist der Kern:

grepture dev

Dieses eine Kommando macht mehrere Dinge gleichzeitig. Es legt einen Session-Eintrag in Grepture Cloud an (damit das Dashboard davon weiss). Es startet einen lokalen Proxy auf localhost:8787. Und es beginnt zu pollen, um Log-Eintraege in dein Terminal zu schreiben.

Du siehst einen Header wie diesen:

  Grepture Dev Session
  ─────────────────────────────────────────
  Session:    d7150823...
  Proxy:      http://localhost:8787
  Target:     https://api.openai.com
  Dashboard:  https://app.grepture.com/sessions/d7150823...
  Expires:    6.5.2026, 19:23:14
  ─────────────────────────────────────────
  Waiting for requests...

Ein paar nuetzliche Flags:

--port 9000, falls 8787 schon belegt ist.
--target https://api.anthropic.com, um standardmaessig Anthropic statt OpenAI als Upstream zu nutzen. Pro Request kannst du das auch ueber den Header x-grepture-target ueberschreiben.
--name "qa-agent", um die Session im Dashboard zu beschriften und spaeter wiederzufinden.

Sessions sind absichtlich zeitlich begrenzt. Nach 5 Minuten ohne Traffic markiert die CLI die Session als idle. Nach 15 Minuten ohne Traffic trennt sie sich automatisch und raeumt auf. Du kannst von deinem Laptop weggehen, ohne Zombie-Sessions zu hinterlassen.

Schritt 3: SDK verbinden

Dein Code auf den lokalen Proxy zu zeigen ist eine Aenderung in einer Zeile. Fuer das OpenAI SDK in TypeScript:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:8787/proxy",
  apiKey: process.env.OPENAI_API_KEY,
});

const res = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello, world." }],
});

Oder per Umgebungsvariable, ganz ohne Code-Aenderung:

export OPENAI_BASE_URL=http://localhost:8787/proxy

Gleiche Idee fuer das Anthropic SDK in Python — starte grepture dev --target https://api.anthropic.com und setze die Base URL des Clients auf http://localhost:8787/proxy:

from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:8787/proxy")

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "Hello, world."}],
)

Dein Provider-API-Key reist weiterhin mit dem Request — die CLI leitet ihn als x-grepture-auth-forward-Header weiter, sodass der Upstream dieselbe Authentifizierung sieht wie immer. Den Proxy-Hop authentifiziert Grepture separat mit dem API-Key, der zu deinem Account gehoert.

Das ist die komplette Verkabelung. Kein SDK-Rewrite, keine separate Test-Umgebung, kein Fork in deinem Code.

Schritt 4: Traffic live mitlesen

Jetzt loest deine App einen Request aus. Das Terminal mit grepture dev druckt fuer jeden eine Zeile:

  19:47:30  POST   200  gpt-4o          1.204ms  12.430 tok  /v1/chat/completions
  19:47:45  POST   403  gpt-4o             89ms      BLOCKED  /v1/chat/completions
  19:48:01  POST   200  gpt-4o          2.105ms  45.230 tok  /v1/chat/completions

Zeit, Methode, Status, Modell, Latenz, Tokens (oder BLOCKED, wenn eine Regel den Call abgelehnt hat) und der Endpoint-Pfad — fuer jeden Request, in Echtzeit. Gelbe Statuscodes bedeuten, dass eine Regel gefeuert hat, der Request aber durchgelaufen ist (z. B. wurde PII vor dem Modell geschwaerzt). Rote Codes stehen fuer Fehler oder Blocks.

Dieser Live-Feed veraendert die Art, wie du arbeitest. Du raetst nicht mehr, warum das Modell etwas Seltsames zurueckgegeben hat — du siehst den Request, der das ausgeloest hat. Token-Zaehlungen ueberraschen dich nicht mehr, weil sie direkt neben jedem Call stehen. Einen Agenten, der das falsche Modell gewaehlt hat, erwischst du in dem Moment, in dem es passiert, nicht erst, wenn die Rechnung kommt.

Fuer tiefere Inspektion — komplette Request- und Response-Bodies, Redaktions-Details, Regel-Traces — fuehrt die beim Start gedruckte Dashboard-URL direkt zur Session-Ansicht auf app.grepture.com. Das Terminal liefert die Vogelperspektive. Das Dashboard ist fuer die Obduktion.

Wenn du Traffic ohne aktive Session anschauen willst, holt grepture logs aktuelle Eintraege aus der Cloud:

grepture logs --since 1h --status 4xx -n 50

Es unterstuetzt --search, --method, --status (2xx/4xx/5xx), --since (30m, 1h, 1d) und -n als Limit. Praktisch, wenn du etwas aus der Session von gestern nachlesen willst, ohne das Terminal zu verlassen.

Fuer den groesseren Observability-Kontext und warum wir das Gateway so gebaut haben, siehe Trace Mode und Observability ohne Latenz.

Es gibt noch mehr in der CLI

Dieser Beitrag bleibt absichtlich beim lokalen Session-Workflow, weil das der Einstieg fuer die meisten Leute ist. Die CLI kann mehr — sie scannt deine Codebase nach PII und hardcoded Secrets, installiert einen Pre-Commit-Hook, der schlechte Commits blockiert, gibt SARIF fuer GitHub Code Scanning in CI aus und synchronisiert Erkennungsregeln zwischen deinem Team und der Cloud. Der Beitrag Introducing the Grepture CLI deckt all das ab, und der Docs-Quickstart hat die Referenz. Der Quellcode liegt auf GitHub.

Wenn du einen Coding-Assistant durch Grepture leitest statt deiner eigenen App, funktioniert dieselbe grepture dev-Session — siehe Claude Code und Cursor fuer die Tool-spezifische Konfiguration.