Configure vvctl

The vvctl tool uses several configuration files to manage users, servers, and contexts.

Configuration Files

The tool uses the following folders by default:

Operating System	Config folder	Data folder
macOS / Linux	`XDG_CONFIG_HOME/vvctl` (fallback `~/.config/vvctl`)	`XDG_DATA_HOME/vvctl` (fallback `~/.local/share/vvctl`)
Windows	`%APPDATA%\\vvctl`	`%LOCALAPPDATA%\\vvctl`

The following example shows a config.yml configuration file:

###
#  - name: name_of_the_user_entry
#    user:
#      token: API token (personal, namespace, or workspace)
#      namespace: The name of the namespace. Required for Self-Managed.
#      workspace: The name of the workspace. Required for Managed Service with a Workspace API token.
#      email: The email address for the Managed Service account.
#      password: The password for the Managed Service account.
users: []
###
#  - name: name_of_the_server_entry
#    server:
#      host: The URL to the Ververica Unified Streaming Data Platform instance.

servers: []
###
#  - name: name_of_the_context
#    context:
#      user: reference_to_existing_user
#      server: reference_to_existing_server
contexts: []

current-context: null
warning_permissions: true
agent_version: 1.9.2-1
agent_charts: oci://registry.ververica.cloud/agent-charts/vv-agent
agent_name: vv-agent

where

Property	Description
`users`	A list of user accounts.
`servers`	A list of server instances.
`contexts`	A list of contexts that associate a user with a server.
`current-context`	The context currently in use.
`warning_permissions`	When true, `vvctl` checks config file permissions (600) and warns you if they don't match.
`agent_*`	Parameters for the BYOC agent installation. Leave these at their default values.

Contexts

The vvctl tool uses contexts to connect to the three deployment options of the Ververica Unified Streaming Data Platform: Managed Service, Bring Your Own Cloud (BYOC), and Self-Managed.

A context is defined by a user and a server.

User

A user represents an account on the Ververica Unified Streaming Data Platform and contains the following properties:

Property	Description
`token`	An API token (personal, namespace, or workspace).
`namespace`	The name of the namespace. Required for Self-Managed instances.
`workspace`	The name of the workspace. Required for Managed Service instances using a workspace API token.
`email`	The email address associated with the account.
`password`	The password associated with the account.

Server

A server represents an instance of the Ververica Unified Streaming Data Platform.

Property	Description
`host`	The URL of the Ververica Unified Streaming Data Platform instance.

An example of a contexts configuration could be

servers:
  - name: vvp
    server:
      host: https://vvp.internal.ververica.cloud
  - name: vvc
    server:
      host: https://app.ververica.cloud
users:
  - name: qa-team
    user:
      email: qa-team@ververica.com
      password: qa-pass
  - name: frontend-team-ws-dev
    user:
      email: frontend-team@ververica.com
      token: token-vvc
      workspace: es223ysdf2j34
contexts:
  - name: qa-vvp
    context:
      server: vvp
      user: qa-team
  - name: qa-vvc
    context:
      server: vvc
      user: qa-team
  - name: frontend-vvc-ws-dev
    context:
      server: vvc
      user: frontend-team-ws-dev
current-context: qa-vvc

Notes:

If no context is defined, the CLI uses the Managed Service server and prompts you to enter your login credentials.
The server name vvc is reserved for the built-in Managed Service server. Defining a server with this name will fail. A built-in context, vvc (built-in), is available and always points to https://app.ververica.cloud.
You can use the VV_CONFIG environment variable to point to an alternate configuration file for project-specific setups:

❯ cat ./ververica-config.yml
servers:
  - name: vvp
    server:
      host: https://vvp.internal.ververica.cloud
users:
  - name: dev-ns-default
    user:
      email: dev@ververica.com
      token: token-vvc
      namespace: default
contexts:
  - name: dev
    context:
      server: vvp
      user: dev-ns-default
current-context: dev

❯ VV_CONFIG=./ververica-config.yml vvctl get deployments

Configuration Commands

Use the config command to manage contexts, servers, and users.

Get Contexts (`get-contexts`)

Lists one or all contexts, or shows the current context.

Syntax

vvctl config get-contexts [NAME | --current] [--output=table|yaml|json]

Parameters

NAME (optional): Show a single context by name.
--current (optional): Show only the current context.
--output (optional): Specify the output format: table (default), yaml, or json.

Examples

vvctl config get-contexts
vvctl config get-contexts vvp-stage-ns-default-viewer
vvctl config get-contexts --current
vvctl config get-contexts --output=yaml

Show Current Context (`current-context`)

Prints the name of the active context.

Syntax

vvctl config current-context

Examples

vvctl config current-context
# Output: vvc-stage

Switch Context (`use-context`)

Sets the current-context in the configuration file.

Syntax

vvctl config use-context NAME

Parameters

NAME (required): The name of the context to switch to.

Examples

vvctl config use-context vvp-stage-ns-default-viewer

Get Servers (`get-servers`)

Lists server entries from the configuration.

Syntax

vvctl config get-servers [--output=table|yaml|json]

Parameters

--output (optional): Specify the output format: table (default), yaml, or json.

Examples

vvctl config get-servers
vvctl config get-servers --output=json

Get Users (`get-users`)

Lists user entries without exposing secrets (tokens or passwords are never shown).

Syntax

vvctl config get-users [--output=table|yaml|json]

Parameters

--output (optional): Specify the output format: table (default), yaml, or json.

Examples

vvctl config get-users
vvctl config get-users --output=yaml

Set Context (`set-context`)

Creates or updates a context entry (merges if it exists). You can also import contexts from a file.

Syntax

vvctl config set-context [NAME | --current | --file FILE] [--server=SERVER_NAME] [--user=USER_NAME]

Parameters

NAME (optional): The name of the context to create or update.
--current (optional): Apply changes to the current context.
--file FILE (optional): Import or merge contexts (and related users, servers, and current-context) from another configuration file.
--server=SERVER_NAME (optional): The server reference for the context.
--user=USER_NAME (optional): The user reference for the context.

Examples

# Create a new context
vvctl config set-context local-vvp --user=local-admin --server=local-server
 
# Import contexts/users/servers from another file
vvctl config set-context --file ./local_vvp_config.yml
 
# Modify the current context (e.g., swap user)
vvctl config set-context --current --user=qa-team-credentials

Set Server (`set-server`)

Creates or updates a server entry (merges if it exists).

Syntax

vvctl config set-server NAME --host=HOST_URL

Parameters

NAME (required): The name of the server entry.
--host (required): The host URL (Ververica Platform Public API-compatible base URL).

Examples

vvctl config set-server local-vvp --host=http://127.0.0.1:8585

Set User (`set-user`)

Creates or updates a user authentication entry (merges if it exists).

Syntax

vvctl config set-user NAME \
  [--token=TOKEN] \
  [--namespace=NAMESPACE] \
  [--workspace=WORKSPACE] \
  [--email=EMAIL] \
  [--password=PASSWORD]

Parameters

NAME (required): The name of the user entry.
--token (optional): API token, Personal Access Token (PAT), or console token.
--namespace (optional): The namespace (mandatory for Ververica Platform tokens; also used for Ververica Cloud multi-namespace cases).
--workspace (optional): The workspace (mandatory for Ververica Cloud workspace tokens).
--email (optional): Ververica Cloud login email.
--password (optional): Ververica Cloud login password (if omitted, the CLI prompts for it on 401 Unauthorized errors).

Examples

# Credentials-based user
vvctl config set-user local-admin --email=admin@local --password=l0ca1
 
# Token user for VVP namespace
vvctl config set-user stage-default-editor-token --token=ey... --namespace=default
 
# Token user for VVC workspace
vvctl config set-user stage-ws-e2e-editor-token --token=ey... --workspace=e2e-test-connectors
 
# Token user for VVC workspace + namespace
vvctl config set-user stage-ws-dev-ns-frontend-editor-token --token=ey... --workspace=dev-ws --namespace=frontend-ns

Delete User (`delete-user`)

Removes a user entry. This command returns an error if the user is referenced by any context.

Syntax

vvctl config delete-user NAME

Parameters

NAME (required): The name of the user entry to delete.

Examples

vvctl config delete-user local-admin

Delete Server (`delete-server`)

Removes a server entry. This command returns an error if the server is referenced by any context.

Syntax

vvctl config delete-server NAME

Parameters

NAME (required): The name of the server entry to delete.

Examples

vvctl config delete-server localhost

Delete Context (`delete-context`)

Removes a context entry.

Syntax

vvctl config delete-context NAME

Parameters

NAME (required): The name of the context to delete.

Examples

vvctl config delete-context local-dev-admin

View Config (`view`)

Shows the effective configuration (default output is YAML). Secrets are masked unless --raw is specified.

Syntax

vvctl config view [--raw] [--minify] [--output=yaml|json]

Parameters

--raw (optional): Include sensitive fields (token, password) instead of masking with ***.
--minify (optional): Show only what current-context uses (that context, plus referenced server, user, and root fields).
--output (optional): Specify the output format: yaml (default) or json.

Examples

vvctl config view
vvctl config view --output=json
vvctl config view --minify
vvctl config view --raw

Use Environment Variables

You can set environment variables to provide default values for certain options. Environment variables take priority and override values in the configuration file.

Environment Variable	Description
`VV_API_TOKEN`	The API token used for authentication.
`VV_EMAIL` and `VV_PASSWORD`	The email address and password used for authentication.
`VV_WORKSPACE`	The default workspace ID.
`VV_NAMESPACE`	The default namespace ID.
`VV_CONFIG`	The path to the configuration file you want to use.

Configuration Files​

Contexts​

User​

Server​

Configuration Commands​

Get Contexts (get-contexts)​

Show Current Context (current-context)​

Switch Context (use-context)​

Get Servers (get-servers)​

Get Users (get-users)​

Set Context (set-context)​

Set Server (set-server)​

Set User (set-user)​

Delete User (delete-user)​

Delete Server (delete-server)​

Delete Context (delete-context)​

View Config (view)​

Use Environment Variables​

Configuration Files

Contexts

User

Server

Configuration Commands

Get Contexts (`get-contexts`)

Show Current Context (`current-context`)

Switch Context (`use-context`)

Get Servers (`get-servers`)

Get Users (`get-users`)

Set Context (`set-context`)

Set Server (`set-server`)

Set User (`set-user`)

Delete User (`delete-user`)

Delete Server (`delete-server`)

Delete Context (`delete-context`)

View Config (`view`)

Use Environment Variables