Set up the CLI

This guide prepares varc for benchmarks, one-shot migrations, bounded scripts, and SQL. The CLI uses its own connections and credentials; it does not read saved connections from the Varc desktop app.

1. Get the CLI

Packaged archives, installers, signing, and package-manager distribution are not part of the current development milestone. For now, build the standalone binary from the Varc repository:

cargo build --release -p varc-cli
./target/release/varc version

Run the installed binary’s help for its exact command surface:

varc --help
varc benchmark --help
varc migrate --help
varc script --help
varc sql --help

2. Create the shared configuration

From the root of the project that will use Varc, create a CLI-wide starter file:

varc init

This creates varc.toml. The file is shared by the whole CLI: it can contain connections, CLI defaults, licensing settings, benchmarks, migrations, scripts, and SQL query files.

A minimal shared configuration with one connection looks like this:

schema_version = 1
default_connection = "local"

[cli]
format = "human"
non_interactive = false

[licensing]
token_env = "VARC_CLI_TOKEN"

[connections.local]
url_env = "REDIS_URL"

The schema is strict and versioned. Unknown fields and unsupported schema_version values are errors. See the complete varc.toml reference for standalone, Cluster, Sentinel, TLS, authentication, and timeout settings.

3. Understand configuration discovery

Varc uses the first configuration source that applies:

1. --config <PATH>;
2. the path in VARC_CONFIG; or
3. the nearest varc.toml, walking from the current directory to the Git repository root.

Outside a Git repository, automatic discovery checks only the current directory. Relative paths inside the file resolve from the directory containing varc.toml.

Inspect what Varc resolved without connecting:

varc config path
varc config validate
varc config show
varc doctor

config show redacts literal passwords and URL credentials. Redaction reduces accidental disclosure in Varc output; keep secrets in environment variables or a secret manager rather than committing them.

4. Supply a connection URL

Expose the endpoint through the environment variable named by the selected connection:

export REDIS_URL='redis://127.0.0.1:6379'

Varc accepts redis://, rediss://, valkey://, and valkeys://. Dragonfly normally uses a Redis URL scheme.

You can also run a diagnostic without a configuration file:

REDIS_URL='redis://127.0.0.1:6379' varc connection test
VALKEY_URL='valkey://127.0.0.1:6379' varc topology inspect

Connection URLs resolve from --url, --url-env, the selected connection’s url_env, exactly one populated REDIS_URL, VALKEY_URL, or DRAGONFLY_URL, then the connection’s literal url. Multiple populated automatic URL variables are rejected as ambiguous.

5. Test the live target

Prove connectivity and inspect the actual server before running either core workflow:

varc connection test
varc topology inspect

connection test checks the selected endpoint. topology inspect reports the detected engine and live topology instead of trusting the connection name or environment variable.

Select a different named connection globally when needed:

varc --connection staging connection test

VARC_CONNECTION provides the same selection for an environment or CI job.

6. Authenticate for execution

Configuration validation, diagnostics, benchmark artifact inspection, saved benchmark report rendering, and script validation do not require a CLI Token. Benchmark runs, migration planning or execution, and script execution require separate paid capabilities available through Pro or Team CLI Tokens.

Create a named CLI Token in the license dashboard, store it in a secret manager, and expose it through [licensing].token_env:

export VARC_CLI_TOKEN='varc_cli_...'
varc auth status

A CLI Token is different from a desktop App Key. Before paid execution, Varc exchanges it for a short-lived, purpose-specific grant; the raw token is not used while measuring a benchmark, copying migration data, or running a script.

7. Choose a core workflow

Your shared CLI setup is now complete.

Benchmark

Create, validate, and run deterministic local or distributed workloads:

varc benchmark init baseline
varc benchmark validate baseline
varc benchmark run baseline

Continue with the Benchmark guide.

Migration

Preflight and run a live copy, bundle export, or bundle import:

varc migrate plan tenant_copy
varc migrate run tenant_copy

Continue with the Migration guide.

Scripts

Validate JavaScript or TypeScript offline, then run it through the bounded QuickJS runtime:

varc script validate inspect
varc script run inspect

Continue with the Scripts guide.

SQL

Validate a Redis-aware statement locally, then execute it against the selected connection:

varc sql validate --statement "SELECT key FROM redis LIMIT 10"
varc sql run --statement "SELECT key FROM redis LIMIT 10"

Continue with the SQL guide.

Use the CLI in automation

Global flags apply consistently across all workflows:

varc --non-interactive --format json <command>

--non-interactive refuses prompts instead of hanging a CI job. --format json keeps stdout to one stable terminal result while progress remains on stderr. Commit the non-secret varc.toml, then supply connection URLs, the CLI Token, and any distributed run ID through the CI system’s secret or environment settings.