---
title: CLI | RunAPI
description: Jeden RunAPI-CLI-Befehl für Modellaktionen, Tasks, Dateien, Uploads,
  Kontoinformationen, Preise, Callbacks und Harness installieren und verwenden.
url: https://runapi.ai/de/docs/resources/cli.md
canonical: https://runapi.ai/de/docs/resources/cli
locale: de
---

> HTML-Version: https://runapi.ai/de/docs/resources/cli
> Website-Index für KI-Agenten: https://runapi.ai/llms.txt

# CLI

Die RunAPI CLI ist ein JSON-orientierter Terminal-Client für Modellaktionen und
Konto-Werkzeuge. Sie schreibt Ergebnisdaten auf die Standardausgabe und
operativen Fortschritt auf die Standardfehlerausgabe und eignet sich gleichermaßen
für Terminals, Shell-Skripte, CI-Jobs und Harness.

## Installieren

Das aktuelle Release auf Linux oder macOS installieren:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh
```

Homebrew- und Go-Quellinstallationen sind ebenfalls verfügbar:

```shell
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
```

Laden Sie unter Windows das passende `windows-amd64`- oder `windows-arm64`-Archiv aus dem [neuesten CLI-Release][1] herunter, extrahieren Sie `runapi.exe` und fügen Sie es zum `PATH` hinzu.



[1]: https://github.com/runapi-ai/cli/releases/latest

Fixieren Sie den Installer auf eine Version oder ein Installationsverzeichnis, wenn eine
Deployment eine reproduzierbare Binärdatei erfordert:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.13.1
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir "$HOME/.local/bin"
```

Das Installationsskript akzeptiert außerdem `RUNAPI_VERSION`, `RUNAPI_INSTALL_DIR`,
`RUNAPI_INSTALL_BASE`, `RUNAPI_DOWNLOAD_BASE` und
`RUNAPI_SKIP_LIBC_CHECK=1`.

## Schnellstart

Melden Sie sich auf einer Workstation im Browser an und bestätigen Sie die Anmeldeinformationsquelle:

```shell
runapi login
runapi auth status
```

Eine Modell-Aktion mit einer inline JSON-Eingabe oder einer JSON-Datei ausführen:

```shell
runapi nano-banana text-to-image --input '{"prompt":"a hummingbird drinking espresso","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.json
```

Die meisten Modellaktionen sind asynchron. Sie warten standardmäßig auf ein Ergebnis im Endzustand; fügen Sie `--async` hinzu, um den Task sofort zurückzugeben und später `wait` zu verwenden:

```shell
TASK_ID=$(runapi suno text-to-music --async --input '{"model":"suno-v5","vocal_mode":"instrumental","style":"minimal piano","title":"Short Piano Theme"}' | jq -r '.id')
runapi wait "$TASK_ID" --service suno --action text-to-music
```

## Befehlskonventionen

Jeder Befehl gibt JSON auf der Standardausgabe aus, sofern eine Option nicht ausdrücklich einen skalaren Wert anfordert, z. B. `files create --url-only` oder `listen
--print-secret`. Fortschritts- und Diagnosemeldungen bleiben auf der Standardfehlerausgabe, sodass JSON sicher an `jq` weitergeleitet werden kann:

```shell
runapi nano-banana text-to-image --input-file request.json \
  | jq -r '.images[].url' \
  | xargs -I{} curl -OL {}
```

Modellaktionen akzeptieren genau eine Anfrage-Eingabequelle:

* `--input '<json object>'` stellt inline JSON bereit.
* `--input-file path/to/request.json` lädt JSON aus einer Datei.
* `--input-file -` liest JSON aus der Standardeingabe.

Verwende `runapi <service> <action> --help`, bevor du eine Anfrage konstruierst.
Die installierte CLI listet die aktuellen Felder der Aktion, akzeptierte Modell-
Identifikatoren und Validierungsbeschränkungen auf.

Diese globalen Optionen gelten für jeden Befehl:

