ScriptWeaver

System & files

ScriptWeaver reaches the operating system through the global sw object: sw.fs (files), sw.sys (processes, paths, environment), and sw.app (application lifecycle). Dialogs live under sw.dialog, and HTTP is the standard global fetch.

Files — sw.fs

Synchronous, text-oriented file operations. Each throws a JavaScript error on failure, so wrap calls that might fail in try / catch.

sw.fs.writeFile('/tmp/notes.txt', 'hello\nworld');
const text = sw.fs.readFile('/tmp/notes.txt');

if (sw.fs.exists('/tmp/notes.txt')) {
  /* … */
}
Call Returns Notes
readFile(path) string Whole-file contents.
writeFile(path, content) — Creates or overwrites.
exists(path) boolean
list(dir) string[] Entry names in dir.
stat(path) object { name, isDir, isFile, size, mtime }.
mkdir(path) — Creates the path, including parents.
remove(path) — Deletes a file or empty directory.

sw.fs is the real filesystem. It can't read files bundled inside a packaged .zip app — those live in a virtual filesystem. See Packaging apps for how to read bundled assets.

Processes, paths & environment — sw.sys

Run a program. sw.sys.exec returns a Promise resolving to { stdout, stderr, exitCode }; the options object accepts cwd and env:

sw.sys.exec('git', ['status', '--short'], { cwd: project }).then((r) => {
  console.log(r.stdout, r.exitCode);
});

Open something in its default app — a URL, file, or folder:

sw.sys.open('https://scriptweaver.dev');
sw.sys.open(downloadPath);

Standard locations. sw.sys.paths is an object of OS directories:

sw.sys.paths.home; // user home
sw.sys.paths.config; // per-user config directory
sw.sys.paths.cache; // per-user cache directory
sw.sys.paths.temp; // temporary directory
sw.sys.paths.exe; // the Player executable's path

Environment variables, and a beep:

sw.sys.env.get('EDITOR'); // string, or undefined
sw.sys.env.set('MY_FLAG', '1');
sw.sys.env.has('HOME'); // boolean
sw.sys.beep(); // a system bell

Application — sw.app

sw.app.quit(); // close the app
sw.app.tclVersion; // e.g. "9.0.3"
sw.app.tkVersion;

Help — sw.openHelp / F1

Pressing F1 anywhere opens documentation in its own window, as a separate Player process — so it never blocks or disturbs the running app. You can also open it yourself, for example from a Help menu:

help.addCommand({ label: 'Documentation', accelerator: 'F1', command: sw.openHelp });

Your app can ship its own manual

If your app bundles a help/ folder (or docs/) with an index.md, F1 opens that — your app's own manual — instead of the ScriptWeaver docs. It works whether your app runs from a .zip bundle or loose from disk (the help folder sits beside your entry script). Write the manual in the same Markdown the viewer renders here; relative links and images resolve against the help folder. Apps that ship no help/ or docs/ fall back to the ScriptWeaver documentation, so F1 always shows something.

help/ is preferred over docs/, so you can keep developer docs in docs/ and the end-user manual your app surfaces on F1 in help/.

You can preview an app's bundled help without launching the app:

scriptweaver --help myapp.zip     # render myapp's help/ (or docs/)
scriptweaver --help ./myapp/      # ... or a project directory
scriptweaver --help               # the ScriptWeaver docs (no target)

Taking over F1

To use F1 for something of your own, replace or clear the global binding:

__native_tcl('bind', 'all', '<F1>', ''); // disable the built-in help key

Next