CLI command reference

Every SubFT command, argument, flag and default checked against source.

Global options

Place global options before the command. --help is available automatically on every command/group. A dash in argument Default means required; None denotes an optional omitted argument. Repeatable flags use .... Python-style type expressions describe Click’s actual path/choice restrictions, not text to enter. Follow the CLI recipe for real inputs and IDs.

Examples are independent, not a sequence to run. First create the sample input and authenticate using the CLI recipe. The shell variable operation_id is the real ID captured there. Recording examples use your own demo/speech.wav from the Python setup.

Flag	Type	Default	Repeated	Required	Meaning
`--version`	`bool`	`False`	—	`False`	Print the installed version and exit.
`--json`	`bool`	`False`	—	`False`	Write one versioned JSON document to stdout; prompts/diagnostics stay on stderr. This does not disable prompts.
`--yes`	`bool`	`False`	—	`False`	Disable prompts and approve charges, reviewed synchronization, replacements and overwrites. Ambiguous choices fail.

Subtitle output choices

These are the registered --output-target choices, checked against the CLI source. They choose subtitle serialization and local placement; --json independently chooses the automation envelope.

JSON

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

Choice	Meaning
`external_srt`	Write an external SRT subtitle sidecar.
`external_vtt`	Write an external WebVTT subtitle sidecar.
`external_ass`	Write an external ASS subtitle sidecar.
`embedded`	Embed selected subtitle tracks into a local media copy using FFmpeg.

Authentication and projects

`subft login`

Verify and store an API token for its gateway. Use the hidden prompt or protected environment.

Text

subft login

Flag	Type	Default	Repeated	Required	Meaning
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.
`--token`	`str`	`None`	—	`False`	API token for login; SUBFT_API_TOKEN or the hidden prompt avoids shell-history exposure.

Prerequisite: an account and its active token; paste it into the hidden prompt.

Example:

Shell

subft login

`subft logout`

Remove only the locally stored token. Environment authentication remains active; server revocation is separate.

Text

subft logout

Prerequisite: local configuration to remove; no remote revocation is performed.

Example:

Shell

subft logout

`subft project bind`

Bind a local file or directory to a matching durable project. Bindings are a disposable cache, not inventory synchronization.

Text

subft project bind PATH

Argument	Type	Default	Meaning
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Flag	Type	Default	Repeated	Required	Meaning
`--project-id`	`str`	`None`	—	`False`	Explicit project ID. Use it when several cached bindings are valid or unattended selection is needed.
`--create`	`bool`	`False`	—	`False`	Create and bind a new empty project matching the local path’s mode. Do not combine with --project-id.
`--name`	`str`	`None`	—	`False`	Display name used with --create; otherwise the local path supplies a default name.
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: the local sample file and an authenticated account. This example creates a new project/binding without synchronizing inventory or charging AI.

Example:

Shell

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

`subft project bindings`

Read cached associations without backend validation or authentication. Optional PATH filters the local list.

Text

subft project bindings [PATH]

Argument	Type	Default	Meaning
`path`	`click.Path(path_type=Path)`	`None`	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Prerequisite: the sample path; inspect cached associations for the current gateway/account.

Example:

Shell

subft project bindings demo/sample.srt

`subft project forget`

Remove local associations scoped to gateway/account; accept missing paths and never archive/delete backend projects.

Text

subft project forget PATH

Argument	Type	Default	Meaning
`path`	`click.Path(path_type=Path)`	—	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Flag	Type	Default	Repeated	Required	Meaning
`--project-id`	`str`	`None`	—	`False`	Explicit project ID. Use it when several cached bindings are valid or unattended selection is needed.
`--all`	`bool`	`False`	—	`False`	Forget every cached association for this local path in the current gateway/account scope.
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: cached associations for the sample path. Review the confirmation; this removes local cache only.

Example:

Shell

subft project forget demo/sample.srt --all

`subft project sync`

Inspect the entire local input and reconcile project inventory. Local scan/probe failures prevent partial submission; stale apply needs a fresh preview.

Text

subft project sync PATH

Argument	Type	Default	Meaning
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Flag	Type	Default	Repeated	Required	Meaning
`--preview`	`bool`	`False`	—	`False`	Inspect and compare inventory without adding/replacing media. Resolution may still create/cache an explicitly requested project.
`--include-hidden`	`bool`	`False`	—	`False`	Include dot-prefixed entries during directory inspection; symlinks remain excluded.
`--project-id`	`str`	`None`	—	`False`	Explicit project ID. Use it when several cached bindings are valid or unattended selection is needed.
`--create`	`bool`	`False`	—	`False`	Create and bind a new empty project matching the local path’s mode. Do not combine with --project-id.
`--name`	`str`	`None`	—	`False`	Display name used with --create; otherwise the local path supplies a default name.
`--media-id`	`str`	`None`	—	`False`	File projects only: the media to replace when several share the file’s name. Without it, sync stops and lists their IDs.
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: the sample project binding established by the guide. Preview is free and does not commit AI work.

Example:

Shell

subft project sync demo/sample.srt --preview

`subft status`

Verify the effective credential and gateway; environment overrides are not persisted.

Text

subft status

Flag	Type	Default	Repeated	Required	Meaning
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: an effective token for the selected gateway.

