Developer Tools

Scripts

# Scripts

Validate and run bounded JavaScript or TypeScript automation against Redis, Valkey, and Dragonfly from the Varc CLI.

Varc CLI scripts run JavaScript or TypeScript inside the same bounded QuickJS
runtime used by the desktop app. Use them for finite, repeatable automation—not
server-side Redis Lua and not an interactive REPL.

Validation is local and free. Running a script requires a Pro or Team CLI Token
with the purpose-specific `scriptRun` capability.

## Create a named script

Keep source in a normal project file and register it in `varc.toml`:

```toml
[scripts.inspect]
path = "scripts/inspect.ts"
connection = "local"
database = 0
language = "typescript"
timeout = "5s"
fetch = false

[scripts.inspect.environment]
TENANT = "CI_TENANT"
```

```ts
const key = `tenant:${env.TENANT}:health`;
const value = await redis.get(key);

console.log("inspected", key);
return { key, value };
```

Paths are relative to the `varc.toml` file. `language` may be `javascript` or
`typescript`; when omitted, Varc infers it from `.js`, `.mjs`, `.cjs`, `.ts`,
`.mts`, or `.cts`.

## Validate without connecting

```bash
varc script validate inspect
```

Validation reads and bounds the source, resolves its language and timeout,
checks environment mapping names, and transpiles it. It does not:

- require a connection or CLI Token;
- read mapped process-environment values;
- contact Redis or the licensing service; or
- grant network or desktop capabilities.

The source limit is 1 MiB. The timeout defaults to `5s` and must be between
`1ms` and `30s`.

## Run against Redis

```bash
export REDIS_URL='redis://127.0.0.1:6379'
export VARC_CLI_TOKEN='varc_cli_...'
export CI_TENANT='acme'

varc script run inspect
```

Before connecting, Varc obtains a short-lived signed grant bound to the script
source, language, logical database, timeout, fetch decision, and environment
mapping. Environment values stay local and are never included in the grant
request.

The script result is written to stdout. Captured `console` messages are written
to stderr in human mode and included structurally in JSON mode:

```bash
varc --non-interactive --format json script run inspect
```

Ctrl-C or SIGTERM cancels the run. A timeout, memory limit, stack limit,
operation quota, oversized reply, or cancellation stops the sandbox with a
stable non-zero exit code.

## Run a file or stdin directly

A named definition is optional:

```bash
varc script validate --file scripts/inspect.js
varc script run --file scripts/inspect.js --timeout 10s
```

Stdin requires an explicit language because there is no file extension:

```bash
printf 'return await redis.get("health")' |
  varc script run --stdin --language javascript
```

Use global `--connection`, `--url`, or `--url-env` to select the target for a
direct source. `--database` overrides the selected logical database.

## Map environment values explicitly

Scripts receive a frozen `env` object containing only configured mappings. The
left side is the name visible to the script; the right side is the process
environment variable Varc reads at execution time:

```toml
[scripts.rotate.environment]
TENANT = "PRODUCTION_TENANT"
NEW_VALUE = "ROTATION_VALUE"
```

Add or override mappings for one invocation with repeatable flags:

```bash
varc script run rotate \
  --env TENANT=CI_TENANT \
  --env NEW_VALUE=CI_ROTATION_VALUE
```

Both names must use uppercase ASCII letters, digits, and underscores, begin
with an uppercase letter, and contain at most 64 characters. Missing source
variables fail before licensing or Redis traffic. Varc does not scrub a value
that the script deliberately prints or returns, so treat script output as
sensitive when mapped values contain secrets.

## Control network access

`fetch()` is denied by default. Grant HTTP or HTTPS access in the named
definition or for one invocation:

```toml
[scripts.status]
path = "scripts/status.js"
fetch = true
```

```bash
varc script run status --allow-fetch
varc script run status --deny-fetch
```

The grant is intentionally broad HTTP/HTTPS access rather than a URL allowlist.
Requests still have bounded URL, header, body, redirect, response-size, and
deadline limits. Varc-generated fetch errors use a closed reason vocabulary
and do not echo authored URLs, which may contain credentials.

## Understand the Redis safety boundary

Scripts can perform ordinary Redis reads and writes through `redis.*` helpers
or `redis.call()`. The locked-down command policy denies authentication,
administrative and topology changes, blocking commands, Pub/Sub subscription
state, connection-state changes, and server-side `EVAL`, `SCRIPT`, and
`FUNCTION` execution.

This policy is a hard sandbox boundary, not a dry-run mode. A permitted write
such as `SET`, `HSET`, or `DEL` reaches the selected server immediately. Review
scripts and target selection before running them against valuable data.

Desktop-only capabilities are unavailable in the CLI: scripts cannot use Varc
storage, the OS keyring, dialogs, clipboard, or notifications. The initial CLI
also omits a REPL so executions remain finite and repeatable.

