SpokeDo CLI

A command-line tool for uploading audio files to SpokeDo scenarios.

Installation

# From the packages/spokedo directory
npm install
npm run build
npm link  # Makes 'spokedo' command available globally

Configuration

Before uploading files, you need to configure your credentials:

Option 1: Interactive configuration

spokedo configure

This will prompt you for:

• Supabase URL: Your project's Supabase URL (e.g., https://xxx.supabase.co)
• API Key: Your SpokeDo API key (starts with spk_)

Configuration is saved to ~/.spokedo/config.json with restricted permissions (600).

Option 2: Command-line options

spokedo configure --url https://xxx.supabase.co --api-key spk_xxx

Option 3: Environment variables

export SPOKEDO_SUPABASE_URL=https://xxx.supabase.co
# or
export SUPABASE_URL=https://xxx.supabase.co

export SPOKEDO_API_KEY=spk_xxx

Environment variables take precedence over the config file.

Usage

Upload audio files

Upload all audio files from the current directory to a scenario:

spokedo upload <scenario-id>

Options

• -d, --directory <path>: Directory containing audio files (default: current directory)
• -r, --recursive: Search for audio files recursively
• -c, --concurrency <n>: Number of concurrent uploads (default: 3)
• --dry-run: List files that would be uploaded without uploading

Examples

# Upload audio files from current directory
spokedo upload 123e4567-e89b-12d3-a456-426614174000

# Upload from a specific directory
spokedo upload 123e4567-e89b-12d3-a456-426614174000 -d /path/to/audio

# Upload recursively with 5 concurrent uploads
spokedo upload 123e4567-e89b-12d3-a456-426614174000 -r -c 5

# Dry run to see what would be uploaded
spokedo upload 123e4567-e89b-12d3-a456-426614174000 --dry-run

View configuration

spokedo config

Supported Audio Formats

• .mp3 - MPEG Audio Layer III
• .wav - Waveform Audio File Format
• .ogg - Ogg Vorbis
• .webm - WebM Audio
• .m4a - MPEG-4 Audio
• .aac - Advanced Audio Coding
• .flac - Free Lossless Audio Codec
• .mp4 - MPEG-4 Video (audio will be extracted)

Getting an API Key

1. Log in to your SpokeDo dashboard
2. Go to Sources and create a new source with platform type "API"
3. Copy the generated API key (shown only once)
4. Use this API key with the CLI

Permission Control

API keys are scoped to specific sources:

• Each source can have its own API key
• API keys are stored as SHA-256 hashes in the database
• Only scenarios linked to the source with a matching API key can receive uploads
• API keys can be rotated from the dashboard

Exit Codes

• 0: Success
• 1: Error (configuration missing, upload failed, etc.)

Troubleshooting

"Not configured" error

Run spokedo configure or set the required environment variables.

"Invalid API key format" error

Ensure your API key starts with spk_ and is the full key (47 characters total).

"Scenario not found" error

Verify the scenario ID is correct and that you have access to it.

"Invalid API key for this scenario" error

The API key provided doesn't match the source linked to the scenario. Make sure you're using the API key from the correct source.

"This scenario does not accept API uploads" error

The scenario's source must have platform type "API". Create a new API source or update the existing one.