---
description: Use when working with the vf CLI (VibeFlare command-line client) — running chat/completions from the shell, piping, scripting, login/setup, config env vars (VIBEFLARE_URL/KEY/MODEL), or debugging vf usage errors. Also covers VibeFlare REST API integration, API keys, and SDK/fetch embedding (references/api.md). Triggers on "vf", "vibeflare", "vf login", "vf not working", "vibeflare API".
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
---


# vf — VibeFlare CLI

Thin proxy over VibeFlare OpenAI-compat API. Defaults: max 256 tokens, no streaming, no JSON unless `--json`.

REST API integration / API keys / SDK-fetch embedding → `references/api.md`.

## Setup

```bash
vf login [insert here]   # prompts for API key, writes ~/.config/vibeflare/config.json
```

Server base URL: `[insert here]` (prod).

Config precedence (env beats file):
```
VIBEFLARE_URL / VIBEFLARE_BASE_URL  — server base URL → [insert here]
VIBEFLARE_KEY                     — API key (vf-<40hex>)
VIBEFLARE_MODEL                   — default model id
```

vibeflare-image tests/apps: must export `VIBEFLARE_BASE_URL=[insert here]`; absence → `VIBEFLARE_BASE_URL not set` skip.

Config file: `~/.config/vibeflare/config.json` (chmod 600)

## Global flags (all commands)

| Flag | Alias | Effect |
|------|-------|--------|
| `--json` | | print raw API response JSON |
| `--max-tokens N` | | max output tokens (default 256) |
| `--head N` | | byte-truncate stdout to N bytes |
| `-q` / `--quiet` | | suppress stderr meta/errors |

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | ok |
| 1 | error |
| 2 | quota exceeded (10k neurons/day) |
| 3 | auth failure (401/403) |

---

## Commands

### `chat` — text generation

```bash
vf chat "message" [flags]
```

| Flag | Alias | Notes |
|------|-------|-------|
| `-m <model>` | `--model` | default: `@cf/meta/llama-3.1-8b-instruct` |
| `-s <text>` | `--system` | inline system prompt |
| `-t <float>` | `--temp` | temperature 0–2 |
| `--cache` | | enable server-side response cache |
| `--system-id <id>` | | server prompt-cache id (replaces `-s`) |
| `--compress-history` | | summarize history >20 msgs before sending |
| `--max-tokens N` | | max output tokens (default 256) |
| `--head N` | | byte-truncate reply |
| `--json` | | full completion JSON |

**`--cache`**: same prompts → save neurons. D1 response_cache, TTL 7d.

**`--compress-history`**: long sessions. >20 msgs → summarize older via llama, keep last 6 verbatim. Fallback if summarize fails.

**`--system-id`**: server-cached sys prompt. Replaces `--system`; resolves id → stored prompt, saves tokens on repeated calls.

Examples:
```bash
vf chat "summarize this" -s "you are terse"
vf chat "next step?" --compress-history --cache
vf chat "translate" --max-tokens 512 --json
echo "what is 2+2" | xargs vf chat
```

---

### `embed` — vector embeddings

```bash
vf embed "text to embed" [-m model]
```

Default model: `@cf/baai/bge-small-en-v1.5`  
Default output: comma-separated float vector  
`--json`: full API response with metadata

```bash
vf embed "hello world" | tr ',' '\n' | wc -l   # vector dims
```

---

### `stt` — speech to text

```bash
vf stt <audio-file> [-m model]
```

Default: `@cf/openai/whisper`. Input: WAV + audio formats. Output: transcription text. `--json`: full response object.

```bash
vf stt recording.wav
vf stt meeting.wav --json | jq .text
```

---

### `tts` — text to speech

```bash
vf tts "text" [-m model] [-o file] [-v voice]
```

Default: `@cf/myshell-ai/melotts`. Output: audio bytes to stdout. `-o <path>`: write file (byte count to stderr). `-o -`: explicit stdout. `-v <voice>`: voice id (default `alloy`).

```bash
vf tts "hello world" -o hello.mp3
vf tts "read this aloud" -v nova | aplay
```

---

### `img` — image generation

```bash
vf img "prompt" [-m model] [-o file] [-n N]
```

Default model: `@cf/...` (text-to-image task model)  
`-o <file>`: save to file  
`-n N`: number of images  
`--json`: full response (b64_json or url depending on size)

Small (<100KB): base64 inline. Large: R2, URL in response (14d TTL).

```bash
vf img "a cat on a keyboard" -o cat.png
vf img "logo" -n 4 --json | jq '.data[].url'
```

---

### `vision` — visual question answering

