fswatch

NAME

fswatch — watch VFS paths for file changes and deliver events as licks

SYNOPSIS

fswatch create --path <path> --pattern <glob> [--scoop <name>] [--name <name>]
fswatch list
fswatch delete <id>

DESCRIPTION

fswatch monitors VFS paths for file changes and delivers change events as lick events. When a file matching the given pattern is created, modified, or deleted under the watched path, an event is fired. Events are routed to the specified scoop; if no scoop is given, they route to the cone.

SUBCOMMANDS

create

Create a new file watcher.

--path <path>

Base VFS path to watch. Required.
--pattern <glob>

Glob pattern to match filenames against (e.g. *.md, *.ts). Required.
--scoop <name>

Route change events to this scoop as lick events. If omitted, events route to the cone.
--name <name>

Human-readable name for the watcher. Defaults to <pattern> in <path>.

list

List all active file watchers, showing their ID, name, path, pattern, target scoop, and creation time.

delete <id>

Remove an active watcher by its ID (e.g. fsw-1). Stops monitoring immediately.

EVENT FORMAT

When a change is detected, fswatch delivers a lick event with the following structure:

{
  "type": "fswatch",
  "fswatchId": "fsw-1",
  "fswatchName": "*.md in /workspace",
  "targetScoop": "doc-watcher",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "changes": [
    { "type": "create", "path": "/workspace/notes/new-file.md" },
    { "type": "modify", "path": "/workspace/README.md" },
    { "type": "delete", "path": "/workspace/old.md" }
  ]
}

Each entry in changes contains:

type

One of create, modify, or delete.
path

Absolute VFS path of the affected file.

PATTERNS

The --pattern flag accepts glob syntax matched against the filename (not the full path):

*.md — all Markdown files
*.ts — all TypeScript files
*.bsh — all bash script files
* — all files

EXAMPLES

# Watch for markdown changes, route to a scoop
fswatch create --path /workspace --pattern "*.md" --scoop doc-watcher --name md-changes

# Watch TypeScript files, events go to cone
fswatch create --path /workspace/src --pattern "*.ts"

# List active watchers
fswatch list

# Remove a watcher
fswatch delete fsw-1