Skip to content
varcDocs
Varc
Docs

Developer Tools

Varc CLI

Run deterministic benchmarks, reviewed migrations, scripts, and Redis-aware SQL from a terminal or CI job.

varc is Varc’s standalone terminal and CI client for Redis, Valkey, and Dragonfly. It runs without Electron, does not read desktop connection profiles, and keeps automation in a strict, versioned varc.toml file.

The current CLI has four operator workflows:

  • deterministic local or distributed benchmarks; and
  • reviewed, foreground one-shot migrations; and
  • bounded JavaScript or TypeScript scripts; and
  • Redis-aware SELECT, UPDATE, and EXPLAIN statements.

Start with the guided CLI setup, then use the dedicated Benchmark and Migration guides, or automate Redis with Scripts, or run SQL. The complete varc.toml reference documents every field.

Command map

varc init
varc version
varc doctor
varc auth status
varc config path|show|validate
varc connection test
varc topology inspect
varc benchmark init|validate|run|report
varc benchmark artifact inspect|validate
varc migrate plan|run
varc script validate|run
varc sql validate|run

Run varc --help or varc <command> --help for the exact flags supported by your installed build.

One configuration format

Connections, CLI defaults, licensing settings, benchmarks, migrations, scripts, and SQL queries live in one varc.toml:

schema_version = 1
default_connection = "ci"

[cli]
format = "human"

[licensing]
token_env = "VARC_CLI_TOKEN"

[connections.ci]
url_env = "REDIS_URL"

[benchmarks.baseline]
requests = 100000
clients_per_runner = 8

[benchmarks.baseline.workload]
type = "preset"
preset = "get_only"

[scripts.inspect]
path = "scripts/inspect.ts"
connection = "ci"
timeout = "5s"

[queries.inspect]
path = "queries/inspect.sql"
connection = "ci"

The schema rejects unknown fields and unsupported versions. URLs and CLI Tokens can stay in environment variables while the non-secret workload definition is committed with the project.

Inspect before running

Varc separates configuration, target, and live-server checks so failures are easier to diagnose:

varc config validate
varc doctor
varc connection test
varc topology inspect
varc benchmark validate baseline
varc script validate inspect
varc sql validate inspect

Configuration, benchmark validation, and script validation are free. Script validation transpiles source without connecting or reading mapped environment values. SQL validation prepares the statement without resolving a connection. connection test proves the selected endpoint is reachable. topology inspect reports the detected engine and live topology instead of trusting an environment variable’s name.

Deliberate execution

Benchmark execution requires a Pro or Team CLI Token with the load-test capability. One-shot migration planning and execution use a separate migration capability. Script execution uses its own purpose-bound scriptRun capability. Personal does not issue CLI Tokens; this does not change migration or scripting features available in the desktop app.

export VARC_CLI_TOKEN='varc_cli_...'
varc auth status
varc benchmark run baseline
varc script run inspect
varc sql run inspect

Before execution traffic reaches the server, Varc exchanges the token for a short-lived, purpose-specific grant. The raw token is not used during benchmark measurement, migration copying, or script execution.

Human and machine output

Human output is the default. --format json writes one stable terminal object to stdout while progress stays on stderr. Benchmarks can also write aggregate JSON, event JSONL, and JUnit XML files. Migrations support TTY, plain, JSONL, or disabled progress independently of their final result.

Stable exit codes make the CLI suitable for CI:

Code Meaning
0 Complete success and passing assertions
2 Usage or configuration error
3 Authentication, licensing, grant, or connection failure
4 Safety or command-policy refusal
5 Incomplete or indeterminate outcome
6 Benchmark assertion failure
7 Runtime failure
130 Joined interruption after cancellation

Continue