```bash
vf vision <image-path-or-url> "question" [-m model]
```

Default: `@cf/llava-hf/llava-1.5-7b-hf`. Image: local path or http/https URL. Local files → base64 inline.

```bash
vf vision screenshot.png "what error does this show?"
vf vision https://example.com/chart.png "what is the trend?"
vf vision diagram.jpg "list all components" --max-tokens 512
```

---

### `models` — list available models

```bash
vf models [task-filter]
```

No filter: all from D1 `models` table. Filter: matching task. `--json`: full objects.

```bash
vf models                      # all
vf models text-generation      # filter by task
vf models --json | jq '.[].id'
```

Common task values: `text-generation`, `text-to-image`, `speech-recognition`, `text-to-speech`, `feature-extraction` (embeddings)

---

### `usage` — quota status

```bash
vf usage [--json]
```

Default output: `<used>/<limit> <pct>%` (e.g. `4231/10000 42%`)  
`--json`: full quota object from server

Quota: 10,000 neurons/day. Warn 90%, cutoff 100%. Resets 00:00 UTC.

```bash
vf usage
# 4231/10000 42%
```

---

### `keys` — API key management

```bash
vf keys ls
vf keys new <label> [--admin]
vf keys rm <prefix>
```

`ls`: prefix, label, last-used date. `new`: prints full key once (unretrievable). `rm <prefix>`: delete by prefix. `--admin`: admin scope. `--json`: full object from ls/new.

```bash
vf keys ls
vf keys new "ci-pipeline"
vf keys new "admin-key" --admin
vf keys rm vf-a1b2c3
```

---

### `cache` — response cache management

```bash
vf cache ls
vf cache clear
```

`ls`: hash prefix, model, hit count. `clear`: delete all, print count. `--json`: full objects. Created on `--cache` in `chat`. TTL 7d, sha256 key.

```bash
vf cache ls
vf cache clear
```

---

### `batch` — JSONL pipe processing

```bash
echo '{"kind":"chat","messages":[{"role":"user","content":"hi"}]}' | vf batch
cat prompts.jsonl | vf batch > results.jsonl
```

JSONL stdin → JSONL stdout. Sequential.

Input schema:
```json
{
  "kind": "chat" | "embed",
  "id": "optional-correlation-id",
  "model": "optional-model-id",
  "messages": [...],          // for kind=chat
  "input": "string",          // for kind=embed
  "max_tokens": 256,
  "system_id": "optional",
  "cache": false
}
```

Output schema:
```json
{"id": "...", "result": {...}}
{"id": "...", "error": "message", "statusCode": 429}
```

Use: bulk classify, batch embed, parallel eval.

---

## Piping and scripting patterns

```bash
# pipe file content into chat
cat README.md | xargs -d '\n' -I{} vf chat "summarize: {}"

# check quota before expensive batch
vf usage -q && cat jobs.jsonl | vf batch

# embed and store
vf embed "$(cat doc.txt)" -q > vector.txt

# TTS from clipboard
xclip -o | xargs -I{} vf tts "{}" -o out.mp3

# vision on screenshot
scrot /tmp/ss.png && vf vision /tmp/ss.png "describe the UI"

# list only text-generation models, pick one
MODEL=$(vf models text-generation | head -1)
vf chat "hello" -m "$MODEL"
```

## When to use each command

| Task | Command | Notes |
|------|---------|-------|
| Quick question | `chat` | 256 tok usually enough |
| Long answer needed | `chat --max-tokens 2048` | bump tokens |
| Repeated same prompt | `chat --cache` | save neurons |
| Long conversation | `chat --compress-history` | >20 msg sessions |
| Classify/embed text | `embed` | vector DB or cosine sim |
| Transcribe audio | `stt` | WAV/audio files |
| Generate audio | `tts` | pipe to player or save |
| Generate images | `img` | prompt → PNG |
| Analyze screenshot/image | `vision` | local file or URL |
| See what models exist | `models [task]` | before choosing `-m` |
| Check quota remaining | `usage` | before big batch |
| Manage API keys | `keys` | ls/new/rm |
| Inspect/clear cache | `cache` | debug hits or free space |
| Bulk AI jobs | `batch` | JSONL stdin→stdout pipeline |

## Build / install

```bash
cd apps/cli
pnpm cli:build          # from repo root: builds vf binary to dist/vf
# or:
bun build src/index.ts --outfile dist/vf --compile
```

Binary: `dist/vf` — copy to PATH.

$ARGUMENTS

Bundled assets for this command live in `/home/user/.claude/command-assets/vibeflare/`. Reference them BY ABSOLUTE PATH — any relative path in the text above resolves there.