vf

Command-line interface for the Realtime API.

Important

This CLI is not yet ready for production use. To complete setup please follow the steps outlined in your workspace. Delete this section before > publishing to a package manager.

Summary

Realtime: Realtime gateway API service

Table of Contents

• vf
  • CLI Installation
  • Shell Completion
  • CLI Example Usage
  • Authentication
  • Available Commands
  • Request Body Input
  • Server Selection
  • Output Formats
  • Error Handling
  • Diagnostics
• Development
  • Maturity
  • Contributions

CLI Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/voiceflow/cli/main/scripts/install.sh | bash

Quick Install (Windows PowerShell)

iwr -useb https://raw.githubusercontent.com/voiceflow/cli/main/scripts/install.ps1 | iex

Go Install

Alternatively, install directly via Go:

go install github.com/voiceflow/cli/cmd/vf@latest

Manual Download

Download pre-built binaries for your platform from the releases page.

Shell Completion

Shell completions are available for Bash, Zsh, Fish, and PowerShell.

Bash

# Add to ~/.bashrc:
source <(vf completion bash)

# Or install permanently:
vf completion bash > /etc/bash_completion.d/vf

Zsh

# Add to ~/.zshrc:
source <(vf completion zsh)

# Or install permanently:
vf completion zsh > "${fpath[1]}/_vf"

Fish

vf completion fish | source

# Or install permanently:
vf completion fish > ~/.config/fish/completions/vf.fish

PowerShell

vf completion powershell | Out-String | Invoke-Expression

CLI Example Usage

Example

vf workspace list --token 'Bearer test_token'

Authentication

Authentication credentials can be configured in four ways (in order of priority):

1. Command-line flags

Pass credentials directly as flags to any command:

vf --token <value> <command> [arguments]

2. Environment variables

Set credentials via environment variables:

Variable	Description
VF_TOKEN	Voiceflow bearer token

3. OS Keychain (recommended for workstations)

Credentials are stored securely in your operating system's keychain when you run:

vf configure

Secret credentials (tokens, API keys, passwords) are automatically stored in:

• macOS: Keychain
• Linux: GNOME Keyring / KWallet (via D-Bus Secret Service)
• Windows: Windows Credential Locker

If no keychain is available (e.g., in CI environments), credentials fall back to the config file.

4. Configuration file

Run the interactive configure command to store non-secret settings:

vf configure

Configuration is stored in ~/.config/vf/config.yaml.

Available Commands

Available commands

workspace

• list - List workspaces
• create - Create workspace
• get - Get workspace
• update - Update workspace
• delete - Delete workspace

project

• list - List projects
• create - Create project
• get - Get project
• update - Update project
• delete - Delete project

environment

• list - List environments
• merge - Merge environments
• update-traffic-split - Update traffic split
• get - Get environment
• update - Update environment
• delete - Delete environment
• compile - Compile environment
• clone - Clone environment
• publish - Publish environment

variable

• list - List variables
• create - Create variable
• get - Get variable
• update - Update variable
• delete - Delete variable

playbook

• list - List playbooks
• create - Create playbook
• get - Get playbook
• update - Update playbook
• delete - Delete playbook

api-tool

• list - List API tools
• create - Create API tool
• get - Get API tool
• update - Update API tool
• delete - Delete API tool

api-tool-variable

• list - List variables
• create - Create variable
• get - Get variable
• update - Update variable
• delete - Delete variable

transcript

• search - Search transcripts
• get - Get transcript

property

• list - List properties
• create - Create property
• get - Get property
• update - Update property
• delete - Delete property
• set-value - Set property value

function

• list - List functions
• create - Create function
• get - Get function
• update - Update function
• delete - Delete function

function-variable

• list - List variables
• create - Create variable
• get - Get variable
• update - Update variable
• delete - Delete variable

path

• list - List paths
• create - Create path
• get - Get path
• update - Update path
• delete - Delete path

evaluation

• list - List evaluations
• create - Create evaluation
• get - Get evaluation
• update - Update evaluation
• delete - Delete evaluation
• run - Run evaluation

document

• list - List documents
• create-url - Create URL document
• create-text - Create text document
• create-table - Create table document
• get - Get document
• update - Update document
• delete - Delete document

agent

• get - Get agent
• update - Update agent

mcp-server

• list - List MCP servers
• create - Create MCP server
• get - Get MCP server
• update - Update MCP server
• delete - Delete MCP server
• sync - Sync MCP server

mcp-tool

• list - List MCP tools
• get - Get MCP tool

tool

• list - List tools
• create - Create tool
• get - Get tool
• update - Update tool
• delete - Delete tool

knowledge-base

• query - Query knowledge base

conversation

• send - Send

state

• get - Get state
• update - Update state
• delete - Delete state
• update-variables - Update variables

analytics

query

• call-count - Query call count
• call-duration - Query call duration
• workspace-transcript-count - Query workspace transcript count
• project-transcript-count - Query project transcript count
• project-transcript-cost - Query transcript cost
• workspace-interaction-count - Query workspace interaction count
• project-interaction-count - Query project interaction count
• organization-token-usage - Query organization token usage
• workspace-token-usage - Query workspace token usage
• project-token-usage - Query project token usage
• hourly-organization-token-usage - Query hourly organization token usage
• hourly-project-token-usage - Query hourly project token usage
• daily-token-usage - Query daily token usage
• entity-token-usage - Query entity token usage
• category-token-usage - Query category token usage
• playbook-usage - Query playbook usage
• workflow-usage - Query workflow usage
• prompt-usage - Query prompt usage
• intent-usage - Query intent usage
• function-usage - Query function usage
• api-tool-usage - Query API tool usage
• mcp-tool-usage - Query MCP tool usage
• knowledge-base-document-usage - Query knowledge base document usage
• integration-usage - Query integration usage
• unique-user-count - Query unique user count

