# Migrating from the Deprecated `--mode` Flag to `serve`, `talk`, and `local` Commands in Hugging Face Speech-to-Speech

> Migrate from the deprecated --mode flag to Hugging Face Speech-to-Speech serve talk and local commands. Learn how to update your CLI usage for efficient speech processing.

- Repository: [Hugging Face/speech-to-speech](https://github.com/huggingface/speech-to-speech)
- Tags: migration-guide
- Published: 2026-08-09

---

**The Hugging Face Speech-to-Speech CLI has replaced the legacy `--mode` flag with explicit sub-commands: use `serve` instead of `--mode realtime`, `local` instead of `--mode local`, and the new `talk` command for connecting audio clients to realtime endpoints.**

The `huggingface/speech-to-speech` repository recently restructured its command-line interface to improve clarity and extensibility. If you are migrating from the deprecated `--mode` flag to the modern sub-command structure, this guide explains the architectural changes in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) and provides exact replacements for your existing scripts.

## From Flags to Commands: The New CLI Structure

### The Legacy `--mode` Flag

Previously, users selected operation modes using a top-level `--mode` flag accepting values like `realtime` or `local`. This approach consolidated disparate functionalities under a single entry point, limiting flexibility as the toolkit expanded to support new interaction patterns.

### The New Sub-command Architecture

The updated CLI introduces three distinct sub-commands that replace the old flag-based system:

- **`serve`**: Runs the Realtime pipeline server (replaces `--mode realtime`)
- **`local`**: Executes the server and audio client together over a loop-back interface (replaces `--mode local`)
- **`talk`**: Connects a microphone and speakers to a Realtime endpoint (new functionality without legacy equivalent)

## How the CLI Handles Legacy Mode Migration

In [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py), the migration logic preserves backward compatibility while guiding users toward the new interface through explicit parsing stages.

### Legacy Mode Extraction

The `_extract_legacy_mode` function (lines 33-59) scans the raw `sys.argv` list before sub-parser invocation. It detects single occurrences of `--mode` or `--mode=value`, removes the flag from the argument list, and returns the discovered mode for subsequent mapping. This extraction prevents the top-level parser from failing when it encounters the deprecated flag.

### Command Mapping and Deprecation Warnings

The `_LEGACY_MODE_COMMANDS` dictionary maps legacy modes to modern commands:
- `realtime` → `serve`
- `local` → `local`

When a legacy mode is detected, the CLI prints a deprecation warning to **stderr** (lines 73-86), informing users of the upcoming removal and recommending the specific replacement command. This warning appears every time the legacy syntax is used, ensuring users notice the required changes.

### Error Handling for Invalid Usage

The parser validates legacy mode usage strictly to prevent ambiguity. Supplying `--mode` multiple times, without a value, or with an unsupported mode (such as `socket`) triggers immediate parser errors with clear messages pointing to the new command structure. These validation rules are verified in [`tests/test_cli_defaults.py`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_cli_defaults.py) (lines 16-24).

## Practical Migration Examples

Replace your existing commands according to the following patterns.

**Realtime server migration:**

```bash

# Old (deprecated) - emits warning to stderr

speech-to-speech --mode realtime --host 0.0.0.0 --port 8080

# New equivalent

speech-to-speech serve --host 0.0.0.0 --port 8080

```

**Local loop-back migration:**

```bash

# Old (deprecated)

speech-to-speech --mode local --local_audio_input_device 1

# New equivalent

speech-to-speech local --local_audio_input_device 1

```

**New talk command:**

The `talk` command has no legacy equivalent. It utilizes `RealtimeAudioClientConfig` from [`src/speech_to_speech/api/openai_realtime/audio_client.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/api/openai_realtime/audio_client.py) to stream audio:

```bash
speech-to-speech talk --url wss://example.com/realtime --model gpt-audio-1.5

```

## Key Source Files and Implementation Details

Understanding the source code helps clarify the migration path:

- **[`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py)**: Contains the main parser setup with three sub-parsers (lines 26-30), the `_extract_legacy_mode` function for backward compatibility, and the warning emission logic.
- **[`tests/test_cli_defaults.py`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_cli_defaults.py)**: Validates that legacy modes map correctly to new commands and that appropriate warnings are emitted when deprecated syntax is detected.
- **[`src/speech_to_speech/api/openai_realtime/audio_client.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/api/openai_realtime/audio_client.py)**: Defines `RealtimeAudioClientConfig`, which powers the new `talk` command's audio streaming capabilities.

## Why Migrate to Sub-commands?

The architectural shift from flags to commands delivers three primary benefits for the speech-to-speech toolkit:

- **Self-documenting interface**: Command names explicitly state the operation intent, eliminating ambiguity about whether you are starting a server or connecting a client.
- **Extensibility**: Adding future capabilities (such as batch processing or configuration management) requires new sub-commands rather than overloading a single flag with complex validation logic.
- **Clearer error messages**: The sub-parser architecture provides immediate, actionable feedback when arguments are missing or incorrect, rather than generic "invalid mode" errors.

## Summary

- Replace `--mode realtime` with the `serve` sub-command to start the Realtime pipeline server.
- Replace `--mode local` with the `local` sub-command for loop-back server-client operation.
- Use the new `talk` sub-command to connect audio devices to existing Realtime endpoints.
- The `_extract_legacy_mode` function in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) temporarily preserves backward compatibility but emits deprecation warnings to stderr.
- Update scripts immediately, as the legacy `--mode` flag will be removed in future releases according to the project's deprecation timeline.

## Frequently Asked Questions

### What happened to the `--mode` flag in Speech-to-Speech?

The `--mode` flag has been deprecated in favor of explicit sub-commands (`serve`, `talk`, `local`). While the CLI still accepts the flag for backward compatibility via the `_extract_legacy_mode` function, it prints a deprecation warning to stderr and internally maps the value to the appropriate modern command.

### How do I migrate a script that uses `--mode realtime`?

Change `speech-to-speech --mode realtime [args]` to `speech-to-speech serve [args]`. All previously supported arguments for the realtime server remain compatible with the `serve` sub-command, as the underlying [`s2s_pipeline.py`](https://github.com/huggingface/speech-to-speech/blob/main/s2s_pipeline.py) implementation remains unchanged.

### Is the `--mode` flag still supported?

Yes, but only temporarily. The `_LEGACY_MODE_COMMANDS` mapping in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) processes the flag and redirects it to new commands while emitting a warning. Future versions will remove this compatibility layer entirely, causing the parser to reject `--mode` as an unrecognized argument.

### What is the `talk` command used for?

The `talk` command connects local microphone and speaker devices to a remote or local Realtime endpoint using `RealtimeAudioClientConfig`. This functionality did not exist in the legacy `--mode` system and provides a dedicated client interface separate from the server operations managed by `serve` and `local`.