> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> varg command-line interface

The varg CLI provides commands for authentication, rendering, and quick generation.

## Installation

The CLI is included with the `vargai` package:

```bash theme={null}
bun install vargai ai
```

Or use directly with `bunx`:

```bash theme={null}
bunx vargai <command>
```

## Authentication Commands

### Login

Sign in to varg.ai and save your API key:

```bash theme={null}
bunx vargai login
```

Two modes:

* **Email** — enter email, receive a 6-digit code, verify. Creates account + API key automatically.
* **API key** — paste an existing key from the dashboard.

Credentials are saved to `~/.varg/credentials`.

### Logout

Clear saved credentials:

```bash theme={null}
bunx vargai logout
```

### Check Balance

View your credit balance:

```bash theme={null}
bunx vargai balance
```

### Top Up

Open the billing page to add credits:

```bash theme={null}
bunx vargai topup
```

## Project Commands

### Initialize Project

Set up a new varg project:

```bash theme={null}
bunx vargai init
```

This runs login (if needed), installs the varg-ai Agent Skill, creates `hello.tsx`, output directories, and `.gitignore`.

### Create Hello World

Generate the hello world starter:

```bash theme={null}
bunx vargai hello
```

Creates `hello.tsx` with a minimal working example.

### Render Video

Render a TSX file to video:

```bash theme={null}
bunx vargai render <file.tsx>
```

Options:

| Flag            | Description                        | Default            |
| --------------- | ---------------------------------- | ------------------ |
| `--output, -o`  | Output file path                   | `output/video.mp4` |
| `--preview`     | Free preview with placeholders     | -                  |
| `--verbose, -v` | Show detailed progress             | -                  |
| `--no-cache`    | Skip cache (regenerate everything) | -                  |
| `--cache`       | Cache directory                    | `.cache/ai`        |

Examples:

```bash theme={null}
bunx vargai render video.tsx --preview      # Free preview
bunx vargai render video.tsx --verbose      # Full render
bunx vargai render video.tsx -o output/my-video.mp4 -v
bunx vargai render video.tsx --no-cache     # Force regeneration

# Background rendering
nohup bunx vargai render video.tsx --verbose > output/render.log 2>&1 &
```

## Generation Commands

Run individual generation actions:

```bash theme={null}
bunx vargai run <action> [options]
```

### Generate Image

```bash theme={null}
bunx vargai run image --prompt "sunset over mountains"
bunx vargai run image --prompt "cute cat" --model nano-banana-pro --aspect-ratio 16:9
```

| Flag                 | Description       | Default           |
| -------------------- | ----------------- | ----------------- |
| `--prompt, -p`       | Image description | required          |
| `--model, -m`        | Model name        | `nano-banana-pro` |
| `--aspect-ratio, -a` | Output ratio      | `1:1`             |
| `--output, -o`       | Output path       | -                 |

### Generate Video

```bash theme={null}
bunx vargai run video --prompt "ocean waves" --duration 5
bunx vargai run video --prompt "cat waving" --image media/cat.jpg --duration 5
```

| Flag             | Description                  | Default    |
| ---------------- | ---------------------------- | ---------- |
| `--prompt, -p`   | Video description            | required   |
| `--image, -i`    | Input image (image-to-video) | -          |
| `--duration, -d` | Duration in seconds          | `5`        |
| `--model, -m`    | Model name                   | `kling-v3` |
| `--output, -o`   | Output path                  | -          |

### Generate Voice

```bash theme={null}
bunx vargai run voice --text "Hello world" --voice rachel
```

| Flag           | Description   | Default  |
| -------------- | ------------- | -------- |
| `--text, -t`   | Text to speak | required |
| `--voice, -v`  | Voice name    | `rachel` |
| `--model, -m`  | TTS model     | -        |
| `--output, -o` | Output path   | -        |

### Generate Music

```bash theme={null}
bunx vargai run music --prompt "upbeat electronic" --duration 30
```

### Transcribe Audio

```bash theme={null}
bunx vargai run transcribe audio.mp3
```

### List Actions

```bash theme={null}
bunx vargai list
```

## Environment

The CLI reads `VARG_API_KEY` from:

1. Environment variable: `export VARG_API_KEY=varg_xxx`
2. `.env` file: `VARG_API_KEY=varg_xxx`
3. Global credentials: `~/.varg/credentials`

## Output Formats

### Default

```
[image] Generating with nano-banana-pro...
[image] Generated: output/image.png
```

### Quiet (`--quiet`)

```
output/image.png
```

### JSON (`--json`)

```json theme={null}
{
  "url": "output/image.png",
  "model": "nano-banana-pro",
  "prompt": "sunset over mountains",
  "duration_ms": 2340
}
```