test

• list - List tests
• create - Create test
• get - Get test
• update - Update test
• delete - Delete test

turn

• list - List turns
• create - Create turn
• get - Get turn
• update - Update turn
• delete - Delete turn

check

• list - List checks
• create - Create check
• get - Get check
• update - Update check
• delete - Delete check

run

• search - Search runs
• create - Create run
• get - Get run

Request Body Input

Operations that accept a request body support three input methods, with a clear priority chain:

Individual flags (highest priority)

vf <command> --name "Jane" --age 30

--body flag

Provide the entire request body as a JSON string:

vf <command> --body '{"name": "John", "age": 30}'

Individual flags override --body values:

# Result: {name: "Jane", age: 30}
vf <command> --body '{"name": "John", "age": 30}' --name "Jane"

Stdin piping (lowest priority)

Pipe JSON into any command that accepts a request body:

echo '{"name": "John", "age": 30}' | vf <command>

Individual flags override stdin values:

# Result: {name: "Jane", age: 30}
echo '{"name": "John", "age": 30}' | vf <command> --name "Jane"

This is useful for chaining commands, reading from files, or scripting:

# Read body from a file
vf <command> < request.json

# Pipe from another command
curl -s https://example.com/data.json | vf <command>

Priority

When multiple input methods are used, the priority is:

Priority	Source	Description
1 (highest)	Individual flags	--name "Jane" always wins
2	--body flag	Whole-body JSON via flag
3 (lowest)	Stdin	Piped JSON input

Server Selection

Override Server URL

Use --server-url to override the server URL entirely, bypassing any named or indexed server selection:

vf --server-url https://custom-api.example.com <command> [arguments]

Precedence: --server-url > --server > default

Output Formats

Every command supports a --output-format flag that controls how the response is rendered to stdout.

Available formats

Format	Flag	Description
Pretty	--output-format pretty (default)	Aligned key-value pairs with color, nested indentation. Human-readable at a glance.
JSON	--output-format json	JSON output. Passthrough when the response is already JSON (preserves original field order and numeric precision). Falls back to typed marshaling otherwise.
YAML	--output-format yaml	YAML output via standard marshaling.
Table	--output-format table	Tabular output for array responses.
TOON	--output-format toon	Token-Oriented Object Notation — a compact, line-oriented format that typically uses 30–60% fewer tokens than JSON. Well-suited for piping responses into LLM prompts.

# Default pretty output
vf <command>

# Machine-readable JSON
vf <command> --output-format json

# TOON for LLM-friendly compact output
vf <command> --output-format toon

# Pipe JSON to jq without using --output-format
vf <command> --output-format json | jq '.fieldName'

jq filtering

Use --jq to filter or transform the response inline using a jq expression. This always outputs JSON and overrides --output-format:

# Extract a single field
vf <command> --jq '.name'

# Filter an array
vf <command> --jq '.items[] | select(.active == true)'

Color control

Use --color to control terminal colors:

Value	Behavior
auto (default)	Color when stdout is a TTY, plain text otherwise
always	Always colorize
never	Never colorize

The NO_COLOR and FORCE_COLOR environment variables are also respected.

Streaming and pagination

When using --all (pagination) or streaming operations, output is written incrementally as items arrive:

Format	Streaming behavior
json	One compact JSON object per line (NDJSON)
yaml	YAML documents separated by ---
toon	One TOON-encoded object per block, separated by blank lines
pretty (default)	Pretty-printed items separated by blank lines

Error Handling

The CLI uses standard exit codes to indicate success or failure:

Exit Code	Meaning
0	Success
1	Error (API error, invalid input, etc.)

On success, the response data is printed to stdout as JSON. On failure, error details are printed to stderr.

# Capture output and handle errors
vf ... > output.json 2> error.log
if [ $? -ne 0 ]; then
  echo "Error occurred, see error.log"
fi

Diagnostics

The CLI includes two diagnostic flags available on all commands:

Dry Run

Preview what would be sent without making any network calls:

vf <command> --dry-run

Output goes to stderr and includes:

• HTTP method and URL
• Request headers (sensitive values redacted)
• Request body preview (sensitive fields redacted)

The command exits successfully without contacting the API. This is useful for verifying request construction before executing.

Debug

Log request and response diagnostics while running normally:

vf <command> --debug

Debug output goes to stderr and includes:

• Request method, URL, headers, and body preview
• Response status, headers, and body preview
• Transport errors (if any)

The command still executes normally and produces its regular output on stdout.

Flag Precedence

If both --dry-run and --debug are set, --dry-run takes precedence and no network calls are made.

Security

Sensitive information is automatically redacted in diagnostic output:

• Headers: Authorization, Cookie, Set-Cookie, X-API-Key, and other security headers show [REDACTED]
• Body: JSON fields named password, secret, token, api_key, client_secret, etc. show [REDACTED]

Diagnostic output should still be treated as potentially sensitive operational data.

Development

Maturity

This CLI is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this CLI, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

CLI Created by Speakeasy