| Option | Zweck |
|----------
| `--api-key` | Verwendet einen API-Schlüssel für diesen Aufruf. Überschreibt `RUNAPI_API_KEY`. |
| `--base-url` | Verwendet einen anderen API-Ursprung für diesen Aufruf. |
| `--timeout` | Legt das gesamte Befehls-Timeout und die maximale Wartezeit für Aufgaben fest. Der Standardwert beträgt 15 Minuten. |
| `--poll-interval` | Legt das Intervall für das Abfragen von Aufgaben fest. Der Standardwert beträgt 3 Sekunden. |
| `--async` | Kehrt sofort nach dem Einreichen einer asynchronen Modell-Aktion zurück. |
| `--quiet` | Unterdrückt Fortschrittsausgaben auf der Standardfehlerausgabe, ohne die JSON-Ausgabe zu verändern. |

## Modellaktionen

Die Modellbefehlsstruktur lautet `runapi <service> <action>`. Synchrone
Aktionen geben ihre Antwort sofort zurück. Bei asynchronen Aktionen ist das
Standardverhalten: Einreichen, Abfragen und Zurückgeben des abschließenden Task-Ergebnisses;
`--async` gibt stattdessen die Erstellungsantwort zurück.

Bei übergeordneten Medien-URL-Feldern wird ein lesbarer lokaler Dateipfad hochgeladen, bevor die Modellaktion ausgeführt wird. Bestehende `http://`- und `https://`-URLs werden unverändert gesendet. Verwenden Sie `files create`, wenn Sie eine wiederverwendbare temporäre URL benötigen, wenn die Quelle eine Remote-URL ist oder wenn die Quelle Base64-Daten sind.

### Audio- und Musikaktionen

* `suno`: `add-instrumental`, `add-vocals`, `blend-lyrics`,
  `boost-style`, `check-voice`, `convert-audio`, `cover-audio`,
  `create-mashup`, `extend-music`, `generate-artwork`,
  `generate-lyrics`, `generate-midi`, `generate-persona`,
  `generate-voice`, `get-timestamped-lyrics`,
  `regenerate-validation-phrase`, `replace-section`,
  `separate-audio-stems`, `text-to-music`, `text-to-sound`,
  `visualize-music`, `voice-to-validation-phrase`
* `producer`: `text-to-music`
* `gemini-omni`: `create-audio`, `create-character`, `text-to-video`
* `openai-tts`: `text-to-speech`
* `fish-audio`: `text-to-speech`
* `gemini-tts`: `text-to-speech`
* `elevenlabs`: `isolate-audio`, `speech-to-text`, `text-to-dialogue`,
  `text-to-sound`, `text-to-speech`

### Bildaktionen

* `nano-banana`: `edit-image`, `text-to-image`
* `imagen-4`: `remix-image`, `text-to-image`
* `seedream`: `decompose-layers`, `edit-image`, `text-to-image`
* `flux`: `remix-image`, `text-to-image`
* `flux-2`: `remix-image`, `text-to-image`
* `flux-kontext`: `text-to-image`
* `qwen-2`: `edit-image`, `text-to-image`
* `qwen-3`: `edit-image`, `text-to-image`
* `qwen-image`: `edit-image`, `remix-image`, `text-to-image`
* `recraft`: `remove-background`, `upscale-image`
* `z-image`: `text-to-image`
* `ideogram-v3`: `edit-image`, `reframe-image`, `remix-image`,
  `text-to-image`
* `gpt-image`: `edit-image`, `text-to-image`
* `gpt-image-2`: `edit-image`, `text-to-image`
* `gpt-4o-image`: `text-to-image`
* `midjourney`: `edit-image`, `get-seed`, `image-to-prompt`,
  `shorten-prompt`, `text-to-image`

### Video- und Animationsaktionen

* `veo-3-1`: `extend-video`, `text-to-video`, `upscale-video`
* `seedance`: `text-to-video`
* `runway`: `extend-video`, `text-to-video`
* `runway-aleph`: `edit-video`
* `kling`: `avatar`, `edit-video`, `extend-video`, `image-to-video`,
  `motion-control`, `text-to-video`
