CLI Options

This page provides a comprehensive reference of all CLI options available across speak-mintlify commands.

Global Options

These options are available for the main CLI:

--version

flag

Display the installed version of speak-mintlify.

speak-mintlify --version

--help

flag

Display help information for commands.

speak-mintlify --help
speak-mintlify generate --help
speak-mintlify cleanup --help

Voice Configuration

Options for configuring TTS voices (used in generate command):

--voices

string

Command: generateComma-separated list of Fish Audio voice IDs.Example: --voices "voice-id-1,voice-id-2,voice-id-3"Alternative: Define in speaker-config.yaml:

voices:
  - id: voice-id-1
    name: English
  - id: voice-id-2
    name: Spanish

Notes:

Required unless using speaker-config.yaml
Voice IDs must exist in your Fish Audio account
Multiple voices enable multi-language or multi-speaker audio

--voice-names

string

Command: generateComma-separated list of human-readable voice names.Example: --voice-names "English,Spanish,French"Alternative: Define in speaker-config.yamlRequirements:

Must match the number of voice IDs
Names appear in the audio player UI
If omitted, defaults to “Voice 1”, “Voice 2”, etc.

Fish Audio API

Options for Fish Audio TTS service:

--api-key

string

Command: generateYour Fish Audio API key for generating text-to-speech.Example: --api-key "fa-12345678-abcd-efgh"Alternative: Set FISH_API_KEY environment variableRequired: Yes (via CLI or environment variable)How to get: Sign up at Fish Audio and generate an API key

S3 Storage Options

Options for configuring S3-compatible storage (used in both generate and cleanup commands):

--s3-bucket

string

Commands: generate, cleanupS3 bucket name where audio files are stored.Example: --s3-bucket "my-docs-audio"Alternative: Set S3_BUCKET environment variableRequired: Yes

--s3-region

string

default:"us-east-1"

Commands: generate, cleanupAWS region for your S3 bucket.Example: --s3-region "us-west-2"Alternative: Set S3_REGION environment variableDefault: us-east-1Common values:

us-east-1 - US East (N. Virginia)
us-west-2 - US West (Oregon)
eu-west-1 - EU (Ireland)
ap-southeast-1 - Asia Pacific (Singapore)
auto - For Cloudflare R2

--s3-endpoint

string

Commands: generate, cleanupCustom S3 endpoint URL for S3-compatible services.Examples:

Cloudflare R2: https://account-id.r2.cloudflarestorage.com
MinIO: https://minio.example.com
DigitalOcean Spaces: https://nyc3.digitaloceanspaces.com

Alternative: Set S3_ENDPOINT environment variableRequired: Only for non-AWS S3-compatible services

--s3-access-key-id

string

Commands: generate, cleanupS3 access key ID for authentication.Example: --s3-access-key-id "AKIAIOSFODNN7EXAMPLE"Alternative: Set S3_ACCESS_KEY_ID environment variableRequired: YesSecurity: Never commit credentials to version control

--s3-secret-access-key

string

Commands: generate, cleanupS3 secret access key for authentication.Example: --s3-secret-access-key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"Alternative: Set S3_SECRET_ACCESS_KEY environment variableRequired: YesSecurity: Never commit credentials to version control

--s3-public-url

string

Commands: generate, cleanupPublic CDN URL for accessing uploaded audio files.Examples:

Cloudflare R2: https://pub-abc123.r2.dev
Custom domain: https://cdn.example.com
Direct S3: https://bucket-name.s3.amazonaws.com

Alternative: Set S3_PUBLIC_URL environment variableRequired: YesNotes:

This URL is embedded in your documentation
Should be publicly accessible
Used to construct audio file URLs

--s3-path-prefix

string

default:"audio"

Commands: generate, cleanupDirectory prefix for organizing audio files in S3.Example: --s3-path-prefix "tts-audio"Default: audioStructure: Files are stored as {prefix}/{page-slug}/{voice-id}.mp3Example paths:

audio/quickstart/voice-1.mp3
audio/guides-setup/voice-en.mp3

Important: Use the same prefix for both generate and cleanup

Component Options

Options for MDX component configuration:

--component-import

string

default:"/snippets/audio-transcript.jsx"

Command: generateImport path for the audio player component.Example: --component-import "/components/AudioPlayer.jsx"Default: /snippets/audio-transcript.jsxUsage: This path is used in the import statement:

