How to Migrate from Deprecated `--mode` Flags to New `serve`/`local` Commands in Hugging Face Speech-to-Speech

Replace --mode realtime with serve and --mode local with local, removing the --mode flag entirely while keeping all other arguments unchanged.

The Hugging Face speech-to-speech repository recently restructured its CLI to use explicit sub-commands instead of the legacy --mode flag. If you're upgrading your scripts or deployment pipelines, you'll need to update your invocations to avoid deprecation warnings and ensure compatibility with future releases.

Understanding the --mode Flag Deprecation

The original CLI accepted a --mode option with two possible values: realtime or local. Internally, this flag was only a thin wrapper that selected one of two sub-commands:

• realtime → the serve command (starts the Realtime server only)
• local → the local command (starts the server and the loopback audio client)

According to the source code in src/speech_to_speech/cli.py, the deprecation logic rewrites argument lists when --mode is detected. The parse_command function handles this translation and emits a deprecation warning:

• --mode realtime … → serve … (lines 82-89)
• --mode local … → local … (lines 97-105)

Because this wrapper will be removed in a future release, you must now invoke the appropriate sub-command directly.

Migration Steps by Use Case

From --mode realtime to serve

Use the serve sub-command when you want to start only the Realtime server without an attached audio client.

Old (deprecated):

speech-to-speech --mode realtime --port 8765 --model_name meta-llama/Llama-3.1-8B-Instruct

New:

speech-to-speech serve --port 8765 --model_name meta-llama/Llama-3.1-8B-Instruct

The serve command is implemented in src/speech_to_speech/s2s_pipeline.py within the run_pipeline_command function when command == "serve" (lines 606-607).

From --mode local to local

Use the local sub-command when you want to launch both the server and a loopback audio client for local testing.

Old (deprecated):

speech-to-speech --mode local --port 8765 --enable_llm_proxy

New:

speech-to-speech local --port 8765 --enable_llm_proxy

This command uses the same run_pipeline_command function with command == "local".

Key Source Code References

Component	Role	Location
CLI entry point	Parses top-level commands, rewrites deprecated --mode usage, emits warnings	src/speech_to_speech/cli.py#L62-L110
serve sub-command	Launches only the Realtime server	src/speech_to_speech/s2s_pipeline.py#L606-L607
local sub-command	Launches server plus loopback audio client	src/speech_to_speech/s2s_pipeline.py#L606-L607
Test coverage	Verifies mapping and deprecation warning	tests/test_cli_defaults.py#L288-L303

Preserving Your Existing Configuration

All flags that previously followed --mode remain valid—they're simply parsed by the sub-command's own argument parser. You don't need to change:

• --port
• --model_name
• --enable_llm_proxy
• Any other pipeline-specific options

Only the --mode flag itself and its value should be removed and replaced with the direct sub-command.

Summary

• --mode realtime → serve
• --mode local → local
• Remove the --mode flag entirely from your commands
• Keep all other arguments in their original positions
• Update scripts, Dockerfiles, and systemd services before the wrapper is removed

Frequently Asked Questions

What happens if I keep using --mode?

The current implementation in src/speech_to_speech/cli.py emits a deprecation warning and automatically rewrites your command to use the new sub-command syntax. However, this compatibility layer will be removed in a future release, causing your commands to fail.

Can I still pass the same arguments after the sub-command?

Yes. All arguments that were valid after --mode are valid after serve or local. The sub-command parsers inherit the same option definitions as the legacy implementation.

How do I verify my migration is correct?

Run speech-to-speech --help to confirm the sub-commands appear. Then test your specific invocation with speech-to-speech serve --help or speech-to-speech local --help to see available options. The test suite in tests/test_cli_defaults.py provides additional validation patterns you can reference.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}