VeloxSaarthi

Appearance

CLI Reference ​

vlx is a single self-contained binary (see Install). When developing from source, every command below also works as bun run src/cli.ts <command>.

vlx init ​

Guided interactive setup.

bash
vlx init

Prompts for the ADO org/project/repo, PAT, and Telegram details, then resolves the repository ID via the ADO API, clones the client repo (default ~/.vlx/repos/<repo>), writes ~/.vlx/vlx.yaml and ~/.vlx/secrets/global.env, and runs migrations. Refuses to run if ~/.vlx/vlx.yaml already exists — edit or delete it first.

vlx migrate ​

Apply pending SQLite database migrations.

bash
vlx migrate

Creates ~/.vlx/state.db (or $VLX_DB_PATH) if it does not exist, then applies all pending migrations in filename order. Idempotent — safe to re-run. The daemon also runs migrate automatically at startup, after snapshotting the database.

Migrations are embedded in the binary at build time (from src/db/migrations/*.sql, named NNNN_short_name.sql). Applied migrations are tracked in the vlx_migrations table by filename. When adding a migration from source, run bun run gen:migrations to refresh the embedded snapshot — a test fails if it drifts.

vlx daemon ​

Start the main daemon poll loop.

bash
vlx daemon [--no-update] [--debug]

This is the long-running process that:

  • Checks the release channel and self-updates before anything else (skip with --no-update or VLX_NO_UPDATE=1).
  • Polls ADO (or the configured tracker) for new stories.
  • Claims stories from the queue and runs them through the pipeline.
  • Handles Telegram commands and callbacks.
  • Runs the watchdog (every 30 s).
  • Polls open PR status every 60 s.
  • Auto-migrates the database at startup.
  • Takes a daily database backup at startup.

The daemon runs in the foreground; stop it with Ctrl+C. It logs to stdout (pretty-printed pino). Set LOG_LEVEL or log.level in vlx.yaml to control verbosity; --debug enables agent-session debug logging.

vlx update ​

Check the release channel and update the binary if a newer version is published.

bash
vlx update

Downloads the platform binary listed in latest.json, verifies its SHA-256, swaps the executable on disk, and restarts into the new version. Prints an explicit failure reason (and exits non-zero) if the check or apply fails — it never pretends to be up to date. From a source checkout this is a no-op.

vlx status ​

Show active runs and queue depth.

bash
vlx status

Prints a human-readable table of:

  • Currently active runs (story ID, stage, status, time since last event).
  • Queue depth (pending / claimed / failed items).

vlx memory report ​

Generate a memory hygiene report.

bash
vlx memory report

Scans the project memory directory (<repo>/.vlx/memory/) and reports:

  • Stale entries (files not updated in > 90 days).
  • Large files (> 10 KB, suggesting accumulated cruft).
  • Potential duplicates (entries with high content overlap).

Output is printed to stdout. No files are modified.

vlx db check ​

Run a SQLite integrity check on state.db.

bash
vlx db check

Runs PRAGMA integrity_check on the database. Prints the results. Exit code 0 = clean; exit code 1 = integrity errors found. Use this to diagnose a corrupt database before attempting a restore.

vlx db backup ​

Take a VACUUM INTO snapshot of the database and prune old backups.

bash
vlx db backup

Creates a timestamped backup in the backups/ directory adjacent to state.db. Prunes old backups (retains the last 14 daily snapshots and the last 12 monthly snapshots).

The daemon runs this automatically at startup. Run it manually to take an on-demand snapshot before a risky operation.

vlx db archive ​

Archive old runs' event logs to cold storage.

bash
vlx db archive

Moves event rows for runs that are in a terminal state (shipped, failed, abandoned, needs_review) and older than the configured archive threshold (default: 90 days) from the events table to an archive file. This keeps the hot events table lean without losing audit history.

vlx db restore <file> --yes ​

Restore state.db from a backup file.

bash
vlx db restore backups/state-2026-06-10T12:00:00.db --yes

Destructive — requires --yes to confirm. Stops the daemon if running (or warns if it cannot stop it), replaces state.db with the specified backup file, then exits. Restart the daemon manually after a restore.

WARNING

There is no automatic rollback. Inspect backups/ to find the correct snapshot, run vlx db check on the backup before restoring, and stop the daemon first.

vlx --version / -v ​

Print the VeloxSaarthi version.

bash
vlx --version
vlx -v

vlx --help / -h ​

Print usage information.

bash
vlx --help
vlx -h

Global flags ​

FlagDescription
--version, -vPrint version and exit.
--help, -hPrint help and exit.

Environment variables affecting all subcommands ​

VariableDescription
VLX_HOMEOperational root. Defaults to ~/.vlx.
VLX_CONFIGPath to vlx.yaml. Defaults to ~/.vlx/vlx.yaml.
VLX_DB_PATHPath to state.db. Defaults to ~/.vlx/state.db.
VLX_UPDATE_URLOverride the self-update release-channel base URL.
VLX_NO_UPDATE1 skips the daemon's on-start update check.
LOG_LEVELLogging verbosity. Overrides log.level in config.

Secrets in ~/.vlx/secrets/global.env are auto-loaded at startup; variables already present in the environment always take precedence.

Internal Veloxcore tool — not a public product.