Authentication

Voiceflow API Key

voiceflow-cli uses Voiceflow APIs. To interact with your Vocieflow projects you will need a Voiceflow API Key. You can get your API Key in your Voiceflow project > Integration page. You can pass the API Key to the CLI using the --voiceflow-api-key flag or by setting the VF_API_KEY environment variable. voiceflow-cli also works with .env files. You can create a .env file in the root of your project and add the VF_API_KEY variable to it.

The voiceflow-cli source code is open source, you can check it out here to learn more about the actions the tool performs.

Base URL

The base URL for the Voiceflow API is https://<api>.<subdomain>.voiceflow.com. The default value is without subdomain: https://<api>.voiceflow.com. If you are using a different Voiceflow environment, you can pass the subdomain using the --voiceflow-subdomain flag or by setting the VF_SUBDOMAIN environment variable.

Custom URLs (Ephemeral / Non-standard Environments)

For environments where the URL pattern does not follow the standard <service>.<subdomain>.voiceflow.com convention (e.g. ephemeral review-app deployments), you can override each service URL individually:

Service	CLI Flag	Environment Variable	Default
Creator API	--voiceflow-api-url	VF_API_URL	https://api.voiceflow.com
General Runtime	--voiceflow-runtime-url	VF_RUNTIME_URL	https://general-runtime.voiceflow.com
Analytics API	--voiceflow-analytics-url	VF_ANALYTICS_URL	https://analytics-api.voiceflow.com

These custom URL flags take priority over --voiceflow-subdomain. You only need to set the ones your command actually uses.

Example – pointing to a custom environment:

voiceflow test execute evals \
  --voiceflow-api-url https://your-custom-api.example.com \
  --voiceflow-runtime-url https://your-custom-runtime.example.com \
  --voiceflow-analytics-url https://your-custom-analytics.example.com

Or via a .env file / environment variables:

VF_API_URL=https://your-custom-api.example.com
VF_RUNTIME_URL=https://your-custom-runtime.example.com
VF_ANALYTICS_URL=https://your-custom-analytics.example.com

URL resolution priority

Custom URL (--voiceflow-api-url, etc.) > Subdomain (--voiceflow-subdomain) > Default (voiceflow.com).

Open AI PI Key

voiceflow-cli uses Open AI APIs. To interact with Open AI you will need an API Key. You can get your API Key in your Open AI account. You can pass the API Key to the CLI using the --openai-api-key flag or by setting the OPENAI_API_KEY environment variable. voiceflow-cli also works with .env files. You can create a .env file in the root of your project and add the OPENAI_API_KEY variable to it.

OpenAI Base URL (optional)

If you need to target a different OpenAI endpoint (for example EU data residency), you can override the base URL by using:

• CLI flag: --openai-base-url
• Environment variable: OPENAI_BASE_URL

Example:

voiceflow test execute evals --openai-base-url https://eu.api.openai.com/v1

If not provided, voiceflow-cli defaults to https://api.openai.com/v1.