CLI Reference
Below is a list of Velocity CLI commands and usage information. You can also see this text in your terminal using
veloctl --help or veloctl -h.Shows the currently installed version of veloctl
veloctl [flags]
Options
-v, --version version for veloctl
Manages veloctl authentication state
Log in to Velocity
veloctl auth login [flags]
Examples
# Login and authenticate to Velocity:
$ veloctl auth login
​
# Login and authenticate to Velocity, use kubernetes context named minikube (use the name as it appears in the kubeconfig file):
$ veloctl auth login --k8s-context minikube
Options
-k, --k8s-context string context name of the cluster where a Velocity operator is installed
Log out and unlinks this device
veloctl auth logout
Stores and manages persistent blueprints that are used when running
veloctl env create -s <service name>Updates the persistent blueprint source from a file containing the latest versions of your k8s resources, replacing former resources
veloctl blueprint commit -f <resource.yaml> --source <source_name> [flags]
Examples
# Commit a k8s blueprint to Velocity from the 'backend' repo:
# The blueprint consists of the k8s resources required to deploy the backend service augmented with Velocity annotations.
# It will be merged with blueprints committed from other sources
$ veloctl blueprint commit --file ./blueprint.yaml --source backend
​
# Commit a k8s blueprint to Velocity for the backend service, by generating it from a Helm chart and Helm values stored in the 'backend' repo:
# The blueprint will be merged with blueprints committed from other sources.
$ helm template -f values.yaml -f velocity_values.yaml --set image.tag=$GITHUB_SHA backend chart/ |
veloctl blueprint commit -f - --source backend
​
# Generate a blueprint from a directory of k8s yaml files from the 'infra' repository and commit it to Velocity as a single blueprint:
$ for i in $(ls velocity/*.yaml); do echo "---"; cat $i; done | tail -n +2 | veloctl blueprint commit -f - --source infra
​
Options
--confirm Don't ask for confirmation (default is false)
-f, --file string Reads the blueprint source from the specified path.
--source string The origin of this blueprint file.
Downloads the blueprint YAML stored in Velocity
veloctl blueprint get [-f <blueprint.yaml> --source <source_name>] [flags]
Examples
# Print the entire blueprint:
$ veloctl blueprint get
$ veloctl blueprint get -f -
​
# Download the entire blueprint to a file:
$ veloctl blueprint get -f full-blueprint.yaml
​
# Download a partial blueprint from a specified source:
# veloctl blueprint get --source infra
​
Options
-f, --file string Saves the blueprint to the specified path. Use '-' for standard output (default "-")
--source string The source name to filter the blueprint by
Lists all available blueprint sources
veloctl blueprint list-sources [flags]
Options
-o, --output output Output format. 'json', 'yaml' or 'text' (default) (default text)
Removes the given source from the blueprint
veloctl blueprint remove-source <source_name>
Setups shell completions
veloctl completion <bash|zsh|fish|powershell>
Examples
Bash:
​
$ source <(veloctl completion bash)
​
# To load completions for each session, execute once:
# Linux:
$ veloctl completion bash > /etc/bash_completion.d/veloctl
# macOS:
$ veloctl completion bash > /usr/local/etc/bash_completion.d/veloctl
​
Zsh:
​
# If shell completion is not already enabled in your environment,
# you will need to enable it. You can execute the following once:
​
$ echo "autoload -U compinit; compinit" >> ~/.zshrc
​
# To load completions for each session, execute once:
$ veloctl completion zsh > "${fpath[1]}/_veloctl"
​
# You will need to start a new shell for this setup to take effect.
​
fish:
​
$ veloctl completion fish | source
​
# To load completions for each session, execute once:
$ veloctl completion fish > ~/.config/fish/completions/veloctl.fish
​
PowerShell:
​
PS> veloctl completion powershell | Out-String | Invoke-Expression
​
# To load completions for every new session, run:
PS> veloctl completion powershell > veloctl.ps1
# and source this file from your PowerShell profile.
​
Creates, shows, and manages environments
Creates a new environment
veloctl env create [environment-name] [flags]
Examples
# Create an environment for developing a specific service:
$ veloctl env create --service worker
​
# Create an environment for developing a specific service in a specific version:
$ veloctl env create --service worker:latest
​
# Create an environment for developing more than one service:
$ veloctl env create --service worker --service backend
​
# Create an environment with a specific name for developing a service:
$ veloctl env create --service website johns-feature
​
# Create an environment that includes all available services:
$ veloctl env create --all
​
# Create an environment specified in a config file (The filename can be '-' for standard input).
# The file will be attributed to the 'default' source:
$ veloctl env create --file config.yml
​
# Create an environment specified in a config file (The filename can be '-' for standard input).
# The file will be attributed to source 'my-source':
$ veloctl env create --file config.yml --source my-source
​
# Create an environment specified in a config file (The filename can be '-' for standard input).
# Override the entire blueprint definition with the specified file definitions:
$ veloctl env create --file config.yml --source my-source --override
​
# Validate a K8s YAML which includes k8s resources with Velocity Annotations:
$ veloctl env create --file config.yml --dry-run
​
# Create a K8s YAML from a Helm Chart and Helm Values file that include Velocity Annotations:
$ helm template chart/ -f values.yaml -f velocity_values.yaml | veloctl env create -f - --dry-run
​
# Create an environment loaded with a database snapshot:
# (Use 'veloctl snapshot put' to create database snapshots)
$ veloctl env create --service worker --snapshot snapshot-name
​
# Create an environment with values for the predefined blueprint parameters:
$ veloctl env create --param 'tenantId=3','dbLocation=west-2'
​
Options
--all Include all available services in the environment (default is false)
--confirm Don't ask for confirmation (default is false)
--creator string Specifies the creator of the environment
-d, --display display Display mode: 'full' or 'partial' (default) (default full)
--dry-run Validates a k8s blueprint file by providing a detailed plan, with error messages and hints
-f, --file string Reads the environment config from the specified path. Use '-' for standard input
-g, --group strings Specifies a group of services that will be included in the environment
--override Override the entire blueprint definition with the specified environment file (default is false)
--param strings Specifies values for the predefined blueprint parameters
-s, --service strings Specifies the services that will be included in the environment.
(Optional) To specify a particular version, use the following format: <service>:<version>
--snapshot strings Data snapshots to load into the environment
--source string Specifies the blueprint source that the given file resources will be attributed to.
Can only be used with the file flag (default is an empty string)
--template Outputs the k8s resources that will be applied to the cluster when creating or updating the environment. Use this command to validate the correctness of your environment configuration
Defines the default working environment
Shows the default set environment to be used when developing
veloctl env current get
Examples
$ veloctl env current get
​
Sets the current working environment
veloctl env current set <environment-name>
Examples
$ veloctl env current set my-dev-env
Describes services of the current environment
veloctl env describe [environment-name] [flags]
Examples
# Show services description for the current environment:
$ veloctl env describe
​
# Show a description for a specific service for the current environment:
$ veloctl env describe --service my-service
​
# Show a description for a specific service for the current environment and save it to a file:
$ veloctl env describe --service my-service --file output.yml
​
Options
-f, --file string Saves the description of this environment to the specified file. Use '-' for standard output (default "-")
-s, --service string Shows only the parameters of the specified service
Destroys an environment
Synopsis
Destroys an environment. This will remove all related cloud resources, and the environment will no longer be active
veloctl env destroy [environment-name] [flags]
Examples
# Destroy the current working environment
$ veloctl env destroy
​
# Destroy an environment by name (e.g. 'johns-feature'):
$ veloctl env destroy johns-feature
​
Options
--confirm Don't ask for confirmation
--ttl duration Sets the time in which the environment will be destroyed (for example 2s, 2m, 3h, etc) (default -1ns)
Develops a service on your local machine and connects it to a remote environment
veloctl env develop <cmd> [flags]
Examples
# Develop a service in the current working environment by starting it locally:
$ veloctl env develop --service my-service -- go run ./main
​
# Develop a service in a specific environment by starting it locally:
$ veloctl env develop --env my-env --service my-service -- go run ./main
​
# Develop a service in the current working environment, and debug it by running the delve debugger
$ veloctl env develop --env my-env --service my-service -- dlv debug --headless=true --api-version=2 --listen=:2345
​
# Develop a service in the current working environment by attaching it to a running 'veloctl env portal'
$ veloctl env develop --attach --service my-service --env-file .env
​
Options
--attach Creates an active tunnel between your local service and the remote environment (Requires a running 'veloctl env portal'
--confirm Don't ask for confirmation (default is false)
--detach Removes active tunnels from your local service to the remote environment (Requires a running 'veloctl env portal')
--dry-run Displays information about how the veloctl would execute the command without executing it
-e, --env string Environment name
--env-file string Writes the environment variables to the specified file. The default is '-' for standard output
-f, --file string Applies command configuration specified in a Velocity YAML file
--no-shell Don't use sh -c when running the command
-q, --quiet No output messages, except for output from the running command
--randomize-used-ports Randomizes used ports of dependent remote services (for locally developed service)
-s, --service string Specifies services to develop
-v, --verbose Verbose log output
Execute a command in a container
veloctl env exec [environment-name] [flags]
Examples
# Execute './test.sh' script in one of the service's container in the first running pod:
$ veloctl env exec -s my-service -- ./test.sh
​
# Execute './test.sh' script in one of the service's container in all running pods:
$ veloctl env exec -s my-service --all-pods -- ./test.sh
​
# Execute './test.sh' script in a 'my-app' container:
$ veloctl env exec -s my-service --container my-app -- ./test.sh
​
# Pass stdin to the container:
$ veloctl env exec -s my-service -i -- /bin/sh <<< "This is coming from the stdin"
​
# Pass the terminal as stdin:
$ veloctl env exec -s my-service -t -- /bin/sh
​
Options
--all-pods Execute in all pods
--container string Specifies the container name. (If empty, the default container is used)
-e, --env string Environment name
-f, --file string Applies command configuration specified in a Velocity YAML file
--pod string Specifies the pod name. (If empty, the first running pod is used)
-q, --quiet Only print output from the remote session
-s, --service string Specifies the service for exec
-i, --stdin Pass stdin as an input
-t, --tty Pass the terminal as stdin
-v, --verbose Verbose log output
Execute a predefined script in a container
veloctl env exec-script <script-name> [flags]
Examples
# Execute 'my-test' script that's defined in '.velocity.yml' file' in the first running pod:
$ veloctl env exec-script my-tes -s my-service
​
# Execute 'my-test' script that's defined in '.velocity.yml' file' in a specific pod:
$ veloctl env exec-script my-test -s my-service --pod my-pod
​
# Execute 'my-test' script that's defined in '.velocity.yml' file with the arguments ["-f", "test1"]:
$ veloctl env exec-script my-test -s my-service --arg=-f,test1"
​
Options
--all-pods Execute in all pods
--arg strings Specifies the arguments to be provided from the configured script command
--container string Specifies the container name. (If empty, the default container is used)
-e, --env string Environment name
-f, --file string Applies command configuration specified in a Velocity YAML file
--pod string Specifies the pod name. (If empty, the first running pod is used)
-q, --quiet Only print output from the remote session
-s, --service string Specifies the service for exec
-v, --verbose Verbose log output
Exports an environment to a file
veloctl env export [environment-name] [flags]
Examples
# Export an environment to a file:
$ veloctl env export johns-feature --file johns-feature.yml
​
Options
-f, --file string Exports the environment to the desired file path. Use '-' for standard output
Lists all active environments
veloctl env list [flags]
Options
-o, --output output Output format. 'json', 'yaml' or 'text' (default) (default text)
Lists all the service groups defined in your account
veloctl env list-groups
Lists the parameters that can be set when creating the environment
veloctl env list-parameters
Lists all services that you can include in your environments
veloctl env list-services [flags]
Options
-o, --output output Output format. 'json', 'yaml' or 'text' (default) (default text)
Lists all snapshots that were loaded into your environment
veloctl env list-snapshots
Displays logs for services in the environment
veloctl env logs [environment-name] [flags]
Examples
# Display logs for all the services in the current working environment:
$ veloctl env logs
​
# Display logs for all the services in a specific environment:
$ veloctl env logs my-env
​
# Display logs for a specific service in a specific environment:
$ veloctl env logs --service my-service my-env
​
# Display logs for more than one service in a the current working environment:
# the current working environment
$ veloctl env logs --service my-service --service my-worker
​
# Display logs for a specific service since a set duration
$ veloctl env logs --service my-service --since 24h
​
Options
-n, --lines int The number of lines from the end of the logs to show. Default is -1, showing all logs (default -1)
--no-color Disables color in the output
-o, --output string Specifies output format: [default, raw, json] (default "default")
-s, --service strings Select logs by the specified services (By default, display logs for all the services)
--since duration Returns the logs captured in the provided time frame (for example 2s, 2m, 3h, etc) (default 2h0m0s)
-t, --timestamps Prints a timestamp to every log record
Generates a plan for an environment without creating it
veloctl env plan [flags]
Examples
# Generate a plan for an environment:
$ veloctl env plan --service my-service --file plan.yaml
​
Options
-d, --display display Display mode: 'full' or 'partial' (default) (default partial)
-f, --file string The target filename. Use '-' for standard output
--param strings Specifies values for the predefined blueprint parameters
-s, --service strings Services to include in the planned environment. (Optional) to use a specific version, use '<service>:<version>'
Opens a portal that manages connections to the remote environment
veloctl env portal [flags]
Examples
# Open a portal for the current working environment:
$ veloctl env portal
​
# Open a portal for a specific environment:
$ veloctl env portal --env my-env
​
Options
-e, --env string environment name
-v, --verbose verbose log output
Opens a tunnel to a remote service
veloctl env portal connect [flags]
Examples
# Open a tunnel to a remote service for the current working environment:
$ veloctl env portal connect --service backend
​
Options
-e, --env string environment name
--randomize-used-ports use a random port if the defined port is already in use
-s, --service string service name
-v, --verbose verbose log output
Disconnects the tunnels opened by
env portal connectveloctl env portal disconnect [flags]
Examples
# Disconnect the tunnel to a remote service for the current working environment:
$ veloctl env portal disconnect --service backend
​
Options
-e, --env string environment name
-s, --service string service name
-v, --verbose verbose log output
Shuts down an environment
Synopsis
Shuts down an environment and preserves its data for later use
veloctl env sleep [environment-name] [flags]
Examples
# Shuts down the current working environment
$ veloctl env sleep
​
# Shuts down an environment named 'johns-feature'
$ veloctl env sleep johns-feature
​
Options
--ttl duration Sets the time in which the environment will be put to sleep (for example 2s, 2m, 3h, etc) (default -1ns)
Shows the status of an existing environment
veloctl env status [environment-name] [flags]
Examples
# Get status for the current working environment:
$ veloctl env status
​
# Watch the status of an environment until it is ready:
$ veloctl env status env-name
​
# Show environment status and quit:
$ veloctl env status --no-watch env-name
​
Options
-d, --display display Display mode: 'full' or 'partial' (default) (default partial)
--no-watch Disable watching the status. show the current status and quit
-o, --output output Output format. 'json', 'yaml' or 'text' (default) (default text)
Automatically synchronizes a remote service based on changes to local files
veloctl env sync [flags]
Examples
# Sync service source code from a local folder
$ veloctl env sync --service worker
​
# Sync service source code from a folder while ignoring a file path that matches '*/my_directory/*'
$ veloctl env sync --service worker --exclude-pattern ".*/my_directory/.*"
​
# Sync service source code from folder path '/my/source-code/path'
$ veloctl env sync --service worker --source /my/source-code/path
​
# Sync service and use 'path/to/Dockerfile/' for building the image
$ veloctl env sync --service worker --dockerfile /path/to/Dockerfile
​
# Sync a service only once, without watching for changes
$ veloctl env sync --service worker --no-watch
​
# Sync service and use a customized build script for building a new image. Build tag is exported as an environment variable.
$ veloctl env sync --service worker --build-script
​
# Sync with live update by copying changes under './local/path' to '/remote/path' in the running containers.
$ veloctl env sync --service worker --live-update ./local/path:/remote/path
​
# Sync with live update and skip building a new image on start.
$ veloctl env sync --service worker --live-update ./local/path:/remote/path --skip-first-build
​
# Sync a service using a custom configuration file
$ veloctl env sync --service worker -f /path/to/velocity.yaml
​
# Sync a service using a custom configuration file and enable remote debugging
$ veloctl env sync --service worker --remote-debug -f /path/to/velocity.yaml
​
Options
--build-dir string
--build-tag-var string The exported variable to the build script containing the expected docker build tag (default "EXPECTED_REF")
--dockerfile string Dockerfile name to use for building the service (default "Dockerfile")
-e, --env string The name of the environment
-p, --exclude-pattern strings Regex for files paths to be ignored on change
-f, --file string Applies command configuration specified in a Velocity YAML file
-l, --live-update strings Run live updates
--no-watch Sync only once without watching changes
--remote-debug Enable remote debugging using the configuration specified in a Velocity YAML file
--restore-when-done Automatically restore the service to the initial state when the sync process is finished
-s, --service string Service to sync
--skip-first-build Skip build on start
--source string Source code directory
--update-image Build and use a new docker image
-v, --verbose Verbose log output
Creates a hybrid Docker Compose environment with offloaded services
veloctl env up [environment-name] [flags]
Examples
# Create a hybrid environment from a docker-compose file by offloading services to a remote cluster
$ veloctl env up --offload postgres --file compose-file.yaml
​
# Create a hybrid environment from a docker-compose file that is located in the specified working directory
$ veloctl env up --offload postgres -f compose-file.yaml --working-directory /path/to/work/dir
​
Options
--creator string Specifies the creator of the environment
-f, --file strings Specifies the path to your docker-compose file
--local strings Defines the list of services that will run locally. The rest of the services will run remotely
--offload strings Defines the list of services that will run remotely
--pre-run strings Defines a pre-run command that will run before the specified service. Format: '<target_service>|<command>'
-v, --verbose Verbose log output
-w, --working-directory string Sets the working directory which contains the docker-compose file
Creates a config file with registry credentials (to be used by the 'env up' command)
veloctl env up registry-login
Examples
# Create a config file with a registry credentials (you will be prompted for url, username and password)
$ veloctl env up registry-login
# The config file will be saved to .$HOME/config/velocity
​
# If you are using an AWS repository (ECR) you can use the following command to retrieve the password:
$ aws ecr get-login-password
# Then you can use the password with the username "AWS".
​
# If you are using GCP repository (GCR) you can use the following steps to retrieve the password:
# 1. Create a service account file:
$ gcloud iam service-accounts keys create keyfile.json --iam-account <Service Account Email>
# 2. encode the config file:
$ echo "$(cat keyfile.json)" | base64
Then you can use the encoded string as password with the username "_json_key".
​
Deletes the registry credentials file that was created by the 'env up registry-login' command
veloctl env up registry-logout
Examples
# Delete the registry credentials file
$ veloctl env up registry-logout
​
Updates services in an existing environment
veloctl env update [environment-name] [flags]
Examples
# Update the current environment for developing existing services:
$ veloctl env update
​
# Update an environment for developing a specific service:
$ veloctl env update --service worker
​
# Update an environment for developing a specific service in a specific version:
$ veloctl env update --service worker:latest
​
# Update an environment for developing more than one service:
$ veloctl env update --service worker --service backend
​
# Update an environment with a specific name for developing a specific service:
$ veloctl env update --service website johns-feature
​
# Update an environment specified in a config file.
# The file will be attributed to the 'default' source:
$ veloctl env update --file config.yml
​
# Update an environment specified in a config file.
# The file will be attributed to source 'my-source':
$ veloctl env update --file config.yml --source my-source
​
# Update an environment by loading a database snapshot:
$ veloctl env update --snapshot snapshot-name
​
# Update an environment by removing an existing service from the environment:
# (multiple services can be removed, as long as they are not depending on one another)
$ veloctl env update --service worker --remove
​
# Update an environment with values for the predefined blueprint parameters:
$ veloctl env update --param 'tenantId=3','dbLocation=west-2'
​
Options
--confirm Don't ask for confirmation (default is false)
-d, --display display Display mode: 'full' or 'partial' (default) (default partial)
-f, --file string Reads the environment config from the specified path. Use '-' for standard input
-g, --group strings Specifies a group of services that will be included in the environment
--param strings Specifies values for the predefined blueprint parameters
--remove Remove the specified service from the environment
-s, --service strings Services to update. To use a specific version, use '<service>:<version>'
--snapshot strings Data snapshots to load into the environment
--source string Specifies the blueprint source that the given file resources will be attributed to.
Can only be used with the file flag (default is an empty string)
Restores a sleeping environment into a running state
veloctl env wakeup [environment-name] [flags]
Examples
# Restores the current sleeping environment into a running state.
$ veloctl env wakeup
​
# Restores a sleeping environment named 'johns-feature' into a running state.
$ veloctl env wakeup johns-feature
​
Options
-d, --display display Display mode: 'full' or 'partial' (default) (default partial)
Configuring velocity-operator
Start a setup wizard to enable Cloud-Resources on an installed operator
Synopsis
Enables Cloud-Resources on an installed operator. this command will start a setup wizard to enable Cloud-Resources on your installed operator. it will use AWS CLI and Helm commands to add some required CRDs and policy permissions to the operator.
veloctl operator enable-cloud-resources
Install or upgrade the velocity operator
Synopsis
Install the velocity operator. If the operator is already installed, it will be upgraded to the latest version
veloctl operator install
Manages the database snapshots available for environment seeding
Delete a snapshot
veloctl snapshot delete [flags]
Examples
# Delete a snapshot named 'my-snapshot' with target 'my-target'
$ veloctl snapshot delete --name my-snapshot --target my-target
​
Options
--confirm Don't ask for confirmation
-n, --name string Name of snapshot to delete
-t, --target string Target of snapshot to delete
Gets (downloads) a snapshot
veloctl snapshot get [flags]
Examples
# Get a snapshot named 'my-snapshot' with target 'my-seeding-job' and save it to './my-seeding-job-snapshot.gz'
$ veloctl snapshot get --file ./my-seeding-job-snapshot.gz --name my-snapshot --target my-seeding-job
​
Options
-f, --file string The download location of the snapshot
-n, --name string The name of the snapshot to get
-t, --target string The target of the snapshot to get
Lists all available snapshots
veloctl snapshot list
Examples
$ veloctl snapshot list
Creates or updates a snapshot
veloctl snapshot put [flags]
Examples
# Upload a seed file that will be associated with the default snapshot and with target 'seeding-accounts'
# The 'seeding-accounts' job has to be annotated with the relevant velocity blueprint annotations
$ veloctl snapshot put --target seeding-accounts --default --file dump.gz
​
# Upload a seed file that will be associated with a snapshot named snap1 and with target 'seeding-accounts'
$ veloctl snapshot put --target seeding-accounts --name snap1 --file dump.gz
​
# Upload a seed file from URL instead of a local file
$ veloctl snapshot put --target seeding-accounts --name snap1 --file https://example-files.online-convert.com/document/txt/example.txt
​
Options
--default The default snapshot that will be used when creating environments without specifying a snapshot.
-f, --file string The location of the snapshot file.
-n, --name string The name of the snapshot the seed file will be associated with. (Only required for non-default snapshots)
-t, --target string Target (service name or seeding job) to load the snapshot into.
Shows the status of your connectivity, environment, and active sessions
veloctl status [flags]
Options
-o, --output output Output format. 'json', 'yaml' or 'text' (default) (default text)
Shows the currently installed version of veloctl
veloctl version
Last modified 11d ago