CLI quickstart

The fslite binary is the easiest way to drive an fslite workspace from a shell. It manages a per-user registry (a friendly name → SQLite database file) and a single context (the registry entry to default to when no explicit target is given), and it runs every verb documented in the CLI verbs reference.

1. Register a filesystem and a starter workspace

fslite create main -f main.db -w primary
# registered "main" → /home/you/projects/main.db
# workspace "primary" inside it: 019fbe44-865f-7222-bcfb-78895800892b

main.db is created as a fresh SQLite database file. The workspace primary is the first occupant; every subsequent operation targets that workspace unless you say otherwise.

2. Set the default context

fslite use main -w primary
# future verb invocations default to (filesystem=main, workspace=primary)

fslite use doesn't create anything — it just writes the named pair into $FSLITE_CONFIG_DIR/context.json (resolved by paths::config_dir; see the registry patterns guide).

3. Run verbs

fslite --json mkdir /docs
# {"created_at_ms":..., "id":"node-...", ...}
 
fslite write /docs/h.md --text=$'# hello\n'
# writes hello.md, returns the new Node's revision
 
fslite cat /docs/h.md
# # hello (printed to stdout, revision printed to stderr)

The verbs follow your shell's argv layout — --text=value, --limit, --recursive, etc. Run fslite help <verb> for a per-verb flag table, or fslite help for the full list.

4. Override the context

Either flag overrides the persisted context for the one invocation:

fslite --filesystem other --workspace prod cat /readme

Precedence (highest to lowest): --db/--memory/--server → --filesystem (with --workspace optional) → persisted context. --filesystem <name> is not persisted — fslite use is what moves the default.

5. Tear down

fslite delete main -y
# removes main.db from disk and forgets it (and its workspaces) from
# the registry

-y skips the confirmation prompt. The database is deleted by default; pass --keep-file if you want to forget the registration without deleting the file.

Advanced

• --server mode — point at a running fslite-server instead of a local database. --token (or FSLITE_TOKEN env var) is required. On Linux, prefer the env var — argv is world-readable via /proc/<pid>/cmdline and lands in shell history.
• --repl — read commands from stdin one per line, until EOF or exit/quit. Useful for poking at a workspace interactively.
• --create-workspace — prints a fresh workspace id to stdout and exits, bypassing the registry. Useful for scripting.

For the complete verb table with one-line summaries and the supported flag list per verb, see the CLI verbs reference.