Developer

Command-line interface

Install the SubFT CLI, bind local projects, and run subtitle operations from the terminal.

Quick start
pip install subft-cli
subft login
subft project sync /media/library --create
subft operation start /media/library --lang de

Workflow

From login to local output

Authenticate once, bind a local directory, start remote work, and apply the result locally.

  1. 1Log inStore the token and select the API gateway.
  2. 2Bind and syncConnect a directory to a project and reconcile its media.
  3. 3Start and watchCreate an operation, wait for progress, or detach for later.
  4. 4Apply outputWrite completed tracks or embedded output back to the local directory.

Reference

Commands and options

These are the stable user-facing command groups. Global automation flags can be used where supported.

Global options

CommandOptionsPurpose
subft COMMAND[--json] [--yes]

Run any command with versioned JSON output or deterministic confirmation handling.

subft --version—

Print the installed CLI version.

subft --help—

Show the root command reference; each nested command also supports --help.

Authentication

CommandOptionsPurpose
subft login[--api-url URL] [--token TOKEN]

Authenticate with a token and optionally select another gateway.

subft status[--api-url URL]

Show the current gateway, identity, and credential source.

subft logout—

Remove the token stored by the CLI.

Projects and synchronization

CommandOptionsPurpose
subft project bind PATH[--project-id ID | --create [--name NAME]] [--api-url URL]

Bind a local path to an existing or newly created project.

subft project forget PATH[--project-id ID | --all] [--api-url URL]

Remove one or all local project bindings.

subft project bindings[PATH]

List saved bindings, optionally filtered by path.

subft project sync PATH[--preview] [--include-hidden] [--project-id ID | --create [--name NAME]] [--api-url URL]

Preview or apply deterministic local-to-project synchronization.

Operations

CommandOptionsPurpose
subft operation start PATH --lang CODE[--output-target TARGET] [--remove-track] [--wait | --detach] [--include-hidden] [--project-id ID | --create [--name NAME]] [--allow-partial] [--api-url URL]

Start a subtitle operation for the bound project and chosen language.

subft operation watch OPERATION_ID[--api-url URL]

Follow an operation until it reaches a terminal state.

subft operation apply OPERATION_ID PATH[--output-target TARGET] [--remove-track | --keep-track] [--allow-partial] [--api-url URL]

Download and apply a completed operation to local files.

Supported CLI inputs

VideoMP4, MKV, AVI, MOV, WEBM
AudioMP3, WAV, FLAC, AAC, OGG, M4A
SubtitlesSRT, VTT, ASS
VobSub pairIDX + SUB

Output targets

Choose an external sidecar, SubFT JSON, or an embedded media output.

  • external_srt
  • external_vtt
  • external_ass
  • external_csubs_json
  • embedded

Gateway and local configuration

Pass --api-url or use these environment variables for non-default gateways and credentials.

  • SUBFT_API_URL
  • SUBFT_API_TOKEN

The CLI uses these XDG locations and falls back to the shown home-directory paths. On POSIX, private permissions are required.

  • $XDG_CONFIG_HOME/subft/config.json~/.config/subft/config.json
  • $XDG_STATE_HOME/subft/projects.json~/.local/state/subft/projects.json

Troubleshooting

Common failures

FFmpeg is not foundInstall both ffmpeg and ffprobe and confirm they are available on PATH.
Authentication is staleRun status, then log in again with the active token if verification fails.
The directory is not boundBind it to a project, or add --project-id or --create to the command.
An operation finishes partiallyReview reported failures and use --allow-partial only when partial output is acceptable.