Example:

Shell

subft status

Operations and export

Account access, a synchronized project and original files are required for source preparation. Committing AI work requires credits. Saved successful outputs remain downloadable; apply also requires the appropriate local destination and binding. Uppercase usage values name arguments; obtain IDs from responses rather than guessing them.

`subft operation apply`

Wait if needed, select saved successful artifacts, and write/register local outputs. Failed inputs are unavailable; partial export needs explicit approval.

Text

subft operation apply OPERATION_ID PATH

Argument	Type	Default	Meaning
`operation_id`	`str`	—	ID of the committed operation; retain it before leaving or retrying preparation.
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Flag	Type	Default	Repeated	Required	Meaning
`--output-target`	`click.Choice(list(OUTPUT_TARGETS), case_sensitive=False)`	`None`	—	`False`	Choose external_srt, external_vtt, external_ass or embedded. Omission uses the account preference; unattended fallback is external_srt.
`--content-id`	`str`	`()`	...	`False`	Supply one eligible source for supply; apply accepts repeated source selectors for a result subset.
`--artifact-id`	`str`	`()`	...	`False`	Select a specific successful immutable stage; repeat for several artifacts.
`--replace`	`str`	`()`	...	`False`	ARTIFACT_ID=ASSET_ID pairs replace checked physical embedded subtitle assets in the same media; embedded otherwise adds streams.
`--allow-partial`	`bool`	`False`	—	`False`	Permit successful results from failed/aborted operations. Unattended partial export requires --yes too and still exits nonzero.
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: the captured operation ID, its successful saved artifacts and the original bound sample path. Review overwrite approval.

Example:

Shell

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

`subft operation start`

Preflight synchronized media, prepare selected sources, estimate, confirm charges, commit and supply. Wait or detach after acceptance; export is separate.

Text

subft operation start PATH

Argument	Type	Default	Meaning
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Flag	Type	Default	Repeated	Required	Meaning
`--lang`	`str`	`None`	—	`True`	Required target-language code. Source-language choices belong to the interactive plan/backend defaults.
`--wait / --detach`	`bool`	`True`	—	`False`	Wait for server processing by default; --detach returns after sources are accepted. Neither exports files.
`--include-hidden`	`bool`	`False`	—	`False`	Include dot-prefixed entries during directory inspection; symlinks remain excluded.
`--project-id`	`str`	`None`	—	`False`	Explicit project ID. Use it when several cached bindings are valid or unattended selection is needed.
`--create`	`bool`	`False`	—	`False`	Create and bind a new empty project matching the local path’s mode. Do not combine with --project-id.
`--name`	`str`	`None`	—	`False`	Display name used with --create; otherwise the local path supplies a default name.
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: a synchronized sample file, enough credits and explicit approval of the estimate.

Example:

Shell

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

`subft operation supply`

Resume eligible awaiting_client/awaiting_retry sources on the existing committed operation. Terminal processing recovery starts a new operation instead.

Text

subft operation supply OPERATION_ID PATH

Argument	Type	Default	Meaning
`operation_id`	`str`	—	ID of the committed operation; retain it before leaving or retrying preparation.
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	Local root, path or POSIX relative path. Scan helpers exclude symlinks; keep paths inside the chosen root.

Flag	Type	Default	Repeated	Required	Meaning
`--content-id`	`str`	`None`	—	`False`	Supply one eligible source for supply; apply accepts repeated source selectors for a result subset.
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: an accepted recording operation with eligible preparation and the same local WAV. A retry supplies existing work and does not restart terminal AI stages.

Example:

Shell

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

`subft operation watch`

Reattach to canonical operation state with realtime hints and HTTP polling. Ctrl-C detaches without aborting accepted work.

Text

subft operation watch OPERATION_ID

Argument	Type	Default	Meaning
`operation_id`	`str`	—	ID of the committed operation; retain it before leaving or retrying preparation.

Flag	Type	Default	Repeated	Required	Meaning
`--api-url`	`str`	`None`	—	`False`	Gateway override for this invocation; also supplied by SUBFT_API_URL. Stored credentials are never sent to another gateway.

Prerequisite: the captured operation ID and access to its project.

Example:

Shell

subft operation watch "$operation_id"

Configuration and local writes

SUBFT_API_URL and SUBFT_API_TOKEN override stored values for one invocation. Explicit --api-url takes precedence over the environment URL; --token selects the login credential explicitly. A stored token is bound to its gateway. Authentication lives at $XDG_CONFIG_HOME/subft/config.json, falling back to ~/.config/subft/config.json; bindings live at $XDG_STATE_HOME/subft/projects.json, falling back to ~/.local/state/subft/projects.json. POSIX directories/files use 0700/0600; tokens are permission-protected, not encrypted.

External SRT/VTT/ASS writes use backend-suggested relative paths, same-directory temporary files and atomic replacement. Different existing files need default-no overwrite approval; identical output is idempotent. Embedded output preserves unrelated streams, requires FFmpeg, refuses an existing <media>.bak, and verifies streams before registering physical assets. A registration failure retains the verified file and backup; in-process registration retry does not mux again. An unresolved backup needs manual review. A new invocation discovers inventory normally.

See JSON and exit contracts, preparation recovery and terminal recovery.