CLI Reference

Install

npm install -g @veltrixsecops/cli
veltrix --version
veltrix --help

init / validate / package

veltrix init <app-id>

Scaffolds a new app with the canonical layout (pulled fresh from the community repo's _template/) and rewrites its identity to your app id. The app id must match /^[a-z0-9][a-z0-9-]*[a-z0-9]$/.

veltrix init crowdstrike-edr
# Options:
#   --dir <dir>   Parent directory to create the app in (default: ".")

cd crowdstrike-edr && npm install

veltrix validate [dir]

Validates an app directory against the platform contract — the same rules CI runs on PRs: manifest schema, handler completeness, no executables, size cap, and import boundaries.

veltrix validate ./crowdstrike-edr
# [dir] defaults to "." — run it from inside the app directory too

veltrix package [dir]

Validates, then builds a release-identical ZIP: stages the app, compiles server-side TypeScript to CommonJS (hosted platforms run compiled code), and prints the SHA-256. Useful for install-by-URL testing and verifying what CI will ship.

veltrix package ./crowdstrike-edr --out dist
# ✔ Packaged crowdstrike-edr v1.0.0
#   file:   dist/crowdstrike-edr.zip
#   size:   84.2 KB (37 files)
#   sha256: 9f2c…
# Options:
#   --out <dir>   Output directory (default: "dist")

login / whoami / logout

Authenticate with an API key created in Settings → Keys & Tokens. The key is verified against the platform and stored in ~/.veltrix/config.json (mode 600). VELTRIX_API_KEY / VELTRIX_URL environment variables override the stored profile — handy for CI.

veltrix login --url https://app.veltrixsecops.com
# Prompts for the API key (hidden input) unless --api-key or VELTRIX_API_KEY is set
# Options:
#   --url <url>         Platform URL (default: https://app.veltrixsecops.com)
#   --api-key <key>     API key (omit to be prompted)
#   --profile <name>    Named profile (default: "default")

veltrix whoami
# url:      https://app.veltrixsecops.com
# customer: cus_1a2b3c
# type:     api-key
# scopes:   sandbox:read, sandbox:write

veltrix logout          # removes the stored credentials for the profile

All authenticated commands accept --profile <name> to select a non-default login profile.

sandbox

Sandboxes let you run a work-in-progress app inside your own tenant on the hosted platform. You develop locally and sync changes in near-real time; the platform validates and hot-reloads them.

# create — one sandbox per app-under-development (name is unique per tenant)
veltrix sandbox create crowdstrike-dev --app crowdstrike-edr

# list — name, app, status, files, size, last sync, expiry
veltrix sandbox list

# delete — confirms first; pass --yes to skip (required in non-interactive shells)
veltrix sandbox delete crowdstrike-dev --yes

# run — one-shot invoke of a pipeline handler inside a synced sandbox
veltrix sandbox run crowdstrike-dev detections validate
#                    <name>         <config-type-id> <handler>
# handler ∈ validate | deploy | rollback | healthCheck | driftDetect | getStatus

Remote handler execution ships with the platform's sandbox runner. On tenants that predate it, sandbox run reports that runs are unavailable and you keep using veltrix dev to sync and validate.

dev — the dev loop

veltrix dev [dir] --sandbox <name> watches an app directory and live-syncs it into a sandbox. It is the day-to-day inner loop for app development.

veltrix dev ./crowdstrike-edr --sandbox crowdstrike-dev --create --run detections:validate
# Flags:
#   --sandbox <name>   Sandbox to sync into (required)
#   --create           Create the sandbox first if it doesn't exist
#   --run <spec>        Invoke <configTypeId>:<handler> after each successful sync
#   --logs             Stream live sandbox events over WebSocket when supported
#   --profile <name>   Use a non-default login profile

How a sync works

On startup the app is validated locally, the sandbox is resolved (--create makes it on the fly), and a full sync runs. Then the directory is watched, and every save runs one debounced cycle:

1. Local validate — the same contract checks CI runs. Failures print and the watcher waits for your next save; the loop never breaks.
2. Manifest diff (sha256) — the CLI hashes every file and POSTs the manifest; the server answers with exactly which files to upload and delete.
3. tar.gz delta upload — only changed files are packed and uploaded; deletes and renames propagate automatically.
4. Server validate + transpile — the platform re-validates the manifest, transpiles server-side TypeScript, and returns a summary the CLI prints.
5. Optional handler run — with --run, the named handler is invoked after each successful sync and its result plus captured logs are pretty-printed.

A typical session:

$ veltrix dev ./crowdstrike-edr --sandbox crowdstrike-dev --run detections:validate
veltrix dev
  app:     /home/dev/crowdstrike-edr
  sandbox: crowdstrike-dev @ https://app.veltrixsecops.com
Performing initial sync…
✔ ↑ 42 files in 910ms — server validation passed, 12 transpiled
✔ run detections:validate succeeded in 38ms
Watching for changes… (Ctrl+C to stop)
10:32:04 ✔ ↑ 1 file in 240ms — server validation passed, 12 transpiled
✔ run detections:validate succeeded in 41ms
10:33:17 ✔ ↑ 2 files, ✕ 1 deleted in 310ms — server validation passed

The loop is resilient: connection drops, state mismatches (409), and transient 5xxs trigger one automatic full resync (re-POSTing the full manifest is the resync). A deleted sandbox is recreated when --create was passed; an expired sandbox (410) ends the session.

.veltrixignore

node_modules/, .git/, dist/, and .veltrix* files are never synced. Add a .veltrixignore at the app root for anything else, using gitignore-style lines:

# scratch files
*.local.md
fixtures/**/*.bin
build/
!keep.this