import AudioTranscript from '/snippets/audio-transcript.jsx';

Notes:

Must be a valid import path in your Mintlify project
Should point to your custom audio player component

--component-name

string

default:"AudioTranscript"

Commands: generate, cleanupName of the audio player component.Example: --component-name "AudioPlayer"Default: AudioTranscriptUsage: This is the component used in MDX:

<AudioTranscript hash="..." voices={[...]} />

Important:

Must match the component name exported from --component-import
Use the same name in both generate and cleanup

File Selection Options

Options for selecting which files to process:

--pattern

string

default:"**/*.mdx"

Commands: generate, cleanupGlob pattern for selecting MDX files.Default: **/*.mdx (all MDX files recursively)Examples:

# All MDX files
--pattern "**/*.mdx"

# Only files in docs directory
--pattern "docs/**/*.mdx"

# Only top-level guides
--pattern "guides/*.mdx"

# Specific sections
--pattern "{guides,api-reference}/**/*.mdx"

# Exclude certain directories
--pattern "!(node_modules|.next)/**/*.mdx"

Pattern syntax:

* - Matches any characters except /
** - Matches any characters including /
? - Matches single character
[abc] - Matches any character in brackets
{a,b} - Matches any of the patterns

Execution Options

Options that control how commands execute:

--dry-run

boolean

default:false

Commands: generate, cleanupSimulate execution without making actual changes.Example: --dry-runDefault: falseBehavior:

generate: Shows diff preview of MDX changes, doesn’t call APIs or write files
cleanup: Lists orphaned files without deleting them

Use cases:

Testing configuration before committing
Previewing changes
Auditing storage
CI/CD validation

Output example:

ℹ [DRY RUN] introduction.mdx

  Changes that would be made:
  @@ -1,3 +1,6 @@
  +import AudioTranscript from '/snippets/audio-transcript.jsx';
  +
   ---
   title: 'Introduction'
   ---

--verbose

boolean

default:false

Commands: generate, cleanupShow detailed processing information.Example: --verboseDefault: falseAdditional output:

Extracted text content for TTS
Content hashes
File-by-file processing status
Detailed error messages
Full result summary

Example output:

━━━ Extracted Text for TTS (1234 chars) ━━━
Introduction to speak-mintlify...
━━━ Hash: a1b2c3d4e5f6 ━━━

✔ Generated TTS for introduction.mdx

Details:
  introduction.mdx: 2 voice(s) generated
  quickstart.mdx: Content unchanged
  configuration.mdx: 2 voice(s) generated

Environment Variables

All CLI options can be set via environment variables:

CLI Option	Environment Variable	Required
`--api-key`	`FISH_API_KEY`	Yes (generate)
`--s3-bucket`	`S3_BUCKET`	Yes
`--s3-region`	`S3_REGION`	No (default: us-east-1)
`--s3-endpoint`	`S3_ENDPOINT`	No
`--s3-access-key-id`	`S3_ACCESS_KEY_ID`	Yes
`--s3-secret-access-key`	`S3_SECRET_ACCESS_KEY`	Yes
`--s3-public-url`	`S3_PUBLIC_URL`	Yes

Setting Environment Variables

Unix/Linux/macOS:

export FISH_API_KEY="your-api-key"
export S3_BUCKET="my-docs-audio"
export S3_REGION="us-east-1"
export S3_ACCESS_KEY_ID="your-access-key"
export S3_SECRET_ACCESS_KEY="your-secret-key"
export S3_PUBLIC_URL="https://cdn.example.com"

Windows (PowerShell):

$env:FISH_API_KEY="your-api-key"
$env:S3_BUCKET="my-docs-audio"
$env:S3_REGION="us-east-1"
$env:S3_ACCESS_KEY_ID="your-access-key"
$env:S3_SECRET_ACCESS_KEY="your-secret-key"
$env:S3_PUBLIC_URL="https://cdn.example.com"

Windows (CMD):

set FISH_API_KEY=your-api-key
set S3_BUCKET=my-docs-audio
set S3_REGION=us-east-1
set S3_ACCESS_KEY_ID=your-access-key
set S3_SECRET_ACCESS_KEY=your-secret-key
set S3_PUBLIC_URL=https://cdn.example.com

.env File

Create a .env file in your project root:

