Search…
⌃K

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.

veloctl

Shows the currently installed version of veloctl
veloctl [flags]
Options
-v, --version version for veloctl

veloctl auth

Manages veloctl authentication state

veloctl auth login

Log in to Velocity
veloctl auth login

veloctl auth logout

Log out and unlinks this device
veloctl auth logout

veloctl blueprint

Stores and manages persistent blueprints that are used when running veloctl env create -s <service name>

veloctl blueprint commit

Updates the persistent blueprint from a file containing the latest versions of your k8s resources. Resources will only be added or updated, not deleted.
veloctl blueprint commit -f <resource.yaml> --source <source_name> [flags]
Examples
# Commit a blueprint file to Velocity without specifying its source:
$ veloctl blueprint commit --file ./blueprint.yaml
# 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 https://github.com/viron/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 https://github.com/viron/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 https://github.com/viron/infra
Options
-f, --file string Reads the blueprint from the specified path.
-s, --source string The origin of this blueprint file. (default "default")

veloctl completion

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.

veloctl env

Creates, shows, and manages environments

veloctl env create

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 specified in a config file (The filename can be '-' for standard input):
$ veloctl env create --file config.yml
# Create an ad-hoc 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 --override
# 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 and override the creator's name:
$ veloctl env create --service worker --creator phil
# Create an environment that includes all available services:
$ veloctl env create --all
# Create an environment with values for the predefined blueprint parameters:
$ veloctl env create --param 'tenantId=3','dbLocation=west-2'
# 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
Options
--all Include all available services in the environment
--confirm Don't ask for confirmation
--creator string Specifies the creator of the environment
-d, --display display Display mode: 'full' or 'partial' (default) (default partial)
--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
--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 Snapshots to load into the environment
--template Outputs the k8s resources that will be applied to the cluster when creating the environment. Use this command to validate the correctness of your environment configuration.

veloctl env current

Defines the default working environment

veloctl env current get

Shows the default set environment to be used when developing
veloctl env current get
Examples
$ veloctl env current get

veloctl env current set

Sets the current working environment
veloctl env current set <environment-name>
Examples
$ veloctl env current set my-dev-env

veloctl env describe

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

veloctl env destroy

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)

veloctl env develop

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

veloctl env export

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

veloctl env list

Lists all active environments
veloctl env list [flags]
Options
-o, --output output Output format. 'json', 'yaml' or 'text' (default) (default text)

veloctl env list-groups

Lists all the service groups defined in your account
veloctl env list-groups

veloctl env list-parameters

Lists the parameters that can be set when creating the environment
veloctl env list-parameters

veloctl env list-services

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)

veloctl env list-snapshots

Lists all snapshots that were loaded into your environment
veloctl env list-snapshots

veloctl env logs

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

veloctl env plan

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

veloctl env portal

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

veloctl env portal connect

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

veloctl env portal disconnect

Disconnects the tunnels opened by env portal connect
veloctl 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

veloctl env sleep

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)

veloctl env status

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)

veloctl env sync

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
Options
--build-dir string
--build-script string Build script to be used for building new images
--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
-s, --service string Service to sync
--skip-first-build Skip build on start
--source string Build directory
-v, --verbose Verbose log output

veloctl env up

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

veloctl env up registry-login

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".

veloctl env up registry-logout

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

veloctl env update

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:
$ veloctl env update --file config.yml
# 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
-d, --display display Display mode: 'full' or 'partial' (default) (default partial)
-f, --file string Reads the environment configuration from a selected path. Use '-' for standard output
-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

veloctl env wakeup

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)

veloctl snapshot

Manages the database snapshots available for environment seeding

veloctl snapshot delete

Delete a snapshot
veloctl snapshot delete <snapshot-name> [flags]
Examples
# Delete a snapshot named 'my-snapshot'
$ veloctl snapshot delete my-snapshot
Options
--confirm Don't ask for confirmation

veloctl snapshot download

Download a snapshot
veloctl snapshot download <snapshot-name> [flags]
Examples
# Download a snapshot named 'my-snapshot' and save it to './dump.gz'
$ veloctl snapshot download --file ./dump.gz my-snapshot
Options
-f, --file string The download location of the snapshot

veloctl snapshot list

Lists all available snapshots
veloctl snapshot list
Examples
$ veloctl snapshot list

veloctl snapshot put

Creates or updates a snapshot
veloctl snapshot put [snapshot-name] [flags]
Examples
# Upload or update a snapshot named 'my-snapshot' with the file 'mysql-dump.sql'
$ veloctl snapshot put --target mysql-database --db db-name --file ./mysql-dump.sql my-snapshot
# Upload a new snapshot. The snapshot's name will be the UTC time of the upload in format "20060102150405"
# with "snapshot-" prefix (e.g. snapshot-20210707160809)
$ veloctl snapshot put --target mysql-database --db db-name --file ./mysql-dump.sql
# Upload a snapshot created by Mongodump ("mongodump --gzip --archive=dump.gz") named 'my-mongo-dump'
$ veloctl snapshot put --target mongodb-database --db db-name --file ./dump.gz my-mongo-dump
# Upload a seed file that will be associated with the default snapshot and target 'seeding-accounts'
# The 'seeding-accounts' job has to be annotated with the relevant velocity blue-print annotations
# please note that with a seeding job the --db flag must be omitted
$ veloctl snapshot put --target seeding-accounts --file ./dump.gz --default
# Upload a seed file that will be associated with a snapshot named snap1 and target 'seeding-accounts'
$ veloctl snapshot put --target seeding-accounts --file ./dump.gz --name snap1
Options
-d, --db string The name of the target database, FileFlag: The location of the snapshot.
-f, --file string The location of the snapshot file.
-t, --target string Target (service name or seeding job) to load the snapshot into.

veloctl status

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)

veloctl version

Shows the currently installed version of veloctl
veloctl version