System & Secrets

wheels system, wheels secrets, and wheels daemon are three LuCLI-level infrastructure commands grouped together here because you touch them occasionally rather than daily. They all sit below the Wheels module — the wheels binary inherits them directly from LuCLI whether you installed LuCLI standalone or through the Wheels distribution.

You’ll use this for:

• Inspecting where LuCLI stores state on disk and cleaning caches or backups.
• Storing API keys, database passwords, and other credentials in an encrypted local vault.
• Running LuCLI as a long-lived daemon for IDE integration or Language Server Protocol endpoints.

Overview

All three surfaces are utilities rather than inner-loop tools. system answers “where does LuCLI put things and how do I reset that state safely?” secrets answers “how do I hand my scripts an API key without committing it to source control?” daemon answers “how do I keep a Lucee runtime hot across many tool invocations?” You can ignore them completely for day-to-day Wheels work and return when the specific need arises.

wheels system

State introspection and maintenance for LuCLI’s home directory (~/.lucli by default).

Synopsis

synopsis

wheels system <subcommand> [flags]

Calling wheels system without a subcommand prints the help summary and exits.

inspect

Inspect LuCLI-managed state artifacts. Currently supports printing the resolved Lucee CFConfig.json in a readable format.

Synopsis

synopsis

wheels system inspect [flags]

Flags

Flag	Description
--lucee	Print Lucee CFConfig.json in a readable (pretty-printed) format.
--path=<path>	Optional path to .CFConfig.json (defaults to the LuCLI home location, ~/.lucli/lucee-server/context/.CFConfig.json).

Without --lucee, inspect prints its own usage and exits zero.

Example

example

wheels system inspect --lucee

paths

Print the set of directories and files LuCLI resolves under your home directory. This is the first thing to run when you’re unsure where LuCLI put something.

Synopsis

synopsis

wheels system paths [flags]

Flags

Flag	Description
--json	Output as pretty-printed JSON.

Example

example

wheels system paths

Sample output:

sample output

LuCLI resolved paths:
  home: /Users/you/.lucli
  homeSource: default
  serversDir: /Users/you/.lucli/servers
  expressDir: /Users/you/.lucli/express
  depsDir: /Users/you/.lucli/deps
  depsGitCacheDir: /Users/you/.lucli/deps/git-cache
  modulesDir: /Users/you/.lucli/modules
  backupsDir: /Users/you/.lucli/backups
  secretsDir: /Users/you/.lucli/secrets
  secretsStoreFile: /Users/you/.lucli/secrets/local.json
  aiDir: /Users/you/.lucli/ai
  aiSettingsFile: /Users/you/.lucli/ai/settings.json
  aiEndpointsFile: /Users/you/.lucli/ai/settings.json
  aiSkillsFile: /Users/you/.lucli/ai/skills.json
  aiSkillPathsFile: /Users/you/.lucli/ai/skill-paths.json
  settingsFile: /Users/you/.lucli/settings.json

clean

Prune cache and backup artifacts. Runs in dry-run mode by default — no files are deleted unless you pass --force.

Synopsis

synopsis

wheels system clean [flags]

Flags

Flag	Description
--caches	Clean cache targets.
--backups	Clean backup targets.
--all	Clean every known safe target (caches and backups).
-f, --force	Apply deletions (without this, clean only previews).
--older-than=<duration>	Backup retention window when cleaning backups. Accepts 30d, 12h, 90m. Default: 30d.

When you pass no target flags, clean defaults to both caches and backups.

Example

# Preview what would be removed
wheels system clean --all

# Apply it
wheels system clean --all --force

backup

Create, list, verify, prune, and restore archives of LuCLI home. Each backup is a .zip plus an adjacent .sha256 checksum file under backupsDir.

Synopsis

synopsis

wheels system backup <subcommand> [flags]

backup create

Create a new backup archive.

synopsis

wheels system backup create [flags]

