How to use vvctl

Interactive mode

When you run vvctl without any commands, you'll enter an interactive mode. This TUI (Text-based User Interface) lets you manage your workspaces and deployments visually.

• Navigation: Use the arrow keys or hjkl to move around.
• Selection: Press space or enter to select an item.
• Exit: Press q to quit the application.

The footer always shows the available shortcuts for your current view.

Command mode

You can run vvctl non-interactively by following it with a command and subcommand. The main commands are:

Usage:
  vvctl [COMMAND]

Commands:
  login           Log in Ververica Cloud
  logout          Log out of Ververica Cloud
  get             Display one or more resources
  create          Create a new resource
  delete          Delete a resource
  start           Start a resource
  stop            Stop a resource
  install         Install a resource
  uninstall       Uninstall a resource
  default-config  Print the default configuration
  interactive     Run interactive mode
  help            Print this message or the help of the given subcommand(s)

For more information about any command, use the --help flag.

❯ vvctl get --help
Display one or more resources

Usage: vvctl get <COMMAND>

Commands:
  workspaces    List all workspaces
  agent         List a single agent
  agents        List all agents from a workspace
  agent-values  Download the helm values file of an agent
  deployments   List all deployments from a workspace
  deployment    List a single deployment
  artifacts     List all artifacts from a workspace
  artifact      Download an artifact
  jobs          List all jobs from a deployment
  job           List a single job
  profile       Show logged user profile
  help          Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

❯ vvctl get workspaces --help
List all workspaces

Usage: vvctl get workspaces [OPTIONS]

Options:
  -i, --instance-id <INSTANCE_ID>
          The ID of the workspace to filter by
  -s, --status-category <STATUS_CATEGORY>
          The status category to filter by
      --with-runtime-info <WITH_RUNTIME_INFO>
          Whether to include runtime information in the response [possible values:
          true, false]
  -p, --permission <PERMISSION>
          The permission to filter by
  -o, --output <OUTPUT>
          Output format [default: table] [possible values: table, json, yaml, yml]
  -h, --help
          Print help

Output formats

Most get commands can format their output as json, yaml, or a table. Use the --output (or -o) option to specify a format. The default is table, which is a human-readable grid.

You can pipe json or yaml output to your preferred tools for filtering. For example, to get only the RUNNING deployments from a workspace:

vvctl get deployments --workspace migpc9aex9vi1v --o yaml | yq eval '.deployments[] | select(.latestJob.status == "RUNNING")'

Creating a deployment

You can create a deployment with the command vvctl create deployment. Currently only JAR and PYTHON deployments are supported.

note

Creating a deployment requires an artifact URI. If you need to create and upload an artifact, you can use the command vvctl create artifact, which will return the URI you need.

You can pass all parameters as command-line options:

$ vvctl create deployment jar \
  --name vvctl-jar-deployment \
  --jar-uri s3i://vvc-tenant-migpc9aex9vi1v-west-1/artifacts/namespaces/default/FlinkQuickStart-1.0-SNAPSHOT-6ba7d69116ac0be045dc7f413346815e.jar \
  --main-arguments "--input /flink/usrlib/Shakespeare.txt" \
  --entry-class org.example.WordCountStreaming \
  --additional-dependencies s3i://vvc-tenant-migpc9aex9vi1v-eu-west-1/artifacts/namespaces/default/Shakespeare.txt

As always, you can get more information with the option --help to see what other options you can use.

Alternatively, you can define the deployment in a YAML file. Given a file named for example jar-deployment.yml:

$ cat jar-deployment.yml
---
artifact:
  kind: JAR
  jarArtifact:
    additionalDependencies:
      - s3i://vvc-tenant-migpc9aex9vi1v-eu-west-1/artifacts/namespaces/default/Shakespeare.txt
    entryClass: org.example.WordCountStreaming
    jarUri: s3i://vvc-tenant-migpc9aex9vi1v-west-1/artifacts/namespaces/default/FlinkQuickStart-1.0-SNAPSHOT-6ba7d69116ac0be045dc7f413346815e.jar
    mainArgs: '--input /flink/usrlib/Shakespeare.txt'
name: vvctl-jar-deployment

You can create the deployment with the flag -f:

vvctl create deployment jar -f jar-deployment.yml

tip

The YAML schema for creating a deployment is the same as the output of vvctl get deployment <id> -o yaml. You can use this command to generate a template from an existing deployment.