# Server Primitive commands

Each Server Primitive package adds its own commands. A namespace shows in `vitehub --help` only when its package is on.

## Read and write blobs

Start the dev server, then run `vitehub blob` in another terminal. Each command runs a `blob.*` [operation](https://vitehub.dev/docs/console/operations) of the app, so it uses the app's blobs. With `--url`, it runs on a deployed app with the Console on, using the credentials in [Run any operation](https://vitehub.dev/docs/cli/inspect#run-any-operation).

```bash [Terminal]
pnpm vitehub blob list --prefix avatars/ --limit 20
pnpm vitehub blob head avatars/ada.png
pnpm vitehub blob get avatars/ada.png --output ./ada.png
pnpm vitehub blob get reports/2026.csv > report.csv
pnpm vitehub blob put avatars/ada.png ./ada.png --content-type image/png
pnpm vitehub blob delete avatars/ada.png
pnpm vitehub blob media avatars/ada.png
pnpm vitehub blob variants avatars/ada.png --json
```

Each write command prints what it changed:

```txt [Output]
Created blob avatars/ada.png in store default (48213 B, image/png).
Deleted blob avatars/ada.png from store default.
```

Every command takes `--store <name>`, `--json`, `--url <url>` for a deployed app, and `--timeout <ms>`. The default Blob store is used unless you pass `--store`. Store names come from `blob.stores`. An unknown store fails and lists the stores, `default` first.

- `list` prints pathname, size, content type, and upload time. `--limit` defaults to 100, at most 250. When more blobs exist, stderr shows the `--cursor` for the next page.
- `head` prints one blob's metadata. A missing blob exits with status 1.
- `get` writes the bytes unchanged, to stdout by default, so redirect them. `--output <file>` writes the file and prints a summary. `--json` needs `--output`.
- `put` uploads a file relative to the current directory. Without `--content-type`, Blob storage guesses the type from the pathname. The output says if the blob was created or replaced. This label is a best guess from a metadata read just before the write, so eventual consistency and concurrent writers can make it wrong.
- `media` prints the blob's [media record](https://vitehub.dev/docs/blob/media). A missing record is built from the object and stored, as `blob.media.get()` does. A missing blob exits with status 1.
- `variants` lists a blob's cached image variants and crop replacements, with transform key, type, and size.
- `put` and `delete` refuse paths under `_vitehub/` (`BLOB_RESERVED_PATH`), which ViteHub keeps for itself. `get` and `head` can read them. The CLI replaces an existing blob without asking. The Console asks first (`overwrite: false` makes `blob.put` fail with `BLOB_EXISTS`).
- `delete` says if the blob existed, which is a best guess for the same reason. Deleting a missing blob changes nothing and exits with status 0.

Files travel as base64 in a JSON call, so `put` and `get` handle up to 8 MiB. The CLI checks an upload's size before it reads the file. Larger blobs fail with `BLOB_UPLOAD_TOO_LARGE` or `BLOB_DOWNLOAD_TOO_LARGE`, so use the app or your provider's tools. There is no `sign` command. `list` shows every object, including those under `_vitehub/` that the Console hides by default.

Errors go to stderr, or to `{ "error": { "code", "message" } }` on stdout with `--json`. The commands print no object URLs, because a signed URL can carry credentials. `media` prints the record's served route URL, which carries none. Metadata values under secret names, such as `token`, are redacted.

The operations are `blob.list`, `blob.head`, `blob.get`, `blob.put`, `blob.delete`, `blob.media`, and `blob.variants`, in the `blob` Console section. They run in the Nitro runtime and answer through the Console RPC, so you need access to the `blob` section. `blob.put` writes and `blob.delete` is destructive. `vitehub blob delete` asks for confirmation on a terminal and refuses elsewhere. Scripts pass `--yes` (or `-y`). The Console Blob page uses the same operations.

## Inspect the Email development outbox

When the dev server has Email on, read the in-memory outbox from another terminal:

```bash [Terminal]
pnpm vitehub email outbox list
pnpm vitehub email outbox get <id> --html
pnpm vitehub email outbox clear
```

Add `--json` for machine-readable output. The outbox exists only in `vite dev` and empties when the server restarts. `vitehub email preview <template>` renders a `server/emails` template without sending it, in your terminal, with no server.

The commands run `email.outbox-list`, `email.outbox-show`, and `email.outbox-clear` in the `email` Console section, so you need access to that section. `email.outbox-clear` is destructive: `vitehub email outbox clear` asks for confirmation on a terminal and refuses elsewhere. Scripts pass `--yes` (or `-y`). The `email.preview` operation renders a template through the same RPC. The written `vitehub email preview` command renders in your terminal without a server. The generated commands `vitehub email outbox list`, `outbox get`, and `outbox clear` print JSON.

## Read and reset Rate Limit counters

Read or reset one key's counter of a Rate Limit from `requireRateLimit()`:

```bash [Terminal]
pnpm vitehub rate-limit peek <id> <key>
pnpm vitehub rate-limit reset <id> <key> [--yes]
```

`<id>` is the stable ID of `requireRateLimit()`. `<key>` is the limited key, such as a client IP or user ID. Put `--` before a key that starts with a dash. Both commands take `--json`, `--url <url>`, and `--timeout <ms>`. Without `--url`, they call this project's dev server. With `--url https://app.example.com`, they call a deployed app with the [Console](https://vitehub.dev/docs/console) on, and sign with `VITEHUB_CONSOLE_PRIVATE_KEY_<NAME>`.

The commands run `rate-limit.peek` (a read) and `rate-limit.reset` in the `rate-limits` Console section. `reset` is destructive: it asks for confirmation on a terminal and refuses elsewhere, so scripts pass `--yes`. The Console **Rate Limits** page uses the same operations.

- The memory provider keeps counters in the server process, so you see only the counters of the process that answers.
- The Cloudflare binding has only `limit()`, which uses a token, so both commands report `unsupported` and exit with status 1.

## Inspect Server Env

These commands report the status of declared Server Env values, without the values.

```bash [Terminal]
pnpm vitehub env list [--stage <name>] [--json]
pnpm vitehub env check [--stage <name>] [--json]
```

Both load the Vite config in the stage mode, with `.env.<stage>` files, and process values win. They list each declared variable with status, source, and required and secret flags. `--json` also lists the host variable `names` of each env declaration, in read order. `env check` exits with status `1` when Server Env would fail to load, so it can gate CI or deploys.

## Check and push host env

`vitehub env diff` and `vitehub env push` compare and set the variables that the deployed app reads. They read the names of the last build in `deployment.json` and the target of the host in `.vitehub/link.json`, and they run the host CLI with your login. Neither loads the project config.

```bash [Terminal]
pnpm vitehub env diff [--host <host>] [--to github [--repo <owner/name>] [--environment <name>]] [--stage <name>] [--json]
pnpm vitehub env push [--host <host>] [--to github [--repo <owner/name>] [--environment <name>]] [--stage <name>] [--only <NAME>]... [--yes] [--json]
```

- `--host`: the link target to use. Without it, the default target.
- `--stage`: `production` (the default) or `preview`. A stage selects the host environment and the `.env.<stage>` file.
- `--only`: push only these names. Repeat it for more names.
- `--yes`: push without the question. Without a terminal, `env push` needs it and exits with `2` and a `rerun`.

When the build output for the host is missing, both commands build first, as `vitehub deploy` does. `vitehub deploy` runs the same check before it deploys: see [Check Env before a deploy](https://vitehub.dev/docs/cli/project#check-env-before-a-deploy).

`env diff` prints three lists: missing required names, missing optional names, and extra names on the host that no declaration reads. An entry with several names, such as `VITEHUB_GITHUB_TOKEN or GITHUB_TOKEN`, is set when one of them is. Hosts do not return values, so `env diff` compares names only and never says that a value changed. It exits with `1` when a required name is missing, so it can gate a deploy step.

`env push` reads each value from the shell first, then from `.env.<stage>.local`, `.env.<stage>`, `.env.local`, and `.env`, as Vite does. It reads the files in the `envDir` that the build recorded in `deployment.json`, so `envDir: "config"` reads `config/.env.production`, and `envDir: false` reads the shell only. For each entry it pushes the first name in read order that has a value. It does not push an entry without a local value, and it never deletes a host variable. It prints the names and where each value came from, never a value. Values go to the host CLI on stdin, or in an API request body, never in argv, and host CLI errors have the values replaced by `<redacted>`.

A secret from an env file must come from a file that git ignores and does not track. `env push` checks every file that the value reads: its own file, the files of the names that it expands with `$NAME`, and the real path of a symlink. When git cannot answer inside a repository, nothing is pushed. A file outside any git repository passes with a warning, because git cannot commit it. A secret from the shell is not checked.

| Host | Names | Values | Stages |
| --- | --- | --- | --- |
| Cloudflare | `wrangler secret list --name <worker>` | `wrangler secret put <name> --name <worker>`. Every value becomes a Worker secret. The Worker gets the new secret at once. Deploy sends values with the new version instead. | `production` only. A Worker has one set of secrets for every version. |
| Vercel | `vercel env ls --environment <target>` | `vercel env add <name> --environment <target> --force`, with `--sensitive` for a secret | `production` and `preview` |
| Netlify | `netlify env:list --context <context>` | The environment variables API with `NETLIFY_AUTH_TOKEN`, because `netlify env:set` takes the value in argv | `production`, and `preview` as `deploy-preview` |
| Deno | `deno deploy env list` | `deno deploy env load /dev/stdin --replace`, for every context. Deno infers secrecy from the name. Secret declarations with names outside its supported secret suffixes, such as `DATABASE_URL`, are refused before writing; set those in the Deno dashboard. A plain declaration gets `--non-secrets`. | `production` only |

### GitHub Actions secrets

`--to github` writes the same names to the Actions secrets of a GitHub repository instead of the host. Use it when your own GitHub workflow runs the deploy. It does not create a workflow or set up CI deploy: `vitehub deploy` runs on your machine by default.

```bash [Terminal]
pnpm vitehub env diff --to github
pnpm vitehub env push --to github --yes
pnpm vitehub env push --to github --repo acme/web --environment production --yes
```

- `--repo`: the repository as `owner/name`. Without it, the GitHub repository of the git remote `origin`.
- `--environment`: write the secrets of this GitHub deployment environment instead of the repository secrets. The environment must exist.
- `--host`: the build that lists the names. Without it, the default link target.
- `--stage`: only picks the `.env.<stage>` file. Any stage name works.

The token comes from `GITHUB_TOKEN`, then `GH_TOKEN`, then `gh auth token`, then an installation token of the GitHub App that `@vite-hub/forge` reads when `VITEHUB_GITHUB_APP_ID` is set. It needs write access to the repository secrets. The CLI encrypts each value with the repository public key (a libsodium sealed box) before the request, so the value is not in argv, in output, or in plain text on the wire. GitHub reserves names that start with `GITHUB_`, so an entry such as `VITEHUB_GITHUB_TOKEN or GITHUB_TOKEN` uses `VITEHUB_GITHUB_TOKEN` there.

### Encrypted env files

To keep values in git, commit a `.env.<stage>` file that [dotenvx](https://dotenvx.com/encryption) encrypted, and keep its private key out of git. `env push` decrypts each `encrypted:` value before it sends it, with the same stdin and redaction rules as a plain value. `vitehub deploy` decrypts the same way after its Env check, before it sets or uploads a value.

```bash [Terminal]
npx @dotenvx/dotenvx encrypt -f .env.production
DOTENV_PRIVATE_KEY_PRODUCTION=<private key> pnpm vitehub env push --yes
```

- The key name follows dotenvx: `DOTENV_PRIVATE_KEY_PRODUCTION` for `.env.production`, `DOTENV_PRIVATE_KEY` for `.env`, or the name that matches the `DOTENV_PUBLIC_KEY_*` line of the file. `env push` reads it from the shell first, then from `.env.keys`. A comma-separated list of keys works, as in `dotenvx rotate`.
- A git-tracked file may hold encrypted secrets. A plaintext secret in a tracked file is still refused.
- `env push` refuses to decrypt when git tracks `.env.keys`, and fails with the key name when the key is missing or wrong.

`vitehub init` ignores `.env*` except `.env.example`. To commit an encrypted stage file, add an exception, and keep `.env.keys` ignored:

```txt [.gitignore]
.env*
!.env.example
!.env.production
```

Vite does not decrypt the file for `vite dev` or `vite build`. Run them through dotenvx when the app reads these values at build time, such as `npx @dotenvx/dotenvx run -f .env.production -- vite build`.

### `SETUP_ENV_FILE_TRACKED`

A plaintext secret value comes from an env file that git tracks, directly, through `$NAME` expansion, or through a symlink. An `encrypted:` value is allowed. Nothing was pushed. Remove the file from git, ignore `.env*`, and rotate the values that git has seen. The command exits with `3`.

### `SETUP_ENV_DECRYPT_FAILED`

The private key cannot decrypt an `encrypted:` value, for example because the file was encrypted with another key. `why` names the dotenvx error code, such as `WRONG_PRIVATE_KEY`. Nothing was pushed. The command exits with `1`.

### `SETUP_ENV_KEYS_TRACKED`

Git tracks `.env.keys`, so everyone with the repository can decrypt the encrypted env files. Nothing was pushed. Remove the file from git, ignore it, and rotate the keys with `dotenvx rotate`. The command exits with `3`.

### `SETUP_ENV_FILE_NOT_IGNORED`

A plaintext secret value comes from an env file that git does not track and does not ignore, so the next commit can add it. Nothing was pushed. Add `.env*` to `.gitignore`. The command exits with `3`.

### `SETUP_ENV_GIT_FAILED`

A secret value comes from an env file in a git repository, but `git ls-files` or `git check-ignore` failed, so the CLI cannot tell whether git has the secret. Nothing was pushed. Fix the repository, or set the value in the shell. The command exits with `1`.

### `SETUP_ENV_NAME_UNKNOWN`

`--only` names a variable that the build output does not list. The command exits with `2`.

### `SETUP_ENV_PRIVATE_KEY_MISSING`

An env file holds `encrypted:` values, and its private key is not in the shell or in `.env.keys`. The fix names the variable, such as `DOTENV_PRIVATE_KEY_PRODUCTION`. Nothing was pushed. The command exits with `2`.

### `SETUP_ENV_STAGE_UNSUPPORTED`

The stage is not `production` or `preview`, or the host has no preview environment. The command exits with `3`.

### `SETUP_GITHUB_REPOSITORY_REQUIRED`

`--to github` found no `--repo` and no github.com remote named `origin`. The command exits with `2`.

### `SETUP_GITHUB_REQUEST_FAILED`

The GitHub API refused a request, for example because the token cannot write secrets or the environment does not exist. The command exits with `1`.

### `SETUP_ENV_VALUE_UNSUPPORTED`

The host cannot safely store this value, such as a Deno value with a single quote or a line break, a secret name Deno cannot classify, or an existing Netlify variable without Functions scope or secret storage. Set it in the host dashboard. The command exits with `3`.
`env list --url <app>` asks the running app instead of a local stage, through the `env.inspect` [operation](https://vitehub.dev/docs/console/operations). Pass `--url` to check a deployment:

```bash [Terminal]
pnpm vitehub env list --url https://my-app.example.com
```

It returns `ok` and, for each declaration, the status, the `names` it reads, the `name` that supplied the value, and the required, secret, and blocking flags. Values never leave the app.

## Generate and derive secrets

```bash [Terminal]
pnpm vitehub secret generate
VITEHUB_SECRET=... pnpm vitehub secret derive myapp:webhooks
pnpm vitehub secret console-key ci
```

`secret generate` prints 32 random bytes as base64 for [`VITEHUB_SECRET`](https://vitehub.dev/docs/env/app-secret). `secret derive <purpose>` prints `deriveSecret(purpose)` for the `VITEHUB_SECRET` in the shell. `secret console-key [name]` prints a new Ed25519 key pair for [signed Console requests](https://vitehub.dev/docs/console/signed-requests): the `VITEHUB_CONSOLE_KEY_<NAME>` line for the app and the `VITEHUB_CONSOLE_PRIVATE_KEY_<NAME>` line for the CLI. The name defaults to `CLI`. None of them loads the project.

## Manage Database migrations

The Database commands refresh the Database Definitions, then run Drizzle Kit. When every Database is named, ViteHub runs once per generated Drizzle config and stops at the first failure.

```bash [Terminal]
pnpm vitehub database generate
pnpm vitehub database generate --name add-audit-log
pnpm vitehub database generate --custom --name backfill-state
pnpm vitehub database generate --custom --schema-snapshot --name move-tables
pnpm vitehub database migrate
pnpm vitehub database up
```

`database up` converts complete Drizzle Kit 0.x folders and folders of hand-written SQLite or D1 `.sql` files to one folder per migration. For hand-written files, it replays the SQL on a temporary database to record the schema. `database generate` and `database migrate` refuse the old layouts with `DATABASE_MIGRATIONS_OLD_LAYOUT`, except that D1 HTTP can migrate flat SQL directly.

`database generate` forwards Drizzle Kit arguments, supports `--name <name>` for a migration name, and uses `--custom` to create an empty custom migration. Drizzle Kit copies the previous snapshot into a custom migration, for SQL that changes only data. On SQLite, write the statements of a custom migration one after the other. `database migrate` runs each statement without changing the file. When the SQL changes the tables to the current Database Definitions, add `--schema-snapshot`: the migration then gets the snapshot of those Definitions, so the next `database generate` has nothing to add. When a change can be a rename, Drizzle Kit asks in a terminal. Without a terminal, or with `CI` set, `database generate` does not ask: it exits with code 2 and `DATABASE_GENERATE_AMBIGUOUS_CHANGE`, which prints the `--hints` command for each answer. Read [Rename a column or table](https://vitehub.dev/docs/database/configure#rename-a-column-or-table). `database migrate` accepts forwarded Drizzle Kit migration arguments.

## Export a Database

`database export` writes a SQL dump of each database, with no build. It reads the local SQLite file by default. `--remote` reads Cloudflare D1 (through the Cloudflare API), D1 HTTP, remote libSQL, or Postgres (through `pg_dump`).

```bash [Terminal]
pnpm vitehub database export
pnpm vitehub database export --remote --stage production --output backups/database.sql
```

| Option | Description |
| --- | --- |
| `--remote` | Read the remote database. Needed for a database that is not a local file. |
| `--stage <name>` | Load the Vite env files of this mode. Process variables win. |
| `--database <name>` | Export only this database. |
| `--output <file>` | Write this file. Defaults to `.vitehub/exports/database/<name>-<local\|remote>-<time>.sql`. |

See [Export a database](https://vitehub.dev/docs/database/configure#export-a-database) for each driver and the dump format.

## Run SQL on a Database

`database sql` runs SQL on one database and prints the rows of each statement as a table. Without a SQL argument, it reads stdin. `database drop` drops every table of one database and its migrations table. It asks first, and needs `--yes` without a terminal. `database reset` drops the same way, then applies the migrations of that database again. They use the local SQLite file or PGlite folder by default. Any other database needs `--remote`.

```bash [Terminal]
pnpm vitehub database sql "select id, email from users limit 5"
pnpm vitehub database sql --json < report.sql
pnpm vitehub database drop --yes
pnpm vitehub database reset --yes
```

| Option | Description |
| --- | --- |
| `--remote` | Use the remote database. Needed for a database that is not a local file or folder. |
| `--stage <name>` | Load the Vite env files of this mode. Process variables win. |
| `--database <name>` | The database to use. Needed when the app has several. |
| `--json` | `sql` only. Print one JSON array with `{ columns, rows, rowsAffected }` for each statement. |
| `--yes` | `drop` and `reset` only. Drop without asking. |

See [Run SQL and drop tables](https://vitehub.dev/docs/database/configure#run-sql-and-drop-tables) for what `drop` drops on each driver.

## Seed data

`vitehub seed` writes the starting data of the app: the seed file of each Database, the KV values in `server/seed/kv/`, and the Blob files in `server/seed/blob/`. It writes local data by default.

```bash [Terminal]
pnpm vitehub seed
pnpm vitehub seed kv blob
pnpm vitehub seed --remote --stage production
```

| Option | Description |
| --- | --- |
| `<primitive>...` | Seed only these: `database`, `kv`, or `blob`. |
| `--remote` | Write the deployed data. KV and Blob call the deployed app, like `vitehub kv set --url`. |
| `--url <url>` | The deployed app for `--remote`. Defaults to `vitehub({ publicUrl })`. |
| `--stage <name>` | Load the Vite env files of this mode. Process variables win. |
| `--database <name>` | Seed only this database. |
| `--timeout <ms>` | Request timeout of each call to the app. |

Without `--remote`, KV and Blob write the stores of the running dev server, so start `vite dev` first. The Database seed needs no server. See [Seed data](https://vitehub.dev/docs/database/configure#seed-data) for the seed file of a Database, [Seed values](https://vitehub.dev/docs/kv/configure#seed-values) for KV, and [Seed files](https://vitehub.dev/docs/blob/configure#seed-files) for Blob.

## Browse Database tables

`database tables` and `database rows` run `databases.tables` and `databases.browse`, the [operations](https://vitehub.dev/docs/console/operations) of the Console Databases section. They read the running app's Database Definitions, so they work on SQLite, D1, libSQL, and Postgres without a Drizzle Kit config. They never write.

```bash [Terminal]
pnpm vitehub database tables
pnpm vitehub database rows users --limit 20 --sort email --direction desc
pnpm vitehub database rows users --search ada --json
pnpm vitehub database rows users --database analytics --offset 20 --url https://app.example.com
```

`database rows` reads at most 100 rows at a time and cuts cells at 32 KiB. `--offset` pages, `--sort <column>` and `--direction asc|desc` sort, and `--search <text>` matches any column. Without a table, it reads the tables only. A table that does not exist fails with `CONSOLE_NOT_FOUND`. `--database` picks a named database. Access needs the `databases` section, and `databases:read` is enough.

## Read and invalidate the cache

With `cache` set in `vitehub()`, `vitehub cache` reads Nitro's `cache` mount, where `defineCachedFunction()` and `defineCachedHandler()` keep their entries. The commands run the `cache.*` [operations](https://vitehub.dev/docs/console/operations) of the Console Cache section, on the dev server or with `--url` on a deployed app.

```bash [Terminal]
pnpm vitehub cache list
pnpm vitehub cache list --prefix nitrofunctions --limit 20
pnpm vitehub cache get 'nitrofunctions.Cm3ZWo:getStars:a1b2.json'
pnpm vitehub cache delete 'nitrofunctions.Cm3ZWo:getStars:a1b2.json'
pnpm vitehub cache delete --prefix 'nitrofunctions.Cm3ZWo:getStars'
```

- Keys show as Nitro stores them: `<group>:<name>:<hash>.json`. Nitro adds a hash to a group or name that has other characters than letters, digits, and `_`, so `nitro/functions` is `nitrofunctions.<hash>`. Copy keys and prefixes from `cache list`.
- `cache list` reads at most 100 entries per page. Pass the printed `--cursor` for the next page. The group is `functions` or `handlers`, and the name is the `name` option, or `_` without one.
- `cache get` cuts the value at 256 KiB.
- `cache delete` removes one key, or at most 1,000 entries under `--prefix` per call. There is no command that clears the whole cache. Nitro computes a removed value again on the next call.
- The driver must list keys. Vercel Runtime Cache cannot, so `cache list` fails there.
- Access needs the `cache` section. `cache:read` allows `list` and `get` only.

## Read and write KV keys

Start the dev server, then run `vitehub kv` in another terminal. Each command runs a `kv.*` [operation](https://vitehub.dev/docs/console/operations) of the app, so it uses the app's keys. With `--url`, it runs on a deployed app with the Console on, using the credentials in [Run any operation](https://vitehub.dev/docs/cli/inspect#run-any-operation).

```bash [Terminal]
pnpm vitehub kv list --prefix users: --limit 20
pnpm vitehub kv get settings
pnpm vitehub kv has settings
pnpm vitehub kv set settings '{"theme":"dark"}' --json-value
pnpm vitehub kv set session:42 active --ttl 3600
pnpm vitehub kv set template @./fixtures/template.txt
pnpm vitehub kv delete settings
```

Each write command prints what it changed:

```txt [Output]
Created key settings in store default (object).
Created key session:42 in store default (string, TTL 3600 s).
Deleted key settings from store default.
```

Every command takes `--store <name>`, `--json`, `--url <url>` for an app other than the dev server of this project, and `--timeout <ms>`. Commands use the default KV store. `--store` picks a named store from `kv.stores`. An unknown store fails and lists the stores, `default` first.

- `list` prints one key per line. Use `--json` when keys contain line breaks. `--limit` defaults to 100, at most 1000. When more keys exist, stderr shows the `--cursor` for the next page. Some drivers count scanned entries toward the limit, so a page can hold fewer keys, or none, and still have a next cursor.
- `get` writes a string value unchanged, with no added newline, and other JSON values as formatted JSON. Binary values go to stdout as bytes, or as base64 with `"encoding": "base64"` in `--json` output. A missing key exits with status 1.
- `has` exits with status 0 when the key exists and 1 when it does not.
- `set` writes a string. `--json-value` parses the value as JSON. JSON input rejects values that underflow to zero or whose decimal size changes when parsed, so use strings for those and for integers outside JavaScript's safe range. A value that starts with `@` reads a UTF-8 file relative to the current directory. The output says if the key was created or updated.
- `--ttl <seconds>` on `set` sets an expiry, and takes positive fractional seconds. Cloudflare KV rounds up to whole seconds, at least 60. Upstash needs at least one second and rounds up to whole seconds. The output shows the real TTL and a notice when the driver changes it.
- `delete` says if the key was found. Deleting a missing key changes nothing and exits with status 0.

KV storage parses stored strings that look like JSON, so `"2026"` can read back as the number `2026`. There is no `clear` command, so each delete is explicit.

Errors go to stderr, or to `{ "error": { "code", "message" } }` on stdout with `--json`. Like the Console KV page, the commands print values as stored, without redaction. Do not store credentials in keys you inspect in shared logs.

The operations are `kv.list`, `kv.get`, `kv.has`, `kv.set`, and `kv.delete`, in the `kv` Console section. They run in the Nitro runtime and answer through the Console RPC, so you need access to the `kv` section. `kv.delete` is destructive: `vitehub kv delete` asks for confirmation on a terminal and refuses elsewhere. Scripts pass `--yes` (or `-y`). The Console KV page uses the same operations.


## Run Choices

A Choices definition is a `defineChoices()` result that picks options from a text. `choices list` finds files that call `defineChoices()`, loads them, and prints the exports that hold the result. It skips `node_modules`, `dist`, `build`, `coverage`, and dot folders. There is no registry: the file path is the address. A file that fails to load is listed with its error, and the command exits with status `1`.

```sh
pnpm vitehub choices list
```

```txt [Output]
FILE                              EXPORT    NAME
server/utils/forecast-choices.ts  forecast  forecast

Run one with: vitehub choices run server/utils/forecast-choices.ts "<text>"
```

`choices run <file> <text>` loads the file, calls `resolve()` with the text, and prints the selection as JSON. It calls the definition's gateway, so it reads the app's keys, such as `AI_GATEWAY_API_KEY` or `TYPESAFE_API_KEY`, from the shell or the project's `.env` files. `--inspect` prints the questions and state that `resolve()` would send, without a model call.

```sh
pnpm vitehub choices run server/utils/forecast-choices.ts "nord parts except vak supply"
pnpm vitehub choices run server/utils/forecast-choices.ts "nord parts" --inspect
```

The first command's output, with the offline gateway of the [Choices tutorial](https://vitehub.dev/docs/choices/get-started):

```json [Output]
{
  "supplier": { "exclude": ["vak"], "include": ["nord"] },
  "chart": { "confidence": 0, "ranked": [{ "probability": 0.1, "value": "line" }, { "probability": 0.1, "value": "bar" }], "value": null }
}
```

| Option | Meaning |
| --- | --- |
| `--export <name>` | The export to run when the file has more than one `defineChoices()` export. |
| `--context <json>` | The `context` for `options` functions, such as `'{"tenantId":"t1"}'`. |
| `--inspect` | Print the plan of `inspect()` instead of calling the gateway. |
| `--json` | `choices list` only: print the files as JSON. |

A Choices error prints `{ "error": { "code", "message" } }` and exits with status `1`. The command loads the file with Vite but without the project config, so imports must use relative paths or package names. Nuxt aliases such as `~~` and auto-imports do not work. See [Choices server API](https://vitehub.dev/docs/choices/server-api) for `resolve()` and `inspect()`.

## Check and move translations

`vitehub i18n status` reads `t`, `<Trans>`, `plural`, `select`, and `msg` in the code, and compares them with the records in `locales/<locale>/`. It prints, per locale, the number of messages, translated messages, missing messages, and unused records. It needs no dev server and changes no file.

```bash [Terminal]
pnpm vitehub i18n status --json
pnpm vitehub i18n export es --output es.po
pnpm vitehub i18n import es es.po
pnpm vitehub i18n prune --yes
```

`export` writes a PO file for Poedit or a translation service. `import` saves its translations as records. `prune` deletes the records of messages that the code no longer has. Without `--yes`, it only lists them. Read [Translate your first page](https://vitehub.dev/docs/i18n/get-started) for the full flow.

## Run app tasks

A task is a [Nitro task](https://nitro.build/docs/tasks): a file in `server/tasks/` that default-exports `defineTask()`. Use tasks for seeds, backfills, data repair, and one-off admin jobs. `vitehub()` registers each file and turns on Nitro tasks, so you do not set `nitro.serverDir` or `nitro.experimental.tasks`. The task name is the path with `/` replaced by `:`, so `server/tasks/db/seed.ts` is `db:seed`.

This seed task adds a row to the `notes` table of the default Database:

```ts [server/databases/default.ts]
import { defineDatabase } from 'vite-hub/database'
import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'

export default defineDatabase({
  schema: {
    notes: sqliteTable('notes', {
      id: integer('id').primaryKey({ autoIncrement: true }),
      title: text('title').notNull(),
    }),
  },
})
```

```ts [server/tasks/db/seed.ts]
import { useDatabase } from 'vite-hub/database'
import { defineTask } from 'nitro/task'

export default defineTask({
  meta: { description: 'Add one demo note' },
  async run({ payload }) {
    const { db, schema } = useDatabase('default')
    const title = typeof payload.title === 'string' ? payload.title : 'Hello'
    const [note] = await db.insert(schema.notes).values({ title }).returning()
    return { result: note }
  },
})
```

Start the dev server, then run the task in another terminal. It runs in that server's Nitro runtime, so `useDatabase()`, `kv`, `blob`, and `env` get the same bindings as a request.

```bash [Terminal]
pnpm vitehub task list
pnpm vitehub task run db:seed '{"title":"First note"}' --yes
pnpm vitehub task run db:seed '{"title":"First note","count":3}' --json --yes
pnpm vitehub task run db:seed --url https://app.example.com --yes
```

```json [Output]
{
  "tasks": [
    { "description": "Add one demo note", "name": "db:seed" }
  ]
}
{
  "durationMs": 14,
  "name": "db:seed",
  "result": { "id": 1, "title": "First note" }
}
```

- The argument after the task name is the payload, a JSON object. Without it the payload is `{}`. `--input '{"name":"db:seed","payload":{...}}'` or `--input @file.json` passes the whole input.
- The command prints the name, `durationMs`, and the `result` from `run()`. A task that throws exits with status 1 and `TASK_FAILED`. The message goes to stderr, or to `{ "error": { "code", "message", "fix" } }` with `--json`. The server log shows the stack.
- An unknown name fails with `TASK_NOT_FOUND`. A task file without `run()` fails with `TASK_NOT_IMPLEMENTED`.
- Nitro runs one instance of a task name at a time per server. A second run while the first is active gets the first run's result.

`vitehub inspect definitions --kind task` lists the files in `server/tasks/` with no server. `task list` asks the running app, so it also shows tasks that `nitro.tasks` declares in the Vite config.

`task list` and `task run` are the `task.list` and `task.run` [operations](https://vitehub.dev/docs/console/operations) in the `tasks` section. They exist when the app has task files or declares `nitro.tasks`. A generated Nitro plugin gives them Nitro's registry, so they also work on a deployment with `--url` and the Console credentials (`task run` needs `console.invoke`). `task run` is `destructive`, so it asks for `--yes`. The `tasks` section has no Console page. Grant it in `console.authorize` with `sections: ['tasks']`, or `'tasks:read'` for listing only.

> [!WARNING]
> A task can change anything the app can. Give `tasks` only to people who may run a seed or a backfill.

`vitehub task` does not support Nuxt, because Nuxt runs its own Nitro and scans `server/tasks` itself when `nitro.experimental.tasks` is on.

Set `nitro: { experimental: { tasks: false } }` to turn tasks off. A task that `nitro.tasks` declares keeps its handler and description.

## Edit and publish Content

Start the dev server, then run `vitehub content` in another terminal. Each command runs a `content.*` [operation](https://vitehub.dev/docs/console/operations) with the app's `server/content.ts`, so it sees the app's drafts and published documents.

```bash [Terminal]
pnpm vitehub content collections
pnpm vitehub content list posts
pnpm vitehub content edit posts hello
pnpm vitehub content diff posts hello
pnpm vitehub content publish --collection posts --id hello
pnpm vitehub content schedule --collection posts --id hello --at 2026-10-20T09:00:00+02:00
```

- `edit` opens the draft in `$EDITOR`, or saves `--file`, and prints the draft's field issues. While another session holds the edit lease, it fails with `CONTENT_LEASE_HELD`, unless you pass `--override-lease`.
- `publish` and `schedule` list the pending changes with their draft digests (content hashes), ask for confirmation, and pin exactly those digests. If a draft is saved in between, the command fails and nothing is published. `--yes` skips the prompt, and `--dry-run` only lists the changes. Without an interactive terminal, they need `--yes`.
- Omit the id for a singleton.

Every command takes `--json`, `--url <origin>`, and `--timeout <ms>`. Without `--url`, it calls this project's dev server (see [Run any operation](https://vitehub.dev/docs/cli/inspect#run-any-operation)). With `--url`, it calls a deployed app with the Console on, using the credentials from [the table below](https://vitehub.dev/docs/cli/agents#inspect-and-cancel-on-a-deployed-app). See [Content CLI](https://vitehub.dev/docs/content/cli) for each command's output.

## Run a Schedule on demand

`schedule run` starts a Static Schedule Definition that sets `manual: true`, and prints the run status, duration, run id, and scheduled time. `--json` prints the run record. A failed run still exits with `0`, so read `status` or `error`. An unknown name fails with `SCHEDULE_DEFINITION_NOT_FOUND` (`404`). A definition without `manual: true` fails with `SCHEDULE_MANUAL_RUN_DISABLED` (`403`).

```bash [Terminal]
pnpm vitehub schedule run sync
pnpm vitehub schedule run sync --at 2026-01-31T23:59:00Z
pnpm vitehub schedule run sync --url https://app.example.com
```

`--at` runs the definition as if its cron fired at that time, without checking the cron. The handler gets it as `scheduledAt`, and `vitehub schedule runs list <name>` lists the run under it. Use it to test code that depends on the fire time, such as a job near midnight or on a month's last day. The value is an ISO 8601 date-time with `Z` or an offset, such as `2026-01-31T23:59:00+01:00`. No time zone, a date only, or a day that does not exist (`2026-02-30`) fails with `SCHEDULE_INVALID_SCHEDULED_AT` (`400`), and nothing runs.

`schedule run` is the `schedule.run` [operation](https://vitehub.dev/docs/console/operations) of the Schedules section. Without `--url`, the dev server runs the definition in its Nitro runtime, with the app's Nitro plugins and dev bindings, and the run shows in `vitehub schedule runs list <name>`. With `--url`, it calls the deployment with the [credentials below](https://vitehub.dev/docs/cli/agents#inspect-and-cancel-on-a-deployed-app). The deployment runs only definitions that the [Console](https://vitehub.dev/docs/console) installed with `invoke: true`, which is on in development and off in a production build.

A CI job needs no Console login. Make a key pair with `vitehub secret console-key ci`, set `VITEHUB_CONSOLE_KEY_CI` on the app with `console: true`, and set `VITEHUB_CONSOLE_PRIVATE_KEY_CI` as a secret of the job. `vitehub schedule run <name> --url <origin>` then [signs the call](https://vitehub.dev/docs/console/signed-requests), the same as every other command with `--url`.

The Console Schedules page runs the same operation. A read-only grant (`"schedules:read"`) can list runs but cannot run a Schedule.

## Run and inspect Schedules

Start the dev server, then run `vitehub schedule` in another terminal. `runs list` and `runs get` read that server's Schedule Run store, so they show the runs the app recorded: manual runs and Process Runtime runs.

```bash [Terminal]
pnpm vitehub schedule runs list digest --limit 5
pnpm vitehub schedule runs list digest --json
pnpm vitehub schedule runs get srun_static_digest_2026-05-22T07:00:00.000Z
```

```txt [Output]
RUN                                          STATUS     SCHEDULED AT              ATTEMPTS  ERROR
srun_static_digest_2026-05-22T07:00:00.000Z  succeeded  2026-05-22T07:00:00.000Z  1         -
```

`list` shows every Schedule of the server: each Static Schedule Definition with its cron, then the Schedules that code started. An app with only cron Schedules lists them without a KV store:

```txt [Output]
SCHEDULE       CRON
morning-brief  0 9 * * 1-5 (Europe/Copenhagen)
pr-upkeep      */15 * * * *
```

`start` and `cancel` work on the Schedules that code starts with [`startSchedule()`](https://vitehub.dev/docs/schedule/server-api#start-a-schedule-from-code). The Definition has no `cron`. `start` takes `--at` for one run, or `--cron` and `--time-zone` for a repeating one. To pass a payload, give the whole input as JSON with `--input`.

```bash [Terminal]
pnpm vitehub schedule start reminder --at 2026-11-08T09:00:00Z
pnpm vitehub schedule start reminder --input '{"name":"reminder","cron":"0 9 * * 1-5","timeZone":"Europe/Madrid","payload":{"text":"Stand-up"}}'
pnpm vitehub schedule list
pnpm vitehub schedule runs list sched_mh1x2y3z_ab12cd34
pnpm vitehub schedule cancel sched_mh1x2y3z_ab12cd34 --yes
```

Every command takes `--json`, `--url <origin>`, and `--timeout <ms>`. `runs` takes `--limit <n>`. Errors go to stderr, or to the JSON body with `--json`. `schedule.runs` and `schedule.attempts` are `read` operations of the Schedules section.

The output redacts URLs with credentials, bearer tokens, and secret assignments in error messages. An unknown run id fails with `SCHEDULE_RUN_NOT_FOUND` (`404`).

## Run Workflows in development

Turn on `hubWorkflow()` and start the dev server.

```bash [Terminal]
pnpm vitehub workflow start welcome '{"name":"Ada"}'
pnpm vitehub workflow runs get <runId>
pnpm vitehub workflow cancel <runId> --yes
pnpm vitehub workflow resume <token> '{"approved":true}'
pnpm vitehub workflow runs list --status failed
pnpm vitehub workflow runs clear --yes
```

The commands are generated from the `workflow.start`, `workflow.get`, `workflow.cancel`, and `workflow.resume` [operations](https://vitehub.dev/docs/console/operations). They call the Console RPC of the running app, so app and CLI runs share state, and `--url <origin>` calls a deployed app that serves the Console RPC. The argument after the Workflow name or token is the payload, a JSON value; `--input '{"workflow":"welcome","payload":{...}}'` or `--input @file.json` passes the whole input. `cancel` and `runs clear` ask for confirmation unless you pass `--yes`. All commands accept `--json`, `--url`, and `--timeout`. A run that this runtime did not start needs `--workflow <name>` for `runs get` and `cancel`. A `console.authorize` grant of `workflows` allows them all; `workflows:read` allows only `runs get` and `runs list`.

Inline runs can be read with `runs get` for five minutes. Inline cancellation is not supported. `cancel` terminates a Cloudflare run through its Workflow binding. OpenWorkflow starts enqueue work. The worker that each Node server starts executes it. For `resume`, pass the token from `context.createSignal()` on Cloudflare, OpenWorkflow, or an inline run in the same process. On Vercel, pass a Workflow DevKit hook token. Do not pass a run ID or signal name.

### Inspect runs in development

`vite dev` records every inline run: the runs that `vitehub workflow start`, the Console, and app code start. `vitehub workflow runs list` lists them newest first, with their status and step count. Filter with `--workflow <name>`, `--status queued|running|completed|failed`, and `--limit <n>`. In `vite dev`, `vitehub workflow runs get <runId>` prints the run with each step, its status and times, the error of a failed step, and the result of the run. Add `--json` for the step outputs. Credentials in results, outputs, and error messages are redacted. `vitehub workflow runs clear --yes` removes all recorded runs and prints how many it removed, so a test or an agent can start from an empty history without a restart. It does not cancel active runs, and `runs get` still reads a run from its provider after it.

The history lives in the memory of the dev server. It keeps the newest 200 runs and is empty after a restart or `runs clear`. It records the steps of a folder Workflow, the numbered files that run through `steps`. Inline runs do not retry a failed step, so each step runs once. The history records inline runs only: a run that a Cloudflare Workflow binding, OpenWorkflow storage, or a native Vercel Workflow starts is not in it. With the `node` preset, `vite dev` runs Workflows on OpenWorkflow, so the history is empty there; read a run with `vitehub workflow runs get`. Only the dev Nitro plugin imports the history code, so a build does not include it and never records runs. On a deployment, `runs list` and `runs clear` fail with `WORKFLOW_RUNS_UNAVAILABLE` (`409`), and `runs get` reads the run from the provider, without steps. Read one deployed run with `vitehub workflow runs get <runId> --workflow <name>`.
## Run Workspace commands during development

Use `vitehub workspace dev` to run a command in a Workspace without an Agent.
Start the dev server, then run it in another terminal.

```bash [Terminal]
pnpm vitehub workspace dev --url http://localhost:5173 docs exec pnpm test --filter api
pnpm vitehub workspace dev --timeout 180000 docs exec "npm run lint"
pnpm vitehub workspace dev --path guides --path examples docs exec pnpm test
```

The command runs through the Workspace dev endpoint of `hubWorkspace()` on the Compatible Vite Development Server.
ViteHub creates a Workspace Session, runs the command, prints stdout and stderr, and commits the session when the command succeeds.
Put options before the Workspace target, and `exec` before one-shot command args.
Repeat `--path <path>` to load only those paths into the session.
Without a command in an interactive terminal, the CLI opens a prompt for repeated commands.

```txt [Output]
Connected to docs at http://localhost:5173
> pnpm test
```

## Work on Workspace files in a local folder

`vitehub pull` and `vitehub push` keep a folder of the project in sync with one ref of a Workspace, as `git pull` and `git push` do with a branch. Edit the files in your editor, and edit the same ref in the Console. The first pull names the folder and the ref and writes `vitehub.lock`; commit that file. See [Work on a ref in a local folder](https://vitehub.dev/docs/workspace/server-api#work-on-a-ref-in-a-local-folder).

```bash [Terminal]
pnpm vitehub pull site --dir content --ref draft --url https://docs.example.com
pnpm vitehub pull --dry-run
pnpm vitehub push --message "Fix the install guide"
```

Run `pnpm vitehub hooks install` once to check for conflicts before each commit and to push the checkout folders when you push the default branch. A push of another branch leaves the remote ref alone, so work in progress does not reach the shared draft. The Workspace push updates `vitehub.lock`, and Git cannot add it to a push that already started, so the hook stops that Git push. Commit `vitehub.lock` and any pulled files, then run `git push` again. Skip the hooks for one Git command with `--no-verify`.

## Read Workspace history during development

`vitehub workspace history`, `refs`, and `show` read a Workspace's [retained history](https://vitehub.dev/docs/workspace/server-api#retained-folder-history): its refs, such as `draft` and `published`, and the revisions on each. Run them next to the dev server, or pass `--url <origin>` for a deployed app. They only read, and never commit or move a ref.

```bash [Terminal]
pnpm vitehub workspace history content
pnpm vitehub workspace history content --ref draft --limit 10
pnpm vitehub workspace refs content
pnpm vitehub workspace get content draft
pnpm vitehub workspace get content published posts/hello.md
pnpm vitehub workspace get content 9a97b4caf7ed04dd7d590ab9192ee21211375d0fb7652c586bd506049bd39f3a posts/hello.md
```

```txt [Output]
REVISION                                                          REF        CREATED AT                AUTHOR  FILES  MESSAGE
bc4cf2341f4244c405de80d58ff6b53b5855b27e22dfb9b61567c9cfc44a4f3d  draft      2026-10-15T12:12:47.744Z  ada     2      Edit hello
9a97b4caf7ed04dd7d590ab9192ee21211375d0fb7652c586bd506049bd39f3a  published  2026-10-15T12:12:47.733Z  editor  1      Publish hello
c08f4415a5303b77a6a0e58436b885215950ed298e3e6cebbc85c18f2b97edb9  draft      2026-10-15T12:12:47.727Z  ada     2      Save hello
8d104bde6b19e80361256ab8f6f0bfee81c2756210c864c5db1ea95a25e40d0f  main       2026-10-15T12:12:47.716Z  -       1      Start content
```

- `history <workspace>` lists revisions newest first. Without `--ref`, it merges all refs and shows the newest `--limit` revisions (default `20`, at most `100`). With `--ref <ref>`, it lists one ref and prints the `--cursor` of the next page.
- `refs <workspace>` lists each ref with its head revision.
- `show <workspace> <ref|revision> [path]` takes a ref name or full revision id. A ref name wins when both match. Without a path, it prints the revision and its files with size, media type, and SHA-256 digest. With a file path, it prints the file as it was then, so you can redirect it. A binary file prints a notice instead, and `--json` returns its bytes as `base64`. With a directory path, it lists the files under it.

`AUTHOR` is the revision `metadata.author`, or `-`. Times are ISO 8601 UTC. Blob + Database revision ids are SHA-256 digests of the revision manifest. Every command takes `--json`, `--url <origin>`, and `--timeout <ms>`. With `--json`, the CLI prints revision objects with `id`, `ref`, `parentId`, `createdAt`, `message`, `metadata`, `author`, `files`, and `bytes`, and `show` returns content as `utf8` text or `base64` bytes. Errors go to stderr, or to the JSON body with `--json`, with exit status 1.

A Workspace whose Store keeps no revisions fails with `WORKSPACE_R0069` and names the [Blob + Database Store](https://vitehub.dev/docs/workspace/configure#blob-database-store), which keeps refs and revisions.

The commands are the `workspace.history`, `workspace.refs`, and `workspace.show` [operations](https://vitehub.dev/docs/console/operations) of the Workspaces section. They run in the app's Nitro runtime, so they work on the dev server and on a deployed app. All three read, so `console.authorize` grants them with `workspaces` or `workspaces:read`.

<!-- vitehub-docs:section-links -->
## In this section

- [Start](https://vitehub.dev/raw/docs/cli.md)
- Commands
  - [Server Primitive commands](https://vitehub.dev/raw/docs/cli/primitives.md) (this page)
  - [Agent commands](https://vitehub.dev/raw/docs/cli/agents.md)
- [Operate](https://vitehub.dev/raw/docs/cli/inspect.md)

Next: [Agent commands](https://vitehub.dev/raw/docs/cli/agents.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