Flag	Description
--name=<name>	Optional archive name (.zip appended if missing).
--exclude-caches	Skip cache directories in the archive.
--include-backups	Include the existing backups directory contents (off by default, avoids recursion).
--progress	Print each file as it is added (verbose). Without this flag, a compact progress bar is shown.

backup list

List available backup archives.

synopsis

wheels system backup list [flags]

Flag	Description
--json	Output as pretty-printed JSON.

backup verify

Verify a backup’s SHA-256 checksum.

synopsis

wheels system backup verify [BACKUP] [flags]

Flag	Description
[BACKUP]	Backup name or path (defaults to the latest backup).
--all	Verify every backup archive.

backup prune

Delete old backups by age and retention count. Dry-run by default — pass --force to apply.

synopsis

wheels system backup prune [flags]

Flag	Description
--older-than=<duration>	Age threshold (e.g. 30d, 12h, 90m). Default: 30d.
--keep=<count>	Keep at least this many newest backups regardless of age. Default: 10.
-f, --force	Apply deletions (without this, prune only previews).

backup restore

Restore a backup archive to a destination directory. Dry-run by default and verifies the checksum unless you override.

synopsis

wheels system backup restore [BACKUP] [flags]

Flag	Description
[BACKUP]	Backup name or path (defaults to the latest backup).
-t, --to=<dir>	Restore destination directory. Default: LuCLI home.
-f, --force	Apply the restore (without this, restore only previews).
--skip-verify	Skip the pre-restore checksum verification.

Example

example

# Create a backup excluding caches
wheels system backup create --name=before-upgrade --exclude-caches

# Verify every backup on disk
wheels system backup verify --all

# Preview a prune run
wheels system backup prune --older-than=14d --keep=5

# Apply the prune
wheels system backup prune --older-than=14d --keep=5 --force

wheels secrets

Manage secrets (API keys, database passwords, service tokens) for LuCLI projects. The default provider is a local, passphrase-encrypted JSON store at ~/.lucli/secrets/local.json. Other providers resolved through Lucee’s SecretProviderGet surface are also supported — set them with secrets provider use.

Alias

wheels secret and wheels secrets are the same command.

Synopsis

synopsis

wheels secrets <subcommand> [flags]

init

Initialize the local encrypted secret store. Prompts twice for a passphrase and persists the empty store.

Synopsis

synopsis

wheels secrets init [flags]

Flag	Description
--reset	Re-initialize the store. DANGEROUS — deletes all existing secrets.

set

Store or update a secret under a logical name. The value is read from the terminal without echoing.

Synopsis

synopsis

wheels secrets set NAME [flags]

Flag	Description
--description=<text>	Human-readable description stored alongside the secret.

Only the local provider supports writes from wheels secrets set; other providers return an error telling you to switch with secrets provider use local.

get

Retrieve a secret value. By default, get refuses to print the raw value — you must opt in with --show.

Synopsis

synopsis

wheels secrets get NAME [flags]

Flag	Description
--show	Print the secret value to stdout. Use with care — shells and terminals may log it.

When the selected provider is not local, get --show resolves the value via Lucee’s SecretProviderGet.

list

List stored secrets (names and descriptions only — values are never printed).

Synopsis

synopsis

wheels secrets list

Only supported for the local provider.

rm

Remove a stored secret. Prompts for confirmation unless -f is given.

Synopsis

synopsis

wheels secrets rm NAME [flags]

Flag	Description
-f	Skip the confirmation prompt.

Only supported for the local provider.

provider list / provider use / provider current

Inspect or switch the active secret provider. The selection is persisted in ~/.lucli/settings.json.

Synopsis

synopsis

wheels secrets provider list
wheels secrets provider use NAME
wheels secrets provider current

Security notes

Passphrase source and scope

