Skip to main content

CLI Reference

This page provides a detailed reference for all available command-line options for hns.

Synopsis​

hns [OPTIONS]

Core Options​

These are the most common flags you'll use with hns.

--last​

Transcribe the last recorded audio file without starting a new recording.

This flag is a powerful recovery mechanism. If hns crashes, hangs, or is terminated unexpectedly during transcription (e.g., due to high memory usage), your recording is not lost. You can simply run hns --last to retry the transcription on the saved audio file.

Use Case: Workflow Recovery

The --last flag is especially useful in chained commands. If a downstream tool fails, you don't have to re-record your thoughts.

# Original command fails after you've finished speaking
hns | llm "summarize this"
# llm command errors out

# Just retry the transcription and pipe it again
hns --last | llm "summarize this"

The last recorded audio is always saved to a temporary file. The location depends on your operating system:

  • macOS: ~/Library/Caches/hns/last_recording.wav
  • Linux: ~/.cache/hns/last_recording.wav
  • Windows: %LOCALAPPDATA%\hns\Cache\last_recording.wav

--language <LANGUAGE_CODE>​

Force transcription to use a specific language instead of relying on auto-detection. Use the two-letter language code (e.g., en, es, ja).

# Force transcription in Japanese
hns --language ja

# Force transcription in Spanish
hns --language es

This can also be set via the HNS_LANG environment variable. The command-line flag takes precedence if both are set.

export HNS_LANG="ja"
hns # Will use Japanese
hns --language es # Will use Spanish for this run

Configuration pages lists all the supported languages along with their ISO 639-1 codes.

--list-models​

List all available Whisper models that can be used for transcription and then exit. This command does not perform any recording or transcription.

hns --list-models

Find the list of available models on the configuration page along with model recommendation guide for help choosing the right model for your needs.

--help​

Display the help message for the hns CLI, showing all available commands and options, then exit.

hns --help

Recording Options​

These options control the audio recording parameters. Most users can stick with the defaults, as Whisper models are optimized for them.

--sample-rate <INTEGER>​

The audio sample rate in Hz for recording.

  • Default: 16000

Whisper models are trained on 16kHz audio, so this value should generally not be changed.

--channels <INTEGER>​

The number of audio channels for recording.

  • Default: 1 (mono)

Mono is sufficient for speech transcription and is the expected format for Whisper.