Val Town CLI Skill | Agent Skills

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

Agent Skills: Val Town CLI

Install this agent skill to your local

Skill Files