• The local store is encrypted with the passphrase you supply at init. Lose the passphrase and the stored secrets are unrecoverable — there is no escrow or reset that preserves values.
• You can preset the passphrase out-of-band by setting the LUCLI_SECRETS_PASSPHRASE environment variable. Without that, LuCLI prompts interactively and will refuse to operate if no console is attached.
• LuCLI does not integrate with the macOS Keychain, GNOME Keyring, or Windows Credential Manager directly. Use the provider surface to select a Lucee-level provider if you want OS-integrated storage.
• secrets list never prints values, and secrets get refuses to print raw values without --show. Treat --show as you would printf $SECRET — anything that sees your terminal output sees the secret.

Example

example

# First-time setup
wheels secrets init

# Store a secret
wheels secrets set STRIPE_API_KEY --description="Production Stripe key"

# List stored secrets (names only)
wheels secrets list

# Fetch it when you really mean to see it
wheels secrets get STRIPE_API_KEY --show

wheels daemon

Run LuCLI as a long-lived background process. Useful when something external — an IDE, a test harness, an editor plugin — wants to hand LuCLI a stream of commands without paying JVM startup on every call. Two server modes plus an interactive client mode are supported.

Synopsis

synopsis

wheels daemon [flags]

Flags

Flag	Description
--port=<port>	TCP port to listen on (server modes) or connect to (client mode). Default: 10000.
--lsp	Run in Language Server Protocol mode instead of the default JSON line mode.
--module=<name>	CFML module to dispatch LSP messages to. Default: LuceeLSP. Must exist under ~/.lucli/modules.
--client	Connect to a running daemon as an interactive client instead of starting a server.
--raw	In client mode, print the raw JSON response packet from the daemon instead of just the output field.

The daemon binds to 127.0.0.1 only — it is not reachable from other hosts.

Modes

JSON mode (default). One JSON request per connection. The client sends {"argv":["modules","list"],"id":"<uuid>"}, the daemon runs the equivalent of lucli modules list through its Picocli pipeline, captures stdout/stderr, and replies with {"id":"<uuid>","exitCode":0,"output":"..."}. Single-threaded: one connection at a time.

LSP mode (--lsp). Speaks the Language Server Protocol framing (Content-Length header + JSON body) and dispatches each message to the named CFML module’s main(string message) entry point. Returning a non-empty string from the module sends a reply; returning null (e.g. for LSP notifications) sends nothing. The module must already exist under ~/.lucli/modules — use lucli modules init <name> to scaffold one.

Client mode (--client). Connects to a running daemon on the given port and gives you a lucli> prompt. Each line is tokenized on whitespace into argv and sent as a JSON request. Type exit or quit to disconnect.

Examples

Start the default JSON daemon on the default port:

wheels daemon

Start it on a specific port:

wheels daemon --port=12345

Start an LSP daemon backed by a CFML module:

wheels daemon --lsp --module=LuceeLSP --port=10001

Drive a running daemon interactively from another terminal:

wheels daemon --client --port=12345

Use cases

• IDE integration — an editor plugin hands LuCLI commands to the JSON daemon and parses structured responses instead of shelling out per command.
• Custom Language Server — ship a CFML module that implements LSP methods (initialize, textDocument/didOpen, etc.) and expose it over TCP with --lsp.
• Long-running orchestration — test runners or build scripts that invoke many LuCLI commands back-to-back avoid JVM warmup on every call.

When to use each

Command	Reach for it when…
wheels system	You need to know where LuCLI put a file, free disk space, or roll back a bad upgrade with backup restore.
wheels secrets	You want to store API keys or DB passwords outside of source control and have scripts or Lucee code look them up.
wheels daemon	An IDE, editor plugin, or long-running tool wants to drive LuCLI without paying JVM startup per call.

Related commands

Server wheels server — manage named Lucee server instances. Uses the same home directory that system paths reports.

Configuration lucee.json and environment-layered config for projects.

MCP Integration stdio MCP surface that exposes wheels_* tools to an AI IDE — the structured alternative to the JSON daemon.

CFML Execution wheels cfml, wheels run, and wheels repl — one-off CFML execution outside the Wheels context.