Command line

folio [FOLDER] [--port N] [--socket PATH]... [--verbose]
folio check [FOLDER] [--port N | --socket PATH]
folio lsp [FOLDER]
folio mcp [FOLIO | --port N | --socket PATH]
folio [COMMAND] --help
folio --version

Argument	Default
FOLDER	the current directory	The folder to serve, check or edit. A folder named mcp, check or lsp is given as ./mcp, ./check or ./lsp
FOLIO	none	For mcp, the Folio to read: its address on this machine - localhost:8641, http://localhost:8641/, any page's address on it - or the path of a unix socket it serves on, as --port or --socket would give it. An empty one, as the Claude Code plugin passes while its Folio setting is unset, is none. A folder, an address on another host or one not over http is refused
--port N, --port=N, -p N	8640	The port, 1 to 65535. Serving without it, Folio moves past a taken 8640 to the next free port above it - unless a Folio on a port it passes already serves the folder, which Folio names before it exits 1. A port given is never left for another. check and mcp given no port, socket or Folio ask the Folio serving their folder, wherever it serves - see below
--socket PATH	none	Also serve on a unix socket at that path - given again, on several, which only its owner may open - for a client that cannot reach the port, such as a container sharing the folder. A socket left by a Folio no longer running is replaced; the socket goes when Folio stops
--verbose	off	Also print every request and every update sent to a tab
-h, --help		Print the commands, options and examples, or with a command, its arguments, options, exit codes and examples, and exit 0
--version		Print Folio's version and exit 0

Folio prints Folio serving <folder>, then at http://localhost:<port>/ - followed by - port 8640 is taken or - ports 8640 to <port - 1> are taken when it moved past them - and and on <socket> for each --socket. While it reads the folder it shows a progress line, then a line saying how many documents it read and how long it took. After that it prints a line for each page a tab opens, naming it - a tab that reconnects does not open its page again - and one for each problem: a request answered with an error, with the reason when Folio failed to answer it, an address with nothing behind it, a file it cannot index or store. Each line after the summary, the progress line aside, is timed in UTC. On a terminal, problems are coloured by severity; printed to a pipe or to a service's journal, the same lines carry no colour and no progress line.

folio check prints the folder's health, one problem a line in aligned columns - path:line, then the severity error, warning for a rule's warning, or - for any other problem, then the kind and what is wrong - and a count, each severity and the count coloured on a terminal, and exits 1 when any problem is an error: a rule's violation unless the rule is a warning, or a problem of a kind of check a health entry declares an error. Otherwise it exits 0, whatever else is listed; when no health can be worked out at all, it says why and exits 2. It asks the Folio serving that folder when one answers - on the port or socket given, or without either wherever a Folio serving exactly that folder serves, else 8640 - and otherwise works the health out itself from Folio's stored state, which a later check or start reuses: a check of a folder whose files have not changed since takes seconds. Meanwhile, on a terminal, one live line says what it is doing - the documents read so far, then the documents checked out of those it checks again, or, waiting on a running Folio, whether that Folio is still reading the folder or checking health - and is gone before the problems print; printed to a pipe, there is none.

folio lsp is a language server on standard input and output, for an editor to start as a command; see Editors. On standard error, which an editor keeps in its log of the server, it prints folio lsp serving <folder> and on standard input and output, the live line folio check shows while it reads the folder - on a terminal only - then ready: read <n> documents in <s> s, and a timed line when an editor connects and when it leaves, the editor named as it names itself.

folio mcp is an MCP server on standard input and output whose tools read the Folio its argument names, or the one running on the port or socket given, for an agent's MCP client to start as a command. Given none, they read the Folio serving the agent's folder, looked up again at every tool call: the nearest folder at or above one of the roots the agent's client names - the first root that leads to one - or, with no roots, at or above the folder folio mcp started in; when no Folio serves any of them, the Folio on 8640. It speaks MCP 2025-06-18, and 2025-03-26 or 2024-11-05 to a client asking for one of them, whose messages for its tools are alike; asked for any other version, it answers with 2025-06-18. A line that is not JSON, not a message object, or a request lacking jsonrpc: "2.0", a method, or params that are an object, is answered with a JSON-RPC error; a notification or a reply gets no answer, a batch the replies to its requests, and the server stays up. On standard error it prints folio mcp reading the Folio at <address> - or on <socket>, or serving the agent's folder given neither, followed by found the Folio at <address> or no Folio serves <folders> or a folder above it; reading the Folio at http://localhost:8640/, again whenever that changes - then whether a Folio answers there and which folder it serves - with none, it says so and keeps running, so a Folio started later is read, and each tool call answers that no Folio answers there, that the user starts one or starts folio mcp to match one - or, when a Claude Code plugin started folio mcp, sets the plugin's Folio setting to one - and that the agent starts no process - a timed line when an agent connects and when it leaves, named as it names itself, and, at a tool call, a line when that Folio stopped answering, answers again or serves another folder. A message folio mcp fails to answer for a reason of its own gets a JSON-RPC internal error saying only that folio mcp failed and that the reason is on its standard error, where a timed line names the request and the reason. Standard output carries the protocol alone, for both commands. The Claude Code plugin in Folio's repository runs npx --yes @jakubro/folio@<version> mcp <setting>, its own release and its Folio setting, from the folder Claude Code is opened in.

Error	Exit status
One line naming what is wrong, then the usage: more than one folder or Folio, a folder given to mcp or an address not on this machine or not over http, an invalid port, an unknown option, one missing its value or a value given to one that takes none, --verbose given to a command other than serving, an empty socket path, more than one socket or a port and a socket together given to check or mcp, a Folio given to mcp with a port or a socket	2
Not a folder: <path>, for a folder that does not exist or is not a folder	2
Port N is already in use., or a socket path in use or holding something else	1
<folder> is already served at http://localhost:<port>/, serving without --port when a Folio on 8640 or a taken port after it serves the folder; No port is free from 8640 up.	1