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

> Easily migrate from deprecated --mode flags to new serve and local commands in Hugging Face Speech-to-Speech. Update your workflow and keep all arguments the same.

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

---

**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`](https://github.com/huggingface/speech-to-speech/blob/main/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):**

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

```

**New:**

```bash
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`](https://github.com/huggingface/speech-to-speech/blob/main/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):**

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

```

**New:**

```bash
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`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) |
| **`serve` sub-command** | Launches only the Realtime server | [`src/speech_to_speech/s2s_pipeline.py#L606-L607`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/s2s_pipeline.py) |
| **`local` sub-command** | Launches server plus loopback audio client | [`src/speech_to_speech/s2s_pipeline.py#L606-L607`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/s2s_pipeline.py) |
| **Test coverage** | Verifies mapping and deprecation warning | [`tests/test_cli_defaults.py#L288-L303`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_cli_defaults.py) |

## 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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_cli_defaults.py) provides additional validation patterns you can reference.