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

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

Clone and modify existing val

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

Live development with auto-sync

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

Work on a feature branch

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

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

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:

vt remix std/reactHonoStarter myWebsite
cd myWebsite
vt watch

Branches

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

Logs

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

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