The veltro CLI

veltro installs and operates every Veltrosecurity product. It’s one CLI whichever products you run; --products decides what an install contains.

Publication status

Every release publishes veltro-cli to PyPI at the release’s version. veltro install then downloads that release from GitHub. The repositories and images are private for now, so the one-line install below needs a GitHub token; see While the repositories are private.

From a clone

git clone https://github.com/veltrosecurity/veltro && cd veltro
pip install ./cli
veltro install --products <products> --source . --public-url https://example.com

--products takes a comma-separated subset of vectorflow,sigmatic,warden. Leave it out to install all three. An empty value (--products '') installs the core alone.

veltro install asks for your first admin’s email, or takes --admin-email. Identity logs that admin’s one-time sign-in link on first start; see Your first sign-in.

VELTRO_CLI_SOURCE=./cli ./install.sh --products … does the same through the bootstrap script.

One-line install

Take the installer from a release tag and name the same release. A tag doesn’t move; main does.

curl -fsSL https://raw.githubusercontent.com/veltrosecurity/veltro/v<release>/install.sh \
  | VELTRO_RELEASE=<release> sh -s -- --public-url https://example.com \
      --admin-email you@example.com

Without VELTRO_RELEASE, the script installs the newest CLI on PyPI and the release it was published with. veltro install without --suite-version takes the newest release.

Read the script before you run it. It needs Python 3.10 or later, installs the CLI into ~/.veltro/venv, links veltro into ~/.local/bin, and runs veltro install, which writes the compose files, gateway configuration and version pins, generates secrets into .env, records your choices in veltro.toml, and starts the install.

While the repositories are private

GitHub answers 404 for a private repository’s files unless the request carries a token, and GHCR won’t hand out the images without a login. One classic token with repo and read:packages covers both. A fine-grained token with read-only Contents on veltrosecurity/veltro covers the downloads, but GHCR still needs a classic token. If you’re logged in with gh, gh auth refresh -s read:packages adds the scope and gh auth token prints the token.

export VELTRO_GITHUB_TOKEN="$(gh auth token)"
printf '%s' "$VELTRO_GITHUB_TOKEN" | docker login ghcr.io -u <github-user> --password-stdin
curl -fsSL -H "Authorization: Bearer $VELTRO_GITHUB_TOKEN" \
  https://raw.githubusercontent.com/veltrosecurity/veltro/v<release>/install.sh \
  | VELTRO_RELEASE=<release> sh -s -- --public-url https://example.com \
      --admin-email you@example.com

veltro install, veltro upgrade and veltro status read the token from VELTRO_GITHUB_TOKEN, then GITHUB_TOKEN, then GH_TOKEN. They send it only to the GitHub API, which serves the release manifest and archive, and never print it. Without a token they use the public download links, and a private release stops the install with HTTP 404 and the variable to set.

To read the script before running it, gh can fetch it too:

gh api -H "Accept: application/vnd.github.raw" \
  "repos/veltrosecurity/veltro/contents/install.sh?ref=v<release>" > install.sh

Commands

Command	What it does
install	Materialise an install, generate secrets and start it
up, down, restart	Start, stop (keeping data) or restart services
ps, logs, config	Service status, logs, and the resolved compose configuration
status	Service status plus HTTP health checks
doctor	Host and install checks, with the command that fixes each failure
agent enroll	Start a VectorFlow agent on this host
demo	List, seed or reset the demo sandbox datasets
backup, restore	Back up or restore the whole install
upgrade	Move to a newer release, taking a backup first
k8s render	Render the Helm chart for GitOps
support-bundle	Capture a support bundle with no secrets in it
init-env	Write .env from .env.example with generated secrets

Lifecycle commands take --products to act on a different selection for one run, and --dry-run to print what they would do.

Make targets

In a clone, the Make targets wrap the same code:

make init                # write .env with generated secrets
make up                  # start the products in VELTRO_PRODUCTS (all three if unset)
make up PRODUCTS=sigmatic    # override the selection for one command

To change the installed set for good, edit VELTRO_PRODUCTS in .env.