* `infinitetalk`: `audio-to-video`
* `omnihuman`: `audio-to-video`, `human-identification`,
  `subject-detection`
* `wan`: `animate`, `edit-video`, `image-to-video`, `speech-to-video`,
  `text-to-image`, `text-to-video`
* `luma`: `modify-video`
* `hailuo`: `image-to-video`, `text-to-video`
* `volcengine-lip-sync`: `lip-sync-video`
* `happyhorse`: `edit-video`, `image-to-video`, `text-to-video`
* `grok-imagine`: `edit-image`, `extend`, `image-to-video`,
  `text-to-image`, `text-to-video`, `upscale-image`
* `topaz`: `upscale-image`, `upscale-video`
* `midjourney`: `extend-video`, `image-to-video`

Die obige Liste ist das vollständige Aktionsinventar in diesem CLI-Release.
Der genaue Anfrage- und Antwortvertrag jeder Aktion ist in der
[API-Referenz](https://runapi.ai/de/docs/api/openai/chat-completions.md) verfügbar, und die lokale
Befehlshilfe ist die Quelle für versionsspezifische Felder.

## Task-Lebenszyklus

Verwende `get`, um den aktuellen Zustand eines asynchronen Tasks zu prüfen, ohne
zu warten. Verwende `wait`, um so lange abzufragen, bis er abgeschlossen ist, fehlschlägt oder das
Befehlstimeout erreicht. Beide Befehle erfordern den ursprünglichen Service und die Aktion,
damit die CLI die korrekte Task-Ergebnisstruktur auswählen kann.

```shell
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
```

## Dateien

`runapi files create` behält den temporären File-Upload-URL-Ablauf bei. Es
lädt einen lokalen Pfad, eine Remote-URL oder eine Base64-Quelle hoch und gibt eine URL
zurück, die nach einer Stunde abläuft.

```shell
runapi files create ./reference.png --url-only
runapi files create --url https://example.test/reference.png --file-name reference.png
runapi files create --base64 "$(base64 < reference.png)" --file-name reference.png
```

Die Quellenoptionen schließen sich gegenseitig aus. `--url-only` gibt nur die URL
aus; lassen Sie diese Option weg, um die vollständige JSON-Antwort zu erhalten.

Verwenden Sie den persistenten Datei-Lebenszyklus, wenn Sie eine stabile `file_id` anstelle einer URL benötigen:

```shell
runapi files create-file ./knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output ./knowledge-copy.pdf
runapi files delete file_123
```

`content` erfordert `--output`; übergeben Sie `-`, um die genauen File-Bytes in die
Standardausgabe zu schreiben. Siehe [Files and Uploads](https://runapi.ai/de/docs/resources/files.md) für
Limits, Account-Isolierung und den REST-Lebenszyklus.

## Hochladen

Verwende Uploads, um einen oder mehrere Parts zu senden, bevor die endgültige File zusammengestellt wird.
Create deklariert die endgültige Byte-Anzahl und Metadaten; wiederhole `--part-id` in
der Kompositionsreihenfolge beim Abschließen:

```shell
runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 ./archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123
```

## Konto und Preisgestaltung

Den authentifizierten Benutzer und das ausgewählte Konto prüfen, dann Guthaben und Ausgabenzähler abfragen:

```shell
runapi account info
runapi account balance
```

`pricing list` liest aktuelle Preispläne. Filtern Sie nach Service, Action
oder Modell. `pricing quote` schätzt die Task-Reservierung für einen erforderlichen
Service und eine Action; fügen Sie `--model` hinzu, wenn die Action modellspezifisch ist, und
geben Sie Pricing Inputs mit `--params` oder `--params-file` an.

```shell
runapi pricing list --service suno --action text-to-music --model suno-v4
runapi pricing quote --service suno --action text-to-music --model suno-v4 \
  --params '{"vocal_mode":"auto_lyrics","prompt":"A chill lo-fi beat"}'
runapi pricing quote --service suno --action text-to-music --params-file pricing-inputs.json
```

Preisabfragen erfordern keine Anmeldedaten, es sei denn, das Angebot bezieht sich auf einen kontoeigenen Quell-Task.

## Authentifizierung und Konfiguration

`runapi login` öffnet einen Browser-Autorisierungsablauf und speichert die
resultierende Anmeldeinformation. Für Server und CI akzeptiert `auth import-token` einen
API-Schlüssel von der Standardeingabe, verifiziert ihn standardmäßig und speichert ihn,
ohne den Wert in der Prozessliste oder dem Shell-Verlauf preiszugeben:

```shell
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
```

`auth import-token --skip-verify` unterstützt die Offline-Image-Einrichtung. Verwenden Sie es
nur, wenn die Verifizierung während der Einrichtung nicht möglich ist; `auth status` verifiziert
die aktive Anmeldeinformation zu einem späteren Zeitpunkt.

Die Priorität des API-Schlüssels ist `--api-key`, dann `RUNAPI_API_KEY`, dann die lokale
CLI-Konfigurationsdatei. Die Priorität der Base URL ist `--base-url`, dann
`RUNAPI_BASE_URL`, dann die gespeicherte Base URL, dann `https://runapi.ai`.
Die Konfigurationsdatei ist `~/.config/runapi/config.json` oder
`$XDG_CONFIG_HOME/runapi/config.json`, wenn `XDG_CONFIG_HOME` gesetzt ist.

## Lokaler Callback-Listener

`runapi listen` empfängt Task-Callbacks für einen ausgewählten API-Schlüssel und
leitet optional jeden signierten Callback an einen lokalen HTTP-Endpunkt weiter.
Eine Browser-Anmeldung ist erforderlich, bevor Listener-Operationen verwendet werden können.

```shell
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
```

Die positionelle URL und `--forward-to` sind Alternativen. Der Listener
schreibt jeden signierten Callback-Body auf die Standardausgabe. Ein Task mit
`callback_url` liefert weiterhin an diese URL und wird zusätzlich an den
lokalen Listener kopiert.

Nachdem ein gültiges Listener-Ereignis empfangen wurde, bestätigt die CLI es, bevor sie die lokale HTTP-Anfrage versucht. Jedes Ereignis wird einmal lokal weitergeleitet: Nicht-2xx-Antworten und Verbindungsfehler werden im Terminal gemeldet, führen jedoch nicht dazu, dass der Listener das Ereignis erneut abspielt. Dieses lokale Debugging-Verhalten ändert nichts an den Zustellungswiederholungen für die `callback_url` einer Task.

Jedes Konto kann bis zu 100 aktive Listener pro Callback-Abonnementschlüssel und insgesamt 1.000 aktive Listener ausführen. Wenn ein Limit erreicht ist, stoppen Sie einen inaktiven Listener oder warten Sie und versuchen Sie es erneut. Die API-Antwort gibt an, ob der ausgewählte Schlüssel, Ihr Konto oder die Gesamtdienstkapazität ausgeschöpft ist.

Ein inaktiver Listener prüft alle 15 bis 30 Sekunden auf neue Ereignisse.
Ereignisse werden normalerweise innerhalb von etwa 15 Sekunden gefunden und sofort gelesen, wenn sie verfügbar sind. Wenn ein Limit erreicht wird, beenden Sie einen inaktiven Listener oder warten Sie und versuchen Sie es erneut. Das bestehende Zustellungs- und Bestätigungsverhalten bleibt unverändert.

Die Schlüsselauswahl erfolgt in dieser Reihenfolge: `--callback-api-key-id` für einen einzelnen Befehl, `callback_api_key_id` in der Projekt-`.runapi.toml`, dann eine interaktive Auswahl. Die Projektkonfiguration wird im Git-Stammverzeichnis oder im aktuellen Verzeichnis außerhalb eines Git-Repositorys gespeichert und enthält nur die stabile ID:

```toml
callback_api_key_id = "token_abc123"
```

Den Listen-Signing-Secret eines ausgewählten Schlüssels ausgeben, ohne einen Listener zu starten, oder ihn nach einer Offenlegung rotieren:

```shell
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
```

Die Rotation macht aktive Listener für den ausgewählten Schlüssel ungültig. Aktualisieren Sie
jeden lokalen Verifier mit dem neu angezeigten Geheimnis, bevor Sie seinen
Listener neu starten.

## Testrahmen

Die portable RunAPI-CLI-Skill in einen unterstützten Harness installieren, unterstützte Ziele prüfen oder eine installierte Skill entfernen:

```shell
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
```

Eingebaute Ziele sind `claude`, `codex`, `gemini`, `openclaw` und
`hermes`. `install-skill` akzeptiert `--version` zum Festlegen einer Skill-Version, `--target-dir` für ein benutzerdefiniertes Zielverzeichnis, `--source` für ein Quell-Repository und `--force` zum Überschreiben eines vorhandenen Skill-Verzeichnisses.

## Shell-Vervollständigung und Version

Vervollständigungsskripte für Bash, Zsh, Fish oder PowerShell generieren. Beispiel: Bash-Vervollständigung in der aktuellen Shell laden:

```shell
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
```

Verwende `runapi --help`, um Befehle aufzulisten, `runapi <command> --help` für die
Optionen eines Befehls und `runapi <service> <action> --help` für die Felder einer
Modell-Aktion.

## Exit-Codes

Befehle enden mit einem Nicht-Null-Code, den Skripte verarbeiten können:

| Code | Bedeutung |
|----------
| `0` | Erfolg |
| `2` | Authentifizierungsfehler oder nicht unterstützte Plattform |
| `3` | Unzureichende Credits oder eine erforderliche lokale Abhängigkeit fehlt |
| `4` | Validierungs-, Nicht-gefunden- oder Manifest-Parsing-Fehler |
| `5` | Zeitüberschreitung, Download-Fehler oder Prüfsummen-Abweichung |
| `6` | Ratenlimit überschritten |
| `7` | Aufgabe fehlgeschlagen |

Für Anfragefelder, Task-Statuswerte, Callback-Payloads, Fehlerkörper und die Behandlung von Ratenbegrenzungen fahren Sie mit der [API
Referenz](https://runapi.ai/de/docs/api/openai/chat-completions.md) fort. Verwenden Sie
[SDKs](https://runapi.ai/de/docs/resources/sdks.md), wenn derselbe Arbeitsablauf innerhalb einer Anwendung stattfindet.

---

## Mehr von RunAPI

- [Startseite](https://runapi.ai/de/.md)
- [Modellkatalog](https://runapi.ai/de/models.md)
- [Preise](https://runapi.ai/de/pricing.md)
- [Anbieter](https://runapi.ai/de/models)
- [Dokumentation](https://runapi.ai/de/docs/guides)
- [SDKs](https://runapi.ai/de/sdk.md)
- [CLI](https://runapi.ai/de/cli.md)
- [MCP Server](https://runapi.ai/de/mcp.md)
- [Claude Code vs Cursor](https://runapi.ai/de/claude-code-vs-cursor.md)
- [Cursor API-Einrichtung](https://runapi.ai/de/cursor-api-setup.md)
- [RunAPI vs OpenRouter](https://runapi.ai/de/openrouter-alternative.md)
- [Enterprise](https://runapi.ai/de/contact.md)
- [Kontakt](https://runapi.ai/de/contact.md)
- [Bedingungen](https://runapi.ai/de/terms.md)
- [Datenschutz](https://runapi.ai/de/privacy.md)
- [Website-Index für KI-Agenten](https://runapi.ai/llms.txt)

Kontakt: contact@runapi.ai

## Strukturierte Daten

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "de",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/de",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/de/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "de",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/de",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/deicon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "de",
    "@type": "TechArticle",
    "headline": "CLI",
    "description": "Jeden RunAPI-CLI-Befehl für Modellaktionen, Tasks, Dateien, Uploads, Kontoinformationen, Preise, Callbacks und Harness installieren und verwenden.",
    "url": "https://runapi.ai/de/docs/resources/cli",
    "mainEntityOfPage": "https://runapi.ai/de/docs/resources/cli"
  }
]
```