Global flags

Six flags are declared once on lemonfiber itself and inherited by every subcommand. You may type them before the subcommand or after it, and they mean the same thing either way.

Flag	What it does
--json	Prints machine-readable output
--dry-run	Says what would happen, and changes nothing
--force	Takes the stack from a run that claimed it and did not give it back
--stack-dir <PATH>	Operates a stack directory of your own instead of the built-in one
--config-dir <PATH>	Keeps lemonfiber’s own configuration under a directory of your own
--data-dir <PATH>	Keeps lemonfiber’s own data under a directory of your own

lemonfiber --help and lemonfiber -h print help, and lemonfiber --version or -V prints the binary’s version. Subcommands take -h and --help; the short -V belongs to the top-level command only.

--json

Every answer has a machine-readable form, and it is the same shape whichever command produced it: an envelope carrying api_version, kind and data. A failure is an envelope too — it goes to the error stream rather than into the answer, so a script reading standard output never has to tell an answer from an apology.

Machine-readable output is a stable interface, not a convenience. Its shape is described in the envelope and versioned separately from the binary, which is the two version numbers.

Two things behave differently under --json. Log streams emit one envelope per line, because a stream has no last element to close a document with. And the plain-language footnote a human report prints underneath itself is left off entirely: it is prose for a person, and appending it to a machine-readable answer would corrupt the one thing that answer exists to be.

--dry-run

A rehearsal. The run says what it would do, prints the exact underlying invocation, and writes nothing — including nothing to the records lemonfiber keeps about itself, such as which words it has already explained to you.

Use it before anything that changes shape: up, down, switch, seed, restore. It is also the honest way to read what a command is actually going to ask Docker for, which is the point of it being there at all.

--force

One lifecycle operation runs against a stack at a time. An operation claims the stack before it starts and gives it back when it ends, so down typed in one terminal cannot land in the middle of up in another and leave the stack in a state neither command asked for.

A refusal names the run that already holds the claim: which process, and how long it has been going. Nothing checks whether that process is still alive, so a run that was killed leaves the stack claimed until somebody says --force. Reach for it when the report tells you the holding run started hours ago and you know it is gone. A rehearsal claims nothing, so --dry-run works whether or not a real run is in flight.

--stack-dir <PATH>

Operates a stack directory of your own instead of the one embedded in the binary. The directory needs a stack.toml beside a compose.yml, and the manifest is validated before anything runs — every violation reported in one pass, each naming its location, rather than one per attempt.

This is the escape hatch that makes a fork possible without a lemonfiber release. What the manifest has to contain is the stack manifest contract, and what to do when lemonfiber refuses one is the stack manifest.

--config-dir <PATH> and --data-dir <PATH>

Where lemonfiber keeps its own two directories — the settings file and journal it writes, and the data it keeps about itself. Each defaults to the conventional place for the platform, and each can be named on its own.

Neither is the data location your library goes to. That is a setting, written by lemonfiber config set and read by the stack; these two are lemonfiber’s own housekeeping and nothing the services ever see.

Naming both is the one case where the platform is not consulted at all, and that is deliberate rather than incidental: a machine whose home directory cannot be resolved is exactly the machine somebody reaches for these flags on, and falling back would answer it with the absence the flags were given to fill.

Flags that only look global

Several flags recur across commands without being inherited, and they are worth knowing apart because their meaning is not identical everywhere.

Flag	Where it appears	What it means there
--yes	doctor, down, setup	Proceed without the prompt this command would otherwise raise
--confirm	companion certificate, config set, credentials, forget, migrate adopt, migrate beside, migrate import, quality set, quality upgrade, support, uninstall, update stack	Say yes to the consequence this command has just named
--offer	credentials revoke, downloads, downloads pause, downloads resume, migrate replace, plugin install, plugin prove, plugin remove, plugin run, plugin update, remove, reset, restart, settings clear, settings set, space, stop-seeding, update stack, wiring fill	Answer the offer a reading of this command printed, by the name it printed
--service	backup, down, up, update stack	Act on the named service rather than on everything the command would otherwise touch

A command that would throw work away or spend a lot of bandwidth states the cost first and does nothing until it is answered: reset names every edit it would revert and prints a name for that offer, which --offer answers, and quality upgrade states what re-downloading the back catalogue comes to before --confirm. support splits the two halves apart — a bare run collects, redacts and tells you what the bundle would hold, --write produces it, and --confirm is only ever about the settings --reveal names, because a flag that publishes a credential is not one to honour because it turned up on a command line somebody copied.

What the environment decides

These environment variables are read, all at the edge of the program rather than threaded through it.

Variable	Effect
LC_ALL, LC_CTYPE, LANG	Read in that order. A locale naming a non-UTF-8 character set, or C/POSIX, folds output to ASCII. A locale that is simply unset is not taken as a claim either way
NO_COLOR	The scrollable log viewer adds no colour. The convention is the variable’s presence, so NO_COLOR=0 refuses colour like any other value
DOCKER_HOST, DOCKER_CONTEXT, DOCKER_TLS_VERIFY, DOCKER_CONFIG	Which engine a run is pointed at, read the way Docker’s own command line reads them

Everything else is a setting rather than a variable, kept where lemonfiber config set writes and readable with lemonfiber config show. The plain-language explanations are one of those: they are on unless LEMONFIBER_EXPLANATIONS is set to off, false, no, 0 or nothing at all.

Where to go next

Every command lists what these flags apply to, and the complete command reference has the per-command flags in full. For what --json actually emits, start with the envelope and then the kinds.