## Next steps

- [Set up the CLI](/docs/varc-cli/getting-started)
- [Read the complete TOML reference](/docs/varc-cli/configuration)
- [Validate and run SQL](/docs/varc-cli/sql)
- [Build and run benchmarks](/docs/varc-cli/benchmark)
- [Plan and run a migration](/docs/varc-cli/migration)

Validate and run bounded JavaScript or TypeScript automation against Redis, Valkey, and Dragonfly from the Varc CLI.

Varc CLI scripts run JavaScript or TypeScript inside the same bounded QuickJS runtime used by the desktop app. Use them for finite, repeatable automation—not server-side Redis Lua and not an interactive REPL.

Validation is local and free. Running a script requires a Pro or Team CLI Token with the purpose-specific scriptRun capability.

Create a named script

Keep source in a normal project file and register it in varc.toml:

[scripts.inspect]
path = "scripts/inspect.ts"
connection = "local"
database = 0
language = "typescript"
timeout = "5s"
fetch = false

[scripts.inspect.environment]
TENANT = "CI_TENANT"

const key = `tenant:${env.TENANT}:health`;
const value = await redis.get(key);

console.log("inspected", key);
return { key, value };

Paths are relative to the varc.toml file. language may be javascript or typescript; when omitted, Varc infers it from .js, .mjs, .cjs, .ts, .mts, or .cts.

Validate without connecting

varc script validate inspect

Validation reads and bounds the source, resolves its language and timeout, checks environment mapping names, and transpiles it. It does not:

require a connection or CLI Token;
read mapped process-environment values;
contact Redis or the licensing service; or
grant network or desktop capabilities.

The source limit is 1 MiB. The timeout defaults to 5s and must be between 1ms and 30s.

Run against Redis

export REDIS_URL='redis://127.0.0.1:6379'
export VARC_CLI_TOKEN='varc_cli_...'
export CI_TENANT='acme'

varc script run inspect

Before connecting, Varc obtains a short-lived signed grant bound to the script source, language, logical database, timeout, fetch decision, and environment mapping. Environment values stay local and are never included in the grant request.

The script result is written to stdout. Captured console messages are written to stderr in human mode and included structurally in JSON mode:

varc --non-interactive --format json script run inspect

Ctrl-C or SIGTERM cancels the run. A timeout, memory limit, stack limit, operation quota, oversized reply, or cancellation stops the sandbox with a stable non-zero exit code.

Run a file or stdin directly

A named definition is optional:

varc script validate --file scripts/inspect.js
varc script run --file scripts/inspect.js --timeout 10s

Stdin requires an explicit language because there is no file extension:

printf 'return await redis.get("health")' |
  varc script run --stdin --language javascript

Use global --connection, --url, or --url-env to select the target for a direct source. --database overrides the selected logical database.

Map environment values explicitly

Scripts receive a frozen env object containing only configured mappings. The left side is the name visible to the script; the right side is the process environment variable Varc reads at execution time:

[scripts.rotate.environment]
TENANT = "PRODUCTION_TENANT"
NEW_VALUE = "ROTATION_VALUE"

Add or override mappings for one invocation with repeatable flags:

varc script run rotate \
  --env TENANT=CI_TENANT \
  --env NEW_VALUE=CI_ROTATION_VALUE

Both names must use uppercase ASCII letters, digits, and underscores, begin with an uppercase letter, and contain at most 64 characters. Missing source variables fail before licensing or Redis traffic. Varc does not scrub a value that the script deliberately prints or returns, so treat script output as sensitive when mapped values contain secrets.

Control network access

fetch() is denied by default. Grant HTTP or HTTPS access in the named definition or for one invocation:

[scripts.status]
path = "scripts/status.js"
fetch = true

varc script run status --allow-fetch
varc script run status --deny-fetch

The grant is intentionally broad HTTP/HTTPS access rather than a URL allowlist. Requests still have bounded URL, header, body, redirect, response-size, and deadline limits. Varc-generated fetch errors use a closed reason vocabulary and do not echo authored URLs, which may contain credentials.

Understand the Redis safety boundary

Scripts can perform ordinary Redis reads and writes through redis.* helpers or redis.call(). The locked-down command policy denies authentication, administrative and topology changes, blocking commands, Pub/Sub subscription state, connection-state changes, and server-side EVAL, SCRIPT, and FUNCTION execution.

This policy is a hard sandbox boundary, not a dry-run mode. A permitted write such as SET, HSET, or DEL reaches the selected server immediately. Review scripts and target selection before running them against valuable data.

Desktop-only capabilities are unavailable in the CLI: scripts cannot use Varc storage, the OS keyring, dialogs, clipboard, or notifications. The initial CLI also omits a REPL so executions remain finite and repeatable.