FISH_API_KEY=your-api-key
S3_BUCKET=my-docs-audio
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_PUBLIC_URL=https://cdn.example.com
S3_ENDPOINT=https://account.r2.cloudflarestorage.com

Note: Add .env to .gitignore to avoid committing secrets:

echo ".env" >> .gitignore

Configuration Precedence

Options are resolved in this order (highest priority first):

CLI options: --api-key "key"
Environment variables: FISH_API_KEY=key
Configuration file: speaker-config.yaml (for voices only)
Defaults: Built-in default values

Example

# Environment variable
export S3_REGION="us-west-2"

# CLI option overrides environment variable
speak-mintlify generate --s3-region "eu-west-1"
# Uses: eu-west-1

Option Validation

The CLI validates options before execution:

Required options: Error if missing
API key format: Must be valid Fish Audio key
S3 credentials: Tested during initialization
Voice IDs: Must be non-empty strings
Voice names: Must match voice ID count
Glob patterns: Must be valid glob syntax
URLs: Must be valid HTTP/HTTPS URLs

Validation Errors

# Missing required option
Error: FISH_API_KEY is required for generate command

# Invalid voice configuration
Error: Number of voice names (2) must match number of voice IDs (3)

# S3 authentication failed
Error: S3 authentication failed: InvalidAccessKeyId

# Invalid pattern
Error: Invalid glob pattern: [unclosed-bracket

Best Practices

1. Use Environment Variables for Secrets

Never pass secrets via CLI options in scripts:

# Bad - secrets in command history
speak-mintlify generate --api-key "secret-key" --s3-secret-access-key "secret"

# Good - secrets in environment
export FISH_API_KEY="secret-key"
export S3_SECRET_ACCESS_KEY="secret"
speak-mintlify generate

2. Use Configuration Files for Voice Management

Manage voices in speaker-config.yaml:

voices:
  - id: voice-id-1
    name: English (US)
  - id: voice-id-2
    name: Spanish (MX)
  - id: voice-id-3
    name: French (FR)

Then run without --voices flags:

speak-mintlify generate

3. Always Test with Dry Run

# Test configuration first
speak-mintlify generate --dry-run --verbose

# Review output, then execute
speak-mintlify generate

4. Use Consistent Options Across Commands

# Use same configuration for generate and cleanup
PREFIX="audio"
COMPONENT="AudioTranscript"

speak-mintlify generate --s3-path-prefix "$PREFIX" --component-name "$COMPONENT"
speak-mintlify cleanup --s3-path-prefix "$PREFIX" --component-name "$COMPONENT"

5. Leverage Verbose Mode for Debugging

# Get detailed output when troubleshooting
speak-mintlify generate --verbose 2>&1 | tee debug.log

Get Started

Configuration

Commands

Guides

Reference

Global Options

Voice Configuration

Fish Audio API

S3 Storage Options

Component Options

File Selection Options

Execution Options

Environment Variables

Setting Environment Variables

.env File

Configuration Precedence

Example

Option Validation

Validation Errors

Best Practices

1. Use Environment Variables for Secrets

2. Use Configuration Files for Voice Management

3. Always Test with Dry Run

4. Use Consistent Options Across Commands

5. Leverage Verbose Mode for Debugging

Build docs developers (and LLMs) love

Get Started

Configuration

Commands

Guides

Reference

​Global Options

​Voice Configuration

​Fish Audio API

​S3 Storage Options

​Component Options

​File Selection Options

​Execution Options

​Environment Variables

​Setting Environment Variables

​.env File

​Configuration Precedence

​Example

​Option Validation

​Validation Errors

​Best Practices

​1. Use Environment Variables for Secrets

​2. Use Configuration Files for Voice Management

​3. Always Test with Dry Run

​4. Use Consistent Options Across Commands

​5. Leverage Verbose Mode for Debugging

Build docs developers (and LLMs) love

Global Options

Voice Configuration

Fish Audio API

S3 Storage Options

Component Options

File Selection Options

Execution Options

Environment Variables

Setting Environment Variables

.env File

Configuration Precedence

Example

Option Validation

Validation Errors

Best Practices

1. Use Environment Variables for Secrets

2. Use Configuration Files for Voice Management

3. Always Test with Dry Run

4. Use Consistent Options Across Commands

5. Leverage Verbose Mode for Debugging