Local workspace CLI

A VizChat workspace has a shape on disk. The vizchat command — shipped in the same package as vizchat-widget — is what lets you and your local tools work with that shape directly.

npm install -g @vizchat/widget-scripts
vizchat --help

What a workspace looks like on disk

~/VizChat/Q3 report/
├─ Q3 report/
│  ├─ quarterly.stb        ← the real file; edit it with anything
│  └─ figures.pdf
├─ .vizchatignore           gitignore syntax; never synced
└─ .vizchat/
   ├─ manifest.json         the sync baseline (≈ Git's HEAD)
   ├─ records.json          per-document metadata, keyed by ref
   ├─ derived/<ref>/        derived data — downloaded, read-only
   │  ├─ manifest.json      what this folder holds, byte-for-byte as in the cloud
   │  ├─ text.md            extracted text from a PDF or image — plain text, greppable
   │  ├─ parse.json         outline and page regions
   │  ├─ listing.md         what's inside an archive
   │  └─ tts/**             narration audio
   └─ local/                private to this machine, never packaged

Your files stay where you put them, under the names you gave them. Everything VizChat needs to keep them in sync lives under .vizchat/.

The commands

sync, ls, ref and check find the workspace root by walking up from the current directory, so they work from any subfolder. Pass --root <dir> to be explicit.

Every command prints one line of JSON on stdout as its last line; explanations go to stderr. Scripts and agents can read the JSON without parsing prose.

If the server no longer supports your version of the CLI, commands stop with CLIENT_OUTDATED and print the command to upgrade; nothing on disk is touched.

Working with an AI coding assistant

An assistant with ordinary file tools can already read and write .stb and .md files, create folders and move things around. Three things it cannot get from the filesystem alone:

Searching PDF text. The extracted text of a PDF lives in .vizchat/derived/<ref>/text.md. Most search tools skip dot-directories by default, so ask for --hidden:

rg --hidden --glob '!.vizchat/local/**' "revenue"

A hit inside text.md tells you the ref (it is the directory name); vizchat ls maps it back to a filename.

Writing a reference to a file. Widgets refer to documents by ref, never by path — so that renaming or moving a file never breaks a reference. Get the ref first:

vizchat ref "Q3 report/figures.pdf"

Checking before you push. vizchat check reports anything that would fail to sync: a reference to a document that isn't here, a reserved name, a file that isn't in the manifest. It also lists modified files — those are simply your unpushed edits, not problems.

Syncing

vizchat sync reconciles this folder with your cloud workspace: what changed in the cloud comes down, what changed locally goes up.

Before the first run, look at what it intends to do:

vizchat sync --dry-run

It lists every change it would make and writes nothing. Once that looks right, run vizchat sync.

Derived data only comes down. Extracted text, archive listings and narration audio are made in the cloud and downloaded into .vizchat/derived/ whenever they change there — only the files that changed, with manifest.json written last. Treat that folder as read-only: sync never uploads it, and anything you edit there is replaced the next time the cloud copy changes (vizchat check reports it in the meantime).

Add --watch to keep it running: it syncs immediately when you change something locally, and checks back with the cloud on a timer even when you don't — changes made on another machine only arrive that way. Ctrl-C to stop.

When it stops and asks

Deleting is the only thing a sync can do that loses work, so there are two gates:

• Too many files would be deleted at once (by count or by share of the workspace): nothing is deleted, and you get the list first. An unmounted external drive or a folder you moved elsewhere both look exactly like "the user deleted everything". Re-run with --yes once the list looks right.
• You have been offline longer than the trash retention window: the cloud can no longer tell you whether those files were deleted or whether a sync went wrong. They are flagged for confirmation rather than deleted.

When both sides changed the same file

Text files keep both versions: the cloud's stays where it was, and yours is saved as <name>.conflict-<time>-<machine>.<ext> and pushed to the cloud too — so you still have it after switching machines.

Binary files (PDFs, images, audio, video) are not merged: your local copy becomes the new version, and the cloud's previous one is saved next to it as <name>.remote-<time>.<ext> for you to choose between.

What does not sync

Dot files are skipped by default. To exclude more, write a .vizchatignore (gitignore syntax) at the workspace root — unpack writes a default one for you. Beyond that, these are listed as "not synced" with a reason and do not fail the run: paths with reserved names, files over the per-file size limit, and new files while your storage is full.

What "stale" means

A PDF's extracted text and page regions are computed from a specific version of the file. Replace the PDF and they no longer match. vizchat check reports those as stale: the text is usually still worth reading, but page highlights would land in the wrong place, so they are dropped until the file is parsed again.

Line endings

Text files keep their line endings and byte-order mark: VizChat records which ones a file uses and writes them back the same way on every machine. Content is hashed as if it used LF without a BOM, so an editor that switches the endings doesn't make VizChat think every line changed — the switch itself is still synced, so other machines end up with the same bytes.