Val Town CLI

The vt CLI manages Val Town projects locally. Key concepts:

•Val: A serverless function/project hosted on Val Town
•HTTP Val: A val that serves HTTP requests (filename must contain "http", e.g., index.http.tsx)
•Branch: Version control within a val (not git branches)

Quick Reference

Task	Command
Create new val	`vt create my-val`
Clone existing	`vt clone username/valName`
Push changes	`vt push`
Pull updates	`vt pull`
Auto-sync	`vt watch`
View in browser	`vt browse`
Stream logs	`vt tail`
Check status	`vt status`
List your vals	`vt list`

Common Workflows

Create and develop a new val

bash

vt create my-api
cd my-api
# Edit files...
vt push
vt browse  # Open in browser

Clone and modify existing val

bash

vt clone username/valName
cd valName
# Edit files...
vt push

Live development with auto-sync

bash

cd my-val
vt watch  # Syncs on every file save

Work on a feature branch

bash

cd my-val
vt checkout -b my-feature
# Make changes...
vt push
vt checkout main

File Naming Conventions

Val Town detects file types by naming patterns:

Pattern	Val Type
`.http.ts`, `.http.tsx`	HTTP endpoint
`*.cron.ts`	Scheduled cron job
`*.email.ts`	Email handler
Other `.ts`/`.tsx` files	Script val

Example: To create an HTTP API, name the file api.http.ts or index.http.tsx.

Command Details

Create

bash

vt create my-val                    # New val in ./my-val
vt create my-val ./existing-folder  # Upload existing files
vt create my-val --private          # Private val
vt create my-val --org-name myorg   # Under an organization

Clone

bash

vt clone                                    # Interactive selection
vt clone username/valName                   # By name
vt clone https://www.val.town/x/user/val    # By URL
vt clone username/valName .                 # Into current directory

Remix

Fork someone else's val:

bash

vt remix std/reactHonoStarter myWebsite
cd myWebsite
vt watch

Branches

bash

vt branch              # List branches
vt checkout main       # Switch branch
vt checkout -b feature # Create new branch
vt branch -D feature   # Delete branch

Logs

bash

vt tail                          # Stream current val's logs
vt tail @user/valName            # Stream specific val
vt tail --print-headers          # Include HTTP headers
vt tail --reverse-logs           # Latest first

Configuration

bash

vt config options                           # List options
vt config set dangerousOperations.confirmation false  # Disable confirmations
vt config ignore                            # Edit global .vtignore

Project Structure

After cloning/creating, a val directory contains:

•.vt/ - Metadata (like .git)
•.vtignore - Files to exclude from sync
•deno.json - Deno LSP configuration
•Source files (.ts, .tsx, etc.)

Tips

•Use vt push --dry-run to preview changes before pushing
•Use vt checkout --dry-run to preview branch switch effects
•HTTP vals require "http" in the filename to be recognized as endpoints
•The vt watch command enables live reloading with the browser companion extension