Configure vvctl

Applies toAll deployments

3 min read

On this page

Configuration Files
Contexts
- User
- Server
Configuration Commands
Use Environment Variables

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
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:

YAML

1###
2#  - name: name_of_the_user_entry
3#    user:
4#      token: API token (personal, namespace, or workspace)
5#      namespace: The name of the namespace. Required for Self-Managed.
6#      workspace: The name of the workspace. Required for Managed Service with a Workspace API token.
7#      email: The email address for the Managed Service account.
8#      password: The password for the Managed Service account.
9users: []
10###
11#  - name: name_of_the_server_entry
12#    server:
13#      host: The URL to the Ververica Unified Streaming Data Platform instance.
14
15servers: []
16###
17#  - name: name_of_the_context
18#    context:
19#      user: reference_to_existing_user
20#      server: reference_to_existing_server
21contexts: []
22
23current-context: null
24warning_permissions: true
25agent_version: 1.9.2-1
26agent_charts: oci://registry.ververica.cloud/agent-charts/vv-agent
27agent_name: vv-agent

where

Property	Description
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
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
Property	Description
host	The URL of the Ververica Unified Streaming Data Platform instance.

An example of a contexts configuration could be

YAML

1servers:
2  - name: vvp
3    server:
4      host: https://vvp.internal.ververica.cloud
5  - name: vvc
6    server:
7      host: https://app.ververica.cloud
8users:
9  - name: qa-team
10    user:
11      email: qa-team@ververica.com
12      password: qa-pass
13  - name: frontend-team-ws-dev
14    user:
15      email: frontend-team@ververica.com
16      token: token-vvc
17      workspace: es223ysdf2j34
18contexts:
19  - name: qa-vvp
20    context:
21      server: vvp
22      user: qa-team
23  - name: qa-vvc
24    context:
25      server: vvc
26      user: qa-team
27  - name: frontend-vvc-ws-dev
28    context:
29      server: vvc
30      user: frontend-team-ws-dev
31current-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:

BASH

1❯ cat ./ververica-config.yml
2servers:
3  - name: vvp
4    server:
5      host: https://vvp.internal.ververica.cloud
6users:
7  - name: dev-ns-default
8    user:
9      email: dev@ververica.com
10      token: token-vvc
11      namespace: default
12contexts:
13  - name: dev
14    context:
15      server: vvp
16      user: dev-ns-default
17current-context: dev
18
19❯ 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

BASH

1vvctl 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

BASH

1vvctl config get-contexts
2vvctl config get-contexts vvp-stage-ns-default-viewer
3vvctl config get-contexts --current
4vvctl config get-contexts --output=yaml

Show Current Context (`current-context`)

Prints the name of the active context.

Syntax

BASH

1vvctl config current-context

Examples

BASH

1vvctl config current-context
2# Output: vvc-stage

Switch Context (`use-context`)

Sets the current-context in the configuration file.

Syntax

BASH

1vvctl config use-context NAME

Parameters

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

Examples

BASH

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

Get Servers (`get-servers`)

Lists server entries from the configuration.

Syntax

BASH

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

Parameters

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

Examples

BASH

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

Get Users (`get-users`)

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

Syntax

BASH

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

Parameters

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

Examples

BASH

1vvctl config get-users
2vvctl 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

BASH

1vvctl 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

BASH

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

Set Server (`set-server`)

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

Syntax

BASH

1vvctl 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

BASH

1vvctl 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

BASH

1vvctl config set-user NAME \
2  [--token=TOKEN] \
3  [--namespace=NAMESPACE] \
4  [--workspace=WORKSPACE] \
5  [--email=EMAIL] \
6  [--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

BASH

1# Credentials-based user
2vvctl config set-user local-admin --email=admin@local --password=l0ca1
3 
4# Token user for VVP namespace
5vvctl config set-user stage-default-editor-token --token=ey... --namespace=default
6 
7# Token user for VVC workspace
8vvctl config set-user stage-ws-e2e-editor-token --token=ey... --workspace=e2e-test-connectors
9 
10# Token user for VVC workspace + namespace
11vvctl 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

BASH

1vvctl config delete-user NAME

Parameters

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

Examples

BASH

1vvctl 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

BASH

1vvctl config delete-server NAME

Parameters

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

Examples

BASH

1vvctl config delete-server localhost

Delete Context (`delete-context`)

Removes a context entry.

Syntax

BASH

1vvctl config delete-context NAME

Parameters

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

Examples

BASH

1vvctl 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

BASH

1vvctl 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

BASH

1vvctl config view
2vvctl config view --output=json
3vvctl config view --minify
4vvctl 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
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.

Was this helpful?

Yes No