CLI-Befehlsreferenz

Alle SubFT-Befehle, Argumente, Optionen und Standards gegen den Quellcode geprüft.

Globale Optionen

Globale Optionen vor den Befehl stellen. --help steht automatisch bei jedem Befehl und jeder Gruppe bereit. Ein Strich bei Argumentstandard bedeutet erforderlich, None ein weggelassenes optionales Argument. Wiederholbare Optionen verwenden .... Python-Typausdrücke beschreiben Click-Pfad- und Auswahlregeln, keine Eingabe. Das CLI-Beispiel liefert tatsächliche Eingaben und IDs.

Beispiele sind unabhängige Befehle, keine Ausführungsfolge. Zuerst Beispieleingabe erstellen und mit dem CLI-Rezept anmelden. Die Shellvariable operation_id enthält die dort erfasste tatsächliche ID. Aufnahmen verwenden die eigene demo/speech.wav aus der Python-Vorbereitung.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--version`	`bool`	`False`	—	`False`	Installierte Version anzeigen und beenden.
`--json`	`bool`	`False`	—	`False`	Ein versioniertes JSON-Dokument auf stdout schreiben; Fragen/Diagnosen bleiben auf stderr. Fragen werden nicht deaktiviert.
`--yes`	`bool`	`False`	—	`False`	Fragen deaktivieren und Berechnung, geprüfte Synchronisierung, Ersetzung und Überschreiben bestätigen. Mehrdeutige Auswahl schlägt fehl.

Untertitelausgabe wählen

Dies sind die registrierten, gegen den CLI-Quellcode geprüften Optionen für --output-target. Sie wählen Untertitelformat und lokalen Speicherort; --json wählt unabhängig die Automatisierungsantwort.

JSON

[
  "external_srt",
  "external_vtt",
  "external_ass",
  "embedded"
]

Auswahl	Bedeutung
`external_srt`	Externe SRT-Untertiteldatei schreiben.
`external_vtt`	Externe WebVTT-Untertiteldatei schreiben.
`external_ass`	Externe ASS-Untertiteldatei schreiben.
`embedded`	Gewählte Untertitelspuren mit FFmpeg in eine lokale Medienkopie einbetten.

Anmeldung und Projekte

`subft login`

API-Token prüfen und für sein Gateway speichern. Verdeckte Eingabe oder geschützte Umgebung verwenden.

Text

subft login

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.
`--token`	`str`	`None`	—	`False`	API-Token zur Anmeldung; SUBFT_API_TOKEN oder verdeckte Eingabe vermeidet Shell-Verlauf.

Voraussetzung: ein Konto und sein aktives Token; in die verdeckte Eingabe einfügen.

Beispiel:

Shell

subft login

`subft logout`

Nur lokal gespeichertes Token entfernen. Umgebungsanmeldung bleibt aktiv; Serverwiderruf ist getrennt.

Text

subft logout

Voraussetzung: zu entfernende lokale Konfiguration; kein Serverwiderruf.

Beispiel:

Shell

subft logout

`subft project bind`

Lokale Datei oder Verzeichnis einem passenden gespeicherten Projekt zuordnen. Bindungen sind Cache, keine Inventarsynchronisierung.

Text

subft project bind PATH

Argument	Typ	Standard	Bedeutung
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--project-id`	`str`	`None`	—	`False`	Ausdrückliche Projekt-ID bei mehreren gültigen Bindungen oder unbeaufsichtigter Auswahl.
`--create`	`bool`	`False`	—	`False`	Neues leeres Projekt im Modus des lokalen Pfads erstellen und binden. Nicht mit --project-id kombinieren.
`--name`	`str`	`None`	—	`False`	Anzeigename bei --create; sonst liefert der lokale Pfad einen Standardnamen.
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: lokale Beispieldatei und angemeldetes Konto. Dieses Beispiel erstellt Projekt/Bindung ohne Inventarabgleich oder AI-Kosten.

Beispiel:

Shell

subft project bind demo/sample.srt --create --name docs-binding-example

`subft project bindings`

Bindungen ohne Backend-Prüfung oder Anmeldung lesen. Optionaler PATH filtert die lokale Liste.

Text

subft project bindings [PATH]

Argument	Typ	Standard	Bedeutung
`path`	`click.Path(path_type=Path)`	`None`	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Voraussetzung: Beispielpfad; Cache-Bindungen des aktuellen Gateways/Kontos prüfen.

Beispiel:

Shell

subft project bindings demo/sample.srt

`subft project forget`

Lokale Bindungen nach Gateway/Konto entfernen; fehlende Pfade akzeptieren und keine Backend-Projekte löschen oder archivieren.

Text

subft project forget PATH

Argument	Typ	Standard	Bedeutung
`path`	`click.Path(path_type=Path)`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--project-id`	`str`	`None`	—	`False`	Ausdrückliche Projekt-ID bei mehreren gültigen Bindungen oder unbeaufsichtigter Auswahl.
`--all`	`bool`	`False`	—	`False`	Alle Bindungen dieses Pfads im aktuellen Gateway-/Kontobereich vergessen.
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: Cache-Bindungen des Beispielpfads. Bestätigung prüfen; nur lokaler Cache wird entfernt.

Beispiel:

Shell

subft project forget demo/sample.srt --all

`subft project sync`

Gesamte lokale Eingabe prüfen und Inventar abgleichen. Scan-/Analysefehler verhindern Teilübermittlung; veraltete Anwendung benötigt neue Vorschau.

Text

subft project sync PATH

Argument	Typ	Standard	Bedeutung
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--preview`	`bool`	`False`	—	`False`	Inventar ohne Hinzufügen/Ersetzen prüfen. Auflösung kann ein ausdrücklich angefordertes Projekt erstellen oder binden.
`--include-hidden`	`bool`	`False`	—	`False`	Dateien mit Punktpräfix bei Verzeichnisprüfung einschließen; Symlinks bleiben ausgeschlossen.
`--project-id`	`str`	`None`	—	`False`	Ausdrückliche Projekt-ID bei mehreren gültigen Bindungen oder unbeaufsichtigter Auswahl.
`--create`	`bool`	`False`	—	`False`	Neues leeres Projekt im Modus des lokalen Pfads erstellen und binden. Nicht mit --project-id kombinieren.
`--name`	`str`	`None`	—	`False`	Anzeigename bei --create; sonst liefert der lokale Pfad einen Standardnamen.
`--media-id`	`str`	`None`	—	`False`	Nur Dateiprojekte: das zu ersetzende Medium, wenn mehrere den Dateinamen teilen. Ohne die Option hält sync an und listet ihre IDs.
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: die im Rezept angelegte Projektbindung. Vorschau ist kostenlos und startet keine AI-Arbeit.

Beispiel:

Shell

subft project sync demo/sample.srt --preview

`subft status`

Wirksame Zugangsdaten und Gateway prüfen; Umgebungsüberschreibungen werden nicht gespeichert.

Text

subft status

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: ein wirksames Token für das gewählte Gateway.

Beispiel:

Shell

subft status

Operationen und Export

Kontozugriff, synchronisiertes Projekt und Originaldateien sind für Quellvorbereitung erforderlich. AI-Start benötigt Guthaben. Gespeicherte erfolgreiche Ausgaben bleiben herunterladbar; apply braucht zusätzlich passendes lokales Ziel und Bindung. Großgeschriebene Werte benennen Argumente; IDs aus Antworten übernehmen.

`subft operation apply`

Bei Bedarf warten, erfolgreiche gespeicherte Artefakte wählen und lokale Ausgaben schreiben/registrieren. Fehlgeschlagene Eingaben fehlen; Teilexport braucht Zustimmung.

Text

subft operation apply OPERATION_ID PATH

Argument	Typ	Standard	Bedeutung
`operation_id`	`str`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--output-target`	`click.Choice(list(OUTPUT_TARGETS), case_sensitive=False)`	`None`	—	`False`	external_srt, external_vtt, external_ass oder embedded wählen. Ohne Angabe gilt Kontopräferenz; unbeaufsichtigter Fallback ist external_srt.
`--content-id`	`str`	`()`	...	`False`	Bei supply eine zulässige Quelle liefern; apply akzeptiert wiederholte Quellelement-IDs für Teilergebnisse.
`--artifact-id`	`str`	`()`	...	`False`	Bestimmte erfolgreiche unveränderliche Stufe wählen; für mehrere Artefakte wiederholen.
`--replace`	`str`	`()`	...	`False`	ARTIFACT_ID=ASSET_ID ersetzt geprüfte eingebettete physische Untertitel im selben Medium; sonst fügt embedded Spuren hinzu.
`--allow-partial`	`bool`	`False`	—	`False`	Erfolgreiche Ergebnisse fehlgeschlagener/abgebrochener Operationen erlauben. Unbeaufsichtigt zusätzlich --yes; Ausgang bleibt ungleich null.
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: erfasste Operations-ID, erfolgreiche gespeicherte Artefakte und ursprünglich gebundener Beispielpfad. Überschreibbestätigung prüfen.

Beispiel:

Shell

subft operation apply "$operation_id" demo/sample.srt \
    --output-target external_srt

`subft operation start`

Synchronisierte Medien prüfen, Quellen vorbereiten, schätzen, Kosten bestätigen, starten und liefern. Nach Annahme warten oder lösen; Export ist getrennt.

Text

subft operation start PATH

Argument	Typ	Standard	Bedeutung
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--lang`	`str`	`None`	—	`True`	Erforderlicher Zielsprachcode. Quellsprachen werden im interaktiven Plan oder durch Backend-Standards gewählt.
`--wait / --detach`	`bool`	`True`	—	`False`	Standardmäßig Serververarbeitung abwarten; --detach kehrt nach Quellannahme zurück. Keines exportiert Dateien.
`--include-hidden`	`bool`	`False`	—	`False`	Dateien mit Punktpräfix bei Verzeichnisprüfung einschließen; Symlinks bleiben ausgeschlossen.
`--project-id`	`str`	`None`	—	`False`	Ausdrückliche Projekt-ID bei mehreren gültigen Bindungen oder unbeaufsichtigter Auswahl.
`--create`	`bool`	`False`	—	`False`	Neues leeres Projekt im Modus des lokalen Pfads erstellen und binden. Nicht mit --project-id kombinieren.
`--name`	`str`	`None`	—	`False`	Anzeigename bei --create; sonst liefert der lokale Pfad einen Standardnamen.
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: abgeglichene Beispieldatei, genügend Credits und ausdrückliche Schätzungsbestätigung.

Beispiel:

Shell

subft operation start demo/sample.srt --lang de --detach

`subft operation supply`

Zulässige awaiting_client-/awaiting_retry-Quellen derselben Operation liefern. Endgültiger Verarbeitungsfehler erfordert neue Operation.

Text

subft operation supply OPERATION_ID PATH

Argument	Typ	Standard	Bedeutung
`operation_id`	`str`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--content-id`	`str`	`None`	—	`False`	Bei supply eine zulässige Quelle liefern; apply akzeptiert wiederholte Quellelement-IDs für Teilergebnisse.
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: angenommene Aufnahmeoperation mit zulässiger Vorbereitung und dieselbe lokale WAV. Wiederholung liefert bestehende Arbeit, startet keine endgültigen AI-Stufen neu.

Beispiel:

Shell

subft operation supply "$operation_id" demo/speech.wav

`subft operation watch`

Mit Echtzeithinweisen und HTTP-Abfragen Operationsstand verfolgen. Strg-C löst, ohne angenommene Arbeit abzubrechen.

Text

subft operation watch OPERATION_ID

Argument	Typ	Standard	Bedeutung
`operation_id`	`str`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.

Option	Typ	Standard	Wiederholbar	Erforderlich	Bedeutung
`--api-url`	`str`	`None`	—	`False`	Gateway für diesen Aufruf überschreiben, auch über SUBFT_API_URL. Gespeicherte Zugangsdaten werden nie an ein anderes Gateway gesendet.

Voraussetzung: erfasste Operations-ID und Projektzugriff.

Beispiel:

Shell

subft operation watch "$operation_id"

Konfiguration und lokale Schreibvorgänge

SUBFT_API_URL und SUBFT_API_TOKEN überschreiben gespeicherte Werte für einen Aufruf. --api-url hat Vorrang vor der Umgebungs-URL; --token wählt die Anmeldeberechtigung ausdrücklich. Ein gespeichertes Token gehört zu seinem Gateway. Anmeldung liegt unter $XDG_CONFIG_HOME/subft/config.json, ersatzweise ~/.config/subft/config.json; Bindungen unter $XDG_STATE_HOME/subft/projects.json, ersatzweise ~/.local/state/subft/projects.json. POSIX-Verzeichnisse/Dateien verwenden 0700/0600; Tokens sind durch Berechtigungen geschützt, nicht verschlüsselt.

Externe SRT/VTT/ASS-Ausgaben verwenden vorgeschlagene relative Pfade, temporäre Dateien im selben Verzeichnis und atomare Ersetzung. Unterschiedliche vorhandene Dateien benötigen standardmäßig abgelehnte Überschreibbestätigung; identische Ausgabe ist idempotent. Einbetten erhält andere Streams, benötigt FFmpeg, lehnt vorhandene <media>.bak ab und prüft Streams vor Registrierung physischer Assets. Bei Registrierungsfehler bleiben geprüfte Datei und Backup erhalten; Wiederholung im selben Prozess muxt nicht erneut. Ungeklärte Backups benötigen manuelle Prüfung. Ein neuer Aufruf ermittelt Inventar regulär.

Siehe JSON- und Ausgangsverträge, Vorbereitungswiederherstellung und Wiederherstellung nach endgültigem Fehler.