CLI flags
The fslite binary takes a small set of global flags that select
where to connect and which named filesystem/workspace to
target, plus three subcommands that manage the local registry and
context. Everything else is a
verb caught by fslite-command's parser.
The clap definitions live in
crates/fslite-cli/src/cli.rs (opens in a new tab).
Global flags
| Flag | Purpose |
|---|---|
--db <path> | Local mode: open this SQLite database file (creating if absent). Mutually exclusive with --memory/--server/--filesystem. |
--memory | Local mode: a private in-memory database (lost on exit). Useful for scripting and tests. |
--server <url> | Remote mode: target a running fslite-server. Pair with --token. |
--token <token> | Bearer token for remote mode. Defaults to $FSLITE_TOKEN (env var). On Linux, prefer the env var — argv is world-readable via /proc/<pid>/cmdline and lands in shell history. |
--filesystem <name> | Use a registered filesystem by name, overriding the persisted context for this invocation only. Mutually exclusive with --db/--memory/--server. |
--workspace <id-or-name> | The target workspace: a raw WorkspaceId, or (when --filesystem <name> matches) the name registered against that filesystem. |
--create-workspace | Create a new workspace directly in the already-selected database, print its raw id, and exit. Bypasses the registry; prefer fslite create for the named-registry workflow. |
--repl | Read commands from stdin, one per line, until EOF or exit/quit. |
--json | Render every output as JSON instead of human-readable text. Stacks with verbs. |
Precedence
- Explicit mode flag (
--db/--memory/--server) wins over everything. - Explicit
--filesystem <name>wins over the persisted context. - Otherwise, the persisted context (
fslite usewritescontext.json) is used; absent that, the command errors out with a "no command given (or no target configured)" message.
--filesystem <name> does not persist — running it doesn't
change context.json. Only fslite use does.
Subcommands
fslite create
fslite create <name> -f <file> [-w <workspace-name>]Creates a new SQLite database file at -f <file>, registers it as
<name>, and (optionally) creates + registers a starter workspace
named <workspace-name> inside it. The database file must not already
exist.
fslite delete
fslite delete <name> [-y]Permanently deletes the named filesystem's database file and forgets
the registration (and all of its workspaces) from the registry. -y
skips the interactive confirmation prompt.
fslite use
fslite use <name> -w <workspace-name>Sets the default filesystem + workspace used by verb invocations that
omit --db/--memory/--server/--filesystem/--workspace.
Writes context.json under FSLITE_CONFIG_DIR.
fslite help
fslite help [<verb>]Bypasses the verb parser entirely. With no argument, lists every verb
with a one-line summary. With an argument, prints the verb's summary
plus every flag it accepts. Exits 2 on an unknown verb.
For the complete verb table, see CLI verbs.