Cursor CLI verwenden: Schritt-für-Schritt-Anleitung

Um Cursor CLI zu verwenden, installierst du sie mit curl https://cursor.com/install -fsS | bash, meldest dich mit agent login an, wechselst in einen Projektordner und startest agent. Du beschreibst eine Aufgabe; der Agent von Cursor liest deinen Code, bearbeitet Dateien und führt Befehle aus, nachdem du sie freigegeben hast. Für Skripte und CI führt agent -p "deine Aufgabe" einen einzelnen Prompt ohne interaktive Oberfläche aus.

Das ist der Grundablauf. Diese Anleitung behandelt den Rest: die drei Modi, den Print-Modus, Modelle, Regeldateien, MCP-Server, Berechtigungen, wie die CLI vom Kontingent deines Cursor-Plans zehrt, ihre Grenzen und wie sie neben anderen Coding-CLIs läuft. Alles hier basiert auf der offiziellen Cursor-Dokumentation, Stand Oktober 2026.

Was Cursor CLI ist

Cursor CLI bringt den Agenten aus dem Cursor-Editor ins Terminal. Sie nutzt dasselbe Konto, dieselben Modelle, dieselben Regeln und dieselben MCP-Einstellungen wie der Editor; arbeitet dein Team schon mit Cursor, verhält sich die CLI also so, wie alle es erwarten. Sie läuft überall, wo es ein Terminal gibt: auf einem Server per SSH, auf einem CI-Runner oder in einem Bereich neben einem anderen Agenten.

Ein Hinweis zum Namen: Der Befehl hieß früher cursor-agent. Im Januar 2026 hat Cursor agent zum Hauptbefehl gemacht; cursor-agent funktioniert als Alias weiter. Ältere Anleitungen und Tools, die cursor-agent aufrufen, brechen also nicht. Diese Anleitung verwendet agent.

Falls du noch zwischen Cursor und einem Terminal-first-Agenten abwägst, vergleicht Claude Code vs. Cursor die beiden. Dieser Beitrag geht davon aus, dass du dich für Cursor entschieden hast und es aus dem Terminal nutzen willst.

Schritt 1: Cursor CLI installieren

Installation prüfen:

agent --version

Findet deine Shell agent nicht, füge ~/.local/bin zu deinem PATH hinzu und öffne ein neues Terminal. Die CLI aktualisiert sich standardmäßig selbst; manuell geht es mit agent update.

Schritt 2: Anmelden

agent login     # öffnet den Browser
agent status    # zeigt, mit welchem Konto du angemeldet bist
agent logout

Auf einem Rechner ohne Browser setzt du NO_OPEN_BROWSER=1; dann gibt agent login die URL aus, statt sie zu öffnen. Für CI und Skripte erstellst du im Cursor-Dashboard unter API Keys einen API-Schlüssel und übergibst ihn über die Umgebungsvariable CURSOR_API_KEY oder mit --api-key.

Schritt 3: Interaktive Sitzung

Starte den Agenten in einem Projekt, mit oder ohne ersten Prompt:

cd my-project
agent
agent "add input validation to the signup form"

Die CLI hat drei Modi, und Shift+Tab schaltet zwischen ihnen um:

Eine gute Gewohnheit für alles, was nicht trivial ist: im Plan-Modus anfangen, sich auf den Ansatz einigen, dann in den Agent-Modus wechseln und umsetzen lassen. Ein paar Dinge, die du täglich brauchst:

• @ wählt Dateien aus, die an deine Nachricht angehängt werden.
• Ctrl+R zeigt die Änderungen des Agenten zur Durchsicht.
• Shift+Enter (oder Ctrl+J) fügt einen Zeilenumbruch ein; Pfeil nach oben blättert durch frühere Nachrichten.
• Shell-Befehle warten vor der Ausführung auf ein y/n.
• /model wechselt das Modell; /clear startet einen frischen Chat; /summarize fasst einen langen Chat zusammen.
• Zweimal Ctrl+D beendet die Sitzung.

Chats werden gespeichert. agent ls listet sie auf, agent resume (oder --continue) springt zum letzten zurück, und --resume="chat-id" öffnet einen bestimmten. In der Sitzung tun /resume, /fork und /rewind, was ihre Namen sagen.

Zwei Extras lohnen sich. Stellst du einer Nachricht & voran, wird das Gespräch an einen Cursor Cloud Agent übergeben, der weiterarbeitet, während du weg bist; unter cursor.com/agents machst du dort weiter. Und -w (oder --worktree name) lässt den Agenten in einem neuen Git-Worktree unter ~/.cursor/worktrees/ laufen, sodass deine aktuelle Arbeitskopie unberührt bleibt.

Schritt 4: Print-Modus für Skripte und CI

Der Print-Modus führt einen einzelnen Prompt aus und beendet sich. So kannst du die CLI aus Skripten, Git-Hooks und CI-Pipelines nutzen:

# Eine nur lesende Frage, Antwort als Klartext
agent -p "summarize what changed in src/billing since the last release"

# Änderungen anwenden (ohne --force werden sie nur vorgeschlagen)
agent -p --force "add JSDoc comments to every exported function in src/utils"

# Maschinenlesbare Ausgabe für ein anderes Tool
agent -p --output-format json "list the TODO comments in this repo"

Die Flags, auf die es hier ankommt:

• --force (Alias --yolo) erlaubt dem Agenten, ohne Nachfrage Dateien zu schreiben und Befehle auszuführen, sofern keine Deny-Regel das blockiert. Das ist der Schalter, mit dem der Print-Modus tatsächlich etwas ändert.
• --output-format akzeptiert text (Standard), json oder stream-json. Kombiniere stream-json mit --stream-partial-output, um Text schon beim Entstehen zu erhalten.
• --trust vertraut dem Arbeitsbereich ohne Nachfrage; --approve-mcps gibt konfigurierte MCP-Server frei.
• --model und --workspace legen Modell und Ordner fest.

Cursor dokumentiert auch den Einsatz der CLI in GitHub Actions. Wenn du --force in CI nutzt, behandle es wie jeden unbeaufsichtigten Agenten: ein eng begrenzter API-Schlüssel, ein Wegwerf-Runner und Änderungen, die zur Prüfung auf einem Branch landen.

Schritt 5: Ein Modell wählen

agent models                   # Modelle, die dein Konto nutzen kann
agent --model <model-id>       # mit einem bestimmten Modell starten

In der Sitzung öffnet /model die Modellauswahl, und /model grok filtert die Liste. Gibst du kein Modell an, nutzt die CLI das in deinem Konto eingestellte. Welche Modelle du siehst, hängt von deinem Plan ab (siehe den Abschnitt zu Preisen unten): Jeder bezahlte Plan enthält Cursors eigene Modelle, Drittanbietermodelle brauchen Premium oder höher.

Schritt 6: Regeln, AGENTS.md und CLAUDE.md

Cursor CLI nutzt dasselbe Regelsystem wie der Editor. Regeln liegen in .cursor/rules, und die CLI liest außerdem AGENTS.md und CLAUDE.md im Projektstamm und wendet sie ebenfalls als Regeln an. Seit dem Release von Oktober 2026 greifen AGENTS.md-Dateien in Unterordnern, wenn der Agent Dateien in diesen Ordnern bearbeitet.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- Never edit files in src/generated/.

Arbeiten mehrere Agenten im selben Repo, ist AGENTS.md die Datei, die alle lesen, und damit der richtige Ort für gemeinsame Regeln. agent generate-rule erstellt interaktiv eine neue Cursor-Regel. Was in diese Dateien gehört, erklärt CLAUDE.md und AGENTS.md schreiben.

Schritt 7: MCP-Server

MCP-Server geben dem Agenten neue Werkzeuge: einen Browser, einen Issue-Tracker, eine Datenbank. Cursor CLI liest dieselbe mcp.json wie der Editor: .cursor/mcp.json für das Projekt und ~/.cursor/mcp.json für alle Projekte. Was du im Editor eingerichtet hast, steht also auch in der CLI bereit.

agent mcp list                 # konfigurierte Server und ihr Status
agent mcp list-tools <id>      # die Werkzeuge eines Servers
agent mcp login <id>           # Anmeldung bei einem Server mit OAuth
agent mcp disable <id>         # abschalten, ohne ihn zu entfernen

In der Sitzung zeigt /mcp list dasselbe an. Jeder Server bringt seine Werkzeuge in den Kontext des Agenten, also lass nur die eingeschaltet, die du brauchst.

Schritt 8: Berechtigungen und Konfiguration

Globale Einstellungen liegen in ~/.cursor/cli-config.json (unter Windows %USERPROFILE%\.cursor\cli-config.json). Ein Projekt kann eine .cursor/cli.json mitbringen, die nur Berechtigungen enthält. Beide sind reines JSON ohne Kommentare.

{
  "permissions": {
    "allow": ["Shell(git)", "Shell(ls)", "Read(src/**/*.ts)", "Write(package.json)", "Mcp(datadog:*)"],
    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
  }
}

Jeder Eintrag nennt ein Werkzeug und ein Muster: Shell(...), Read(...), Write(...), WebFetch(domain) und Mcp(server:tool). Deny schlägt Allow. Die globale Datei legt außerdem den Freigabemodus fest (allowlist, auto-review oder unrestricted), dazu Sandbox-Einstellungen und ob Commits eine „Made with Cursor“-Zeile bekommen.

Wie Cursor CLI mit deinem Cursor-Plan zusammenhängt

Es gibt kein eigenes CLI-Abo. Die CLI nutzt dein Cursor-Konto, und Stand Oktober 2026 wird Cursor als Teil von The X Subscription verkauft, zusammen mit Grok und X. Jeder bezahlte Plan hat ein gemeinsames Nutzungskontingent für Cursors eigene Modelle (Grok 4.7, Grok 4.6, Grok 4.5 und Composer 2.5). Editor, CLI, Cloud Agents und die Grok-Apps zehren alle davon, und es erneuert sich wöchentlich.

Was das für die Nutzung der CLI bedeutet:

• Modelle zehren unterschiedlich schnell vom Kontingent. Restnutzung und nächstes Erneuerungsdatum siehst du in den Editor-Einstellungen und im Nutzungs-Dashboard.
• Claude, GPT und Gemini sind nicht im Kontingent enthalten. Ab Premium zahlst du sie ab der ersten Anfrage zum API-Listenpreis aus Prepaid-Guthaben. Plus und Free können sie nicht nutzen.
• Plus hat keine Cloud Agents und kein Auto. Die Übergabe an einen Cloud Agent mit & braucht Premium oder höher.
• Ältere Pläne laufen weiter. Pro, Pro+, Ultra, Start sowie Teams-Standard- und -Premium-Plätze gelten als Legacy-Pläne und behalten ihre zwei monatlichen Kontingente und die nutzungsbasierte Abrechnung.

Grenzen, die du kennen solltest

• Shell Mode hat ein Timeout von 30 Sekunden. /shell führt Befehle direkt aus, kann aber keine dauerhaft laufenden Server oder interaktive Eingaben ausführen, und cd bleibt zwischen Befehlen nicht erhalten.
• Der Print-Modus ist standardmäßig vorsichtig. Ohne --force schlägt er Änderungen vor, statt sie zu schreiben; das überrascht beim ersten Mal die meisten.
• Konfigurationsdateien sind striktes JSON. Ein Kommentar oder ein überzähliges Komma in cli-config.json macht die Datei ungültig.
• Ein Chat pro Terminal. Die CLI hat Worktrees und Cloud Agents, aber keine eingebaute Ansicht, die mehrere lokale Agenten gleichzeitig zeigt.

Häufige Stolperfallen

• command not found: agent. ~/.local/bin fehlt in deinem PATH.
• Ein Tool ruft noch cursor-agent auf. Kein Problem, der Alias bleibt. Nur die Doku ist auf agent umgestiegen.
• Das gewünschte Modell fehlt in der Liste. Es ist ein Drittanbietermodell, und dein Plan ist Free oder Plus.
• Regeln werden ignoriert. Prüfe, ob AGENTS.md oder CLAUDE.md im Projektstamm liegt oder ob die Regel in .cursor/rules für die bearbeiteten Dateien gilt.
• CI hängt an einer Freigabeabfrage. Füge --trust hinzu, nutze CURSOR_API_KEY und gib --approve-mcps mit, wenn MCP-Server konfiguriert sind.

Cursor CLI neben anderen CLIs betreiben

Lebt dein Team schon in Cursor, ist Cursor CLI eine gute Wahl: dieselben Modelle, Regeln und MCP-Server im Editor und im Terminal. Willst du tiefe Erweiterungspunkte im Terminal wie Hooks, Skills und Plugins, ist Claude Code dort stärker. Und wenn du Cursor ganz verlassen willst, stellt Die besten Cursor-Alternativen die Optionen ehrlich vor.

Viele landen am Ende dabei, Cursor CLI neben Claude Code, Codex oder Gemini CLI laufen zu lassen, jeden an einer eigenen Aufgabe. In einfachen Terminals heißt das: ein Tab pro Agent und -w-Worktrees, um sie auseinanderzuhalten. AgentVera ist eine Desktop-App, die diese CLIs nebeneinander in echten Terminals ausführt, mit deinen eigenen Installationen und Anmeldungen. Die Cursor-Unterstützung funktioniert so:

• Jeder Agent bekommt seinen eigenen Chat. Für jeden neuen Cursor-Agenten wird ein leerer Chat angelegt (cursor-agent create-chat), und der Agent kehrt immer zu ihm zurück; so arbeiten mehrere Cursor-Agenten im selben Projekt, ohne sich in die Quere zu kommen. Der Cursor-Editor muss nicht geöffnet sein.
• Deine Anmeldung, deine Modelle. Es wird die eigene Anmeldung von Cursor CLI verwendet; bleibt das Modell leer, gilt das Modell aus den Cursor-Einstellungen.
• Regeln statt Rollen-Prompt. Cursor CLI hat kein Flag für zusätzliche Anweisungen, daher erreicht das Rollenfeld des Agenten Cursor nicht. Dauerhafte Anweisungen gehören in AGENTS.md oder Regeldateien.
• MCP an einer Stelle. In AgentVera hinzugefügte MCP-Server und der Browser von AgentVera werden als lokales Plugin eingebunden und für den Lauf freigegeben.
• Raster, Konten und Server. Lass Cursor im Workspace-Raster neben anderen Agenten laufen, mit automatischem Code-Review, sobald ein Durchgang endet. Unter Einstellungen → Konten kannst du mehrere Cursor-Konten als Ausweichreihenfolge hinterlegen, und ein Cursor-Agent kann auch auf einem gespeicherten SSH-Server laufen.

Zum Ausprobieren: AgentVera herunterladen.

Zusammengefasst

Um Cursor CLI zu verwenden, installierst du sie, führst agent login aus und startest agent in einem Projekt. Wechsle vor größeren Änderungen mit Shift+Tab in den Plan-Modus, nutze agent -p --force in Skripten und halte Regeln in AGENTS.md oder .cursor/rules und Werkzeuge in mcp.json. Wie weit deine Nutzung reicht, bestimmt dein Cursor-Plan; wähle Modelle also mit Blick auf das wöchentliche Kontingent.