# Kommandozeile

Der Befehl `costfluent` führt jedes Tool des [MCP-Servers](/de/developers/mcp) aus einem Terminal, einem Skript oder einem CI-Job aus. Ein Befehl ist der Name des Tools mit Bindestrichen und nimmt die Argumente des Tools als Flags, sodass er genau das liest, was das Tool liest, mit derselben Prüfung der Berechtigung, derselben Validierung und demselben Ergebnis. Er gibt JSON für ein Skript und eine Tabelle für Sie aus. Der Befehl eines lesenden Tools liest nur; der Befehl eines schreibenden Tools legt an oder ändert, was das Tool tut, und erst, wenn ein Eigentümer KI-Agenten Objekte anlegen und ändern lässt ([die MCP-Seite](/de/developers/mcp) sagt, wie). Kein Befehl löscht etwas in Costfluent oder greift auf Ihre Cloud zu. `costfluent estimate`, unten beschrieben, sendet die Kostenschätzung eines Terraform-Pull-Requests aus jeder CI.

## Bevor Sie beginnen

<PlanAvailability feature="ApiTokens" plan="Pro" />

- Ein API-Token. Erstellen Sie es, wie es [Token erstellen](/de/developers/mcp#token-erstellen) in der Anleitung zum MCP-Server beschreibt, aus der Vorlage **Nur lesen**; ein CI-Job bekommt ein eigenes Token. Auf Ihrem eigenen Rechner können Sie sich stattdessen [anmelden](#anmelden).
- Ein Rechner mit macOS, Linux oder Windows, amd64 oder arm64.

## Installieren

Laden Sie das Archiv für Ihre Plattform aus dem [neuesten Release](https://github.com/costfluent/costfluent-mcp/releases/latest) herunter und legen Sie `costfluent` in Ihren `PATH`. Das Archiv enthält `costfluent` und den MCP-Server `costfluent-mcp`. Oder bauen Sie beide mit Go:

```bash
go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest
go install github.com/costfluent/costfluent-mcp/cmd/costfluent-mcp@latest
```

Jedes Release trägt eine Build-Provenance-Attestierung, die `gh attestation verify <archive> --repo costfluent/costfluent-mcp` prüft.

## Einen Befehl ausführen

<Stepper>

1. Setzen Sie `COSTFLUENT_API_TOKEN` auf das Token, oder [melden Sie sich an](#anmelden). `COSTFLUENT_BASE_URL` ist optional, standardmäßig `https://api.costfluent.com` und muss https verwenden.
2. Führen Sie `costfluent whoami` aus, um zu sehen, was die API über das Token sagt: seinen Namen, seinen Arbeitsbereich und seine Berechtigungen.
3. Führen Sie einen Befehl aus, etwa die Abfrage unten. `costfluent <command> --help` listet die Flags eines Befehls.

</Stepper>

```bash
export COSTFLUENT_API_TOKEN=<token>
costfluent whoami
costfluent query-costs --start-date 2026-10-01 --end-date 2026-10-31 --group-by ServiceName
costfluent list-budgets --output json | jq '.items[] | select(.state == "over")'
```

## Anmelden

Statt mit einem Token meldet `costfluent login` Sie über Ihren Browser an, wo Sie den Lesezugriff auf eine Organisation zulassen, wie [Mit einer App anmelden](/de/api/authentication#mit-einer-app-anmelden) beschreibt. Befehle laufen danach ohne `COSTFLUENT_API_TOKEN`; ein gesetztes Token hat weiter Vorrang. `costfluent logout` widerruft die Anmeldung und vergisst sie auf diesem Rechner, auch wenn der Widerruf Costfluent nicht erreicht.

```bash
costfluent login
costfluent whoami
costfluent logout
```

- Die Anmeldung liegt im Anmeldedatenspeicher des Betriebssystems: im macOS-Schlüsselbund, im Secret Service unter Linux oder in der Windows-Anmeldeinformationsverwaltung. Auf einem Rechner ohne einen solchen Speicher legt `costfluent login --insecure-storage` sie in `costfluent/credentials.json` unter `XDG_CONFIG_HOME` oder im Konfigurationsverzeichnis des Systems ab, nur für Sie lesbar, und ein Befehl lehnt die Datei ab, sobald andere sie lesen können. Ohne das Flag schlägt die Anmeldung dort fehl und widerruft, was sie erhalten hat.
- Die Seite, die sich öffnet, zeigt `costfluent login` als App, die Costfluent nicht geprüft hat und die nur zu Ihrem Rechner zurückkehrt, weil ihre Antwort an den Befehl auf diesem Rechner zurückgeht: Lassen Sie sie zu, wenn Sie den Befehl selbst ausgeführt haben.
- `--no-browser` gibt die Adresse zum Öffnen aus, statt Ihren Browser zu öffnen. `--timeout` legt fest, wie lange der Befehl auf Ihre Zustimmung wartet, etwa `--timeout 10m`; sonst wartet er 5 Minuten.
- `COSTFLUENT_BASE_URL` wählt die API wie bei jedem Befehl, und jede API behält ihre eigene Anmeldung.
- Ist die Anmeldung abgelaufen oder wurde sie widerrufen, endet ein Befehl mit 3 und bittet Sie, `costfluent login` erneut auszuführen.

## Befehle

| Befehl | Was er tut | Berechtigung |
|---|---|---|
| `costfluent list-workspaces` | Die Arbeitsbereiche, die das Token lesen kann | **Arbeitsbereiche anzeigen** |
| `costfluent query-costs` | Kosten, Nutzung oder Ressourcenanzahl über einen Zeitraum, nach bis zu drei Dimensionen gruppiert und durch einen Kostenfilter eingegrenzt | **Kosten anzeigen** |
| `costfluent list-cost-reports` | Die gespeicherten Kostenberichte eines Arbeitsbereichs | **Kostenberichte anzeigen** |
| `costfluent get-cost-report-data` | Die Zahlen, die ein gespeicherter Bericht jetzt zeigt | **Kosten anzeigen**, für einen Bericht mit einer Geschäftskennzahl auch **Kostenberichte anzeigen** |
| `costfluent list-annotations` | Die Anmerkungen eines Arbeitsbereichs nach Datum | **Kostenberichte anzeigen** |
| `costfluent list-budgets` | Budgets mit ihren aktuellen Ausgaben und ihrem Zustand | **Budgets anzeigen** |
| `costfluent list-anomalies` | Erkannte Kostenanomalien, die neuesten zuerst | **Anomalien anzeigen** |
| `costfluent list-savings-items` | Die Einsparpotenziale eines Arbeitsbereichs mit ihrer geschätzten monatlichen Einsparung und ihrem Status | **Einsparungen anzeigen** |
| `costfluent list-commitments` | Die Savings Plans, Reservierungen und Committed Use Discounts eines Arbeitsbereichs | **Kosten anzeigen** |
| `costfluent get-commitment-coverage` | Wie viel der dafür infrage kommenden Nutzung Commitments in einem Zeitraum abgedeckt haben | **Kosten anzeigen** |
| `costfluent get-kubernetes-efficiency` | Kosten, Leerlaufkosten sowie genutzte gegenüber angeforderter CPU und angefordertem Speicher je Cluster, Namespace oder Workload | **Kosten anzeigen** |
| `costfluent create-annotation` | Setzt eine Notiz an einem Datum an einen oder mehrere gespeicherte Kostenberichte | **Kostenberichte bearbeiten** |
| `costfluent create-cost-report` | Speichert einen neuen Kostenbericht | **Kostenberichte erstellen** |
| `costfluent update-cost-report` | Ändert einen gespeicherten Kostenbericht; was der Aufruf auslässt, bleibt, wie es ist | **Kostenberichte bearbeiten** |
| `costfluent create-budget` | Legt ein Budget an | **Budgets erstellen** |
| `costfluent update-budget` | Ändert ein Budget; was der Aufruf auslässt, seine Warnungen eingeschlossen, bleibt, wie es ist | **Budgets bearbeiten** |
| `costfluent create-cost-alert` | Legt eine Kostenwarnung an | **Kostenwarnungen verwalten** |
| `costfluent update-cost-alert` | Ändert eine Kostenwarnung; was der Aufruf auslässt, bleibt, wie es ist | **Kostenwarnungen verwalten** |
| `costfluent pause-cost-alert` | Pausiert eine Kostenwarnung | **Kostenwarnungen verwalten** |
| `costfluent resume-cost-alert` | Setzt eine pausierte Kostenwarnung fort | **Kostenwarnungen verwalten** |
| `costfluent create-dashboard` | Legt ein Dashboard an | **Dashboards erstellen** |
| `costfluent add-dashboard-widget` | Fügt einem Dashboard ein Widget hinzu | **Dashboards bearbeiten**, dazu **Kostenberichte anzeigen** |
| `costfluent acknowledge-anomaly` | Bestätigt eine erkannte Kostenanomalie | **Anomalien bestätigen** |
| `costfluent set-savings-item-status` | Setzt ein Einsparpotenzial auf **Angenommen**, **Umgesetzt** oder **Abgelehnt**, eine Ablehnung mit ihrem Grund | **Auf Einsparungen reagieren** |
| `costfluent assign-savings-item-owner` | Legt fest, wer für ein Einsparpotenzial verantwortlich ist | **Einsparungen verwalten** |
| `costfluent search-docs` | Durchsucht die Costfluent-Dokumentation auf Deutsch oder Englisch nach den Abschnitten, die eine Frage beantworten; braucht kein Token | Keine |
| `costfluent get-doc-page` | Gibt eine Seite der Costfluent-Dokumentation oder einen ihrer Abschnitte als Markdown aus; braucht kein Token | Keine |

Ein Flag ist das Argument des Tools mit Bindestrichen: Aus `start_date` von `query_costs` wird `--start-date`. Ein Flag, das eine Liste nimmt, etwa `--group-by`, geben Sie für jeden Wert einmal an.

<FeatureStatus feature="CommitmentCoverage" />

`costfluent list-commitments` und `costfluent get-commitment-coverage` lesen die Commitments, die die Verbindungen eines Arbeitsbereichs halten, und wie viel der infrage kommenden Nutzung sie abgedeckt haben.

## Einen Assistenten verbinden

`costfluent mcp install` gibt den Eintrag aus, der `costfluent-mcp` in Ihrem Assistenten startet, oder fügt ihn mit `--write` der Konfigurationsdatei des Assistenten hinzu.

<Stepper>

1. Führen Sie `costfluent mcp install --client <client>` mit `claude-code`, `cursor`, `codex`, `vscode` oder `copilot` aus und prüfen Sie den ausgegebenen Eintrag.
2. Führen Sie den Befehl erneut mit `--write` aus, um den Eintrag der Datei hinzuzufügen, die die Tabelle unten nennt. Mit `--project` schreibt er stattdessen die Projektdatei von Cursor oder Codex im aktuellen Verzeichnis.
3. Starten Sie den Assistenten neu, aus einer Shell, in der `COSTFLUENT_API_TOKEN` gesetzt ist.

</Stepper>

| Client | Datei |
|---|---|
| `claude-code` | `.mcp.json` im aktuellen Verzeichnis |
| `cursor` | `~/.cursor/mcp.json`, mit `--project` `.cursor/mcp.json` |
| `codex` | `~/.codex/config.toml`, mit `--project` `.codex/config.toml` |
| `vscode` | `.vscode/mcp.json` im aktuellen Verzeichnis |
| `copilot` | `~/.copilot/mcp-config.json`, oder `mcp-config.json` in `COPILOT_HOME` |

:::note
Der Eintrag enthält das Token nur, wenn Sie es verlangen. Claude Code, Cursor, Codex und Copilot CLI lesen es aus `COSTFLUENT_API_TOKEN` in ihrer eigenen Umgebung, und VS Code fragt beim ersten Start des Servers danach. Mit `--write --embed-token` enthält der Eintrag stattdessen das Token aus `COSTFLUENT_API_TOKEN`, für einen Assistenten, der ohne diese Variable startet, und nur Sie können die Datei dann lesen: Halten Sie sie aus der Versionskontrolle heraus, und widerrufen Sie das Token, wenn Sie den Assistenten nicht mehr nutzen. Ein aus dem Dock gestartetes Cursor sieht die Variablen Ihrer Shell nicht: Starten Sie es aus einer Shell, oder lassen Sie `envFile` im Eintrag auf eine Datei zeigen, die die Variable setzt. Ein ohne die Variable gestartetes Claude Code gibt dem Server den Text `${COSTFLUENT_API_TOKEN}` statt eines Tokens, den die API ablehnt.
:::

## Kostenschätzungen aus der CI senden

`costfluent estimate submit` sendet die Schätzung, die Infracost für einen Terraform-Pull-Request erstellt, an Costfluent, und `costfluent estimate apply` hält fest, dass die Änderung angewendet wurde, mit den IDs, die Terraform den erstellten oder ersetzten Ressourcen gegeben hat. Mit diesen IDs findet Costfluent jede Ressource in Ihren Abrechnungsdaten und vergleicht die Schätzung mit den Kosten, die folgten. Die beiden Befehle tun aus jeder CI, was die Kostenschätzungs-Action von Costfluent in GitHub Actions tut, und wandeln das JSON von Infracost und Terraform mit den Programmen der Action selbst um, sodass beide dieselbe Schätzung senden.

<Stepper>

1. Öffnen Sie **Einstellungen**, dann **API-Token**, und wählen Sie **API-Token erstellen**. Wählen Sie unter **Zugriff** den Arbeitsbereich, zu dem die Schätzungen gehören, und unter **Vorlage** die Vorlage **Nur lesen**; entfernen Sie dann jede Berechtigung und wählen Sie **Kostenschätzungen übermitteln**, die einzige, die die Befehle brauchen.
2. Speichern Sie das Token als maskiertes Secret der Pipeline und geben Sie es dem Job als `COSTFLUENT_API_TOKEN`. Kein Flag nimmt das Token.
3. Schreiben Sie im Job, der bei Merge Requests oder Pull Requests läuft, den Vergleich von Infracost als JSON (`infracost diff --format json` mit Infracost v0.10, `infracost diff --json` mit Infracost v2) und den gespeicherten Plan mit `terraform show -json`, und führen Sie dann `costfluent estimate submit` aus.
4. Wenden Sie im Job, der die gemergte Änderung anwendet, den gespeicherten Plan an, schreiben Sie den Plan und dann den Zustand mit `terraform show -json` und führen Sie `costfluent estimate apply` mit der Nummer des gemergten Pull Requests aus.

</Stepper>

| Flag | Was es nimmt |
|---|---|
| `--workspace-id` | Den Arbeitsbereich, zu dem die Schätzung gehört; erforderlich |
| `--repository` | Das Repository, etwa `acme/infra`; erforderlich |
| `--pull-request` | Die Nummer des Pull Requests oder Merge Requests; erforderlich |
| `--infracost-json` | Für `submit` das JSON von Infracost; erforderlich |
| `--terraform-plan-json` | `terraform show -json` des gespeicherten Plans: optional für `submit`, wo es jeder geänderten Ressource die IDs gibt, über die Costfluent ihre Kosten misst, und erforderlich für `apply` |
| `--terraform-state-json` | Für `apply` `terraform show -json` des Zustands nach dem Anwenden; erforderlich |
| `--commit`, `--url`, `--infracost-version` | Für `submit` den Commit, einen https-Link zum Pull Request und die Version von Infracost, die mit der Schätzung gespeichert werden |
| `--fail-above` | Für `submit` den Höchstwert der geplanten monatlichen Änderung in der Währung der Schätzung |

### GitLab CI

Dieser Job läuft bei Merge Requests, nach einem Job `plan`, der `infracost.json` und `plan.json` als Artefakte behält. `COSTFLUENT_API_TOKEN` ist eine maskierte CI/CD-Variable.

```yaml
cost-estimate:
  image: golang:1.27.4
  needs: [plan]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest
    - >-
      costfluent estimate submit
      --workspace-id wsp_8f3k2m
      --repository "$CI_PROJECT_PATH"
      --pull-request "$CI_MERGE_REQUEST_IID"
      --infracost-json infracost.json
      --terraform-plan-json plan.json
      --commit "$CI_COMMIT_SHA"
      --url "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID"
      --fail-above 500
```

### Azure Pipelines

Diese Pipeline läuft bei Pull Requests in Azure Repos, die eine Richtlinie zur Buildvalidierung auf dem Zielbranch startet. `COSTFLUENT_API_TOKEN` ist eine geheime Pipelinevariable, die ein Schritt nur sieht, wenn sein `env` sie zuordnet.

```yaml
trigger: none

pool:
  vmImage: ubuntu-24.04

steps:
  - task: GoTool@0
    inputs:
      version: 1.27.4
  - script: |
      go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest
      echo "##vso[task.prependpath]$HOME/go/bin"
    displayName: Install costfluent
  # Run Terraform and Infracost here, writing plan.json and infracost.json.
  - script: >-
      costfluent estimate submit
      --workspace-id wsp_8f3k2m
      --repository "$(Build.Repository.Name)"
      --pull-request "$(System.PullRequest.PullRequestId)"
      --infracost-json infracost.json
      --terraform-plan-json plan.json
      --commit "$(System.PullRequest.SourceCommitId)"
      --fail-above 500
    displayName: Post the cost estimate
    env:
      COSTFLUENT_API_TOKEN: $(COSTFLUENT_API_TOKEN)
```

### Das Anwenden festhalten

Nachdem die gemergte Änderung aus ihrem gespeicherten Plan angewendet ist, in jeder CI:

```bash
terraform show -json tfplan > plan.json
terraform apply -input=false tfplan
terraform show -json > state.json
costfluent estimate apply --workspace-id wsp_8f3k2m --repository acme/infra --pull-request 42 \
  --terraform-plan-json plan.json --terraform-state-json state.json
```

- `submit` erstellt die Schätzung des Pull Requests beim ersten Senden und ersetzt sie bei jedem weiteren, bis die Änderung angewendet ist. Ein Vergleich, der keine bepreiste Ressource ändert, sendet nichts, und der Befehl endet mit 0.
- Beide Befehle geben die Quittung der Schätzung aus: ihre ID und ihren Zustand und, von `submit`, die geplanten monatlichen Kosten vorher und nachher, die Änderung und wie viele Ressourcen Infracost nicht bepreisen konnte, wie Costfluent sie in der Währung der Schätzung berechnet hat. Eine Zeile auf stderr sagt, ob die Schätzung erstellt oder aktualisiert wurde.
- `--fail-above` wird geprüft, nachdem die Quittung ausgegeben ist, und vergleicht die exakten Beträge: Eine Änderung gleich `--fail-above` besteht, eine Änderung darüber endet mit 4, und eine negative Änderung nie. Antwortet Costfluent ohne die geplanten Summen, sagt eine Warnung, dass `--fail-above` nicht angewendet wird, und der Befehl endet mit 0, statt jeden Pull Request an einer Änderung scheitern zu lassen, die er nicht lesen kann.
- `apply` warnt vor jeder Ressource, die der Plan erstellt oder ersetzt hat und für die der Zustand keine ID enthält, und lässt sie weg. Ein Pull Request ohne Schätzung im Arbeitsbereich hat nichts anzuwenden: Der Befehl sagt es mit dem Grund der API und endet mit 0.
- Ein falsches oder fehlendes Flag oder eine Eingabedatei, die kein JSON ist, endet mit 2, bevor eine Anfrage gesendet wird.

## Wie es sich verhält

- Ein Befehl gibt JSON aus, wenn seine Ausgabe in eine Datei, eine Pipe oder ein CI-Log geht, und eine Tabelle, wenn sie in ein Terminal geht; `--output json` oder `--output table` legt es fest. Beträge behalten jede Stelle, die die API sendet.
- Ein Befehl endet mit 0, wenn er erfolgreich war, mit 1, wenn der Aufruf fehlschlug, mit 2, wenn die Kommandozeile falsch ist, mit 3, wenn das Token fehlt, abgelehnt wird oder die Berechtigung nicht trägt, die der Befehl braucht, bevor der Befehl etwas liest, und mit 4, wenn ein von Ihnen gesetzter Schwellenwert überschritten wurde, wie ihn `costfluent estimate submit --fail-above` setzt.
- Ein Fehler geht nach stderr: der Fehler der API als JSON, mit Status, Code, Detail und Trace-ID, wenn stderr kein Terminal ist, und eine Zeile, wenn es eines ist.
- Eine Liste liefert eine Seite, wie das Tool; das Ergebnis nennt die nächste Seite, die `--page` liest.
- Jeder Befehl zählt gegen das Anfragelimit des Tokens und wartet ein kurzes Limit ab, wie es der MCP-Server tut.
- Eine Tabelle schreibt Steuerzeichen in Namen, Titeln und Tag-Werten als Escape-Folgen, denn Ihre Nutzer und Ihre Cloud-Konten schreiben sie, und ein Terminal würde sie ausführen.
- Kein Befehl gibt das Token aus, und `costfluent mcp install` schreibt es nur mit `--embed-token` in eine Datei, das `--write` voraussetzt.
- `--write` behält jeden anderen Server in der Datei und lehnt eine Datei ab, die schon einen Eintrag `costfluent` hat, sofern `--force` ihn nicht ersetzt. Eine Datei, die es nicht als reines JSON lesen kann, etwa eine mit Kommentaren, lässt es unverändert.

## Verwandte Seiten

- [MCP-Server](/de/developers/mcp)
- [API-Authentifizierung](/de/api/authentication)
- [API-Referenz](/api)