# Hume CLI Documentation

The Hume CLI provides a simple interface for generating speech, saving voices, and exploring the features of the Hume TTS API. This guide shows how to get started using Hume’s Text-to-Speech capabilities using the Hume CLI. It demonstrates:

1. Converting text to speech with a new voice.
2. Saving a voice to your voice library for future use.
3. Giving “acting instructions” to modulate the voice.
4. Generating multiple variations of the same text at once.
5. Providing context to maintain consistency across multiple generations.

### Installation

Install the Hume CLI using npm:

```
npm install -g @humeai/cli
```

See usage information by running `hume tts --help`.

### Authentication

Authenticate using the CLI:

```
hume login
```

This will open a browser window to the Hume AI platform, where you can retrieve your API key, and then prompt you to enter your API key.

### Calling Text-to-Speech

To use Hume TTS,

- Provide the text you want to speak as a positional argument.
- Provide the optional `--description` flag to control how the voice sounds. If you don’t provide a description, Hume will examine the text and attempt to determine an appropriate voice.

```
hume tts "Take an arrow from the quiver." \
  --description "A refined, British aristocrat"
```

By default, the CLI will

- save the audio to the output directory (defaults to `./hume-tts-output`)
- attempt to play it automatically.
- display the `generation_id` for the speech, for future reference

### Saving voices

When you find a voice you like, use the `hume voices create` command to give it a name and save it to your voice library for future use. You can specify the generation ID:

```
hume voices create \
  --name aristocrat \
  --generation-id GENERATION_ID
```

or, alternatively, use the `--last` flag to save the most recent generation.

```
hume voices create --name aristocrat --last
```

### Continuity

To use a voice from your library, specify its name.

```
hume tts "Now take a bow." --voice-name aristocrat
```

If the speech should sound like it follows from previous speech, you can provide the `--context-generation-id` flag with the `generation_id` of the previous speech.

```
# For example if PREVIOUS_GENERATION_ID refers to speech
# about archery, 'bow' will be pronounced to rhyme with
# 'toe' and not 'cow'.
hume tts "Now take a bow." \
  --voice-name aristocrat \
  --context-generation-id GENERATION_ID
```

Alternatively, use the `--last` flag to continue from the most recent generation.

```
hume tts "Now take a bow." --voice-name aristocrat --last
```

### Acting Instructions

If you specify both a voice and a description, the description acts as “acting instructions”. It will keep the character of the specified voice, but modulated to match the description.

```
hume tts "Does he even know how to use that thing?" \
  --voice-name aristocrat \
  --description "Murmured softly, with a heavy dose of sarcasm and contempt"
```

### Generating multiple variations

To generate multiple variations of the same text at once, use the `--num-generations` flag.

```
hume tts "Now aim at the bullseye, nock your arrow, draw, and..." \
  --voice-name aristocrat \
  --num-generations 3
```

### Other features

```
# Read from stdin
cat poem.txt | hume tts -

# Machine-readable output
hume tts "Hello" --reporter-mode json

# Session settings last for the duration of the terminal session
hume session set tts.voiceName aristocrat
hume session set tts.outputDir ~/audio

# Global settings persist until changed
hume config set tts.play none
hume config set reporterMode json
# Clear them like this (will also log you out).
hume config reset
```