CLI Reference

Every command, flag, and option for the folio CLI.

folio [OPTIONS] COMMAND [ARGS]

Running folio with no arguments displays the help text.

Global Options

folio --version

It prints the installed version, for example folio 0.1.0.

Commands

folio init

Generate a docs.yaml configuration file for an existing Python project. This is the recommended way to get started.

folio init [DIRECTORY]

Interactive wizard:

When run without --yes, folio init launches an interactive wizard that walks you through configuration:

Interactive terminals use compact inline arrow-key menus for list choices and inline (Y/n) hints for short yes/no choices; press y/n to submit yes/no choices directly. The intro banner includes a sparkle-framed Folio update line that refreshes in place every second while arrow-key prompts are open. Detected project settings are pre-filled from the project scan.

$ folio init

 ████████╗ ██████╗ ██╗     ██╗ ██████╗
 ██╔═════╝██╔═══██╗██║     ██║██╔═══██╗
 █████╗   ██║   ██║██║     ██║██║   ██║
 ██╔══╝   ██║   ██║██║     ██║██║   ██║
 ██║      ╚██████╔╝███████╗██║╚██████╔╝
 ╚═╝       ╚═════╝ ╚══════╝╚═╝ ╚═════╝  v0.1.0

   ⚡Incremental builds skip pages whose sources are unchanged⚡

       ╭───────────────────── 🔎 Detected ─────────────────────╮
       │ 🎯 Target     .                                       │
       │ 📦 Project    my-library 1.2.0                        │
       │ 🧬 Source     src/my_library                           │
       │ 🌐 Repo       https://github.com/org/my-library        │
       │ 🐍 Python     3.12                                    │
       │ 🛠️ Framework  Typer package                           │
       │ ✨ Status     Documentation scaffold not found         │
       ╰───────────────────────────────────────────────────────╯

? 🧭 Docstring style      › - Use arrow-keys. Return to submit.
  Google
  NumPy
› Auto-detect
✔ 🧭 Docstring style      › Auto-detect
? 🎨 Visual preset        › - Use arrow-keys. Return to submit.
› Organic Editorial
  Beacon
  Atlas
  Workshop
✔ 🎨 Visual preset        › Organic Editorial

  ✔ Created docs.yaml
  ✔ Created docs/index.md
  ✔ Created .github/workflows/pages.yml
  Next folio serve

What it does:

1. Checks if docs.yaml already exists. If it does, prints a message and exits without overwriting.
2. Detects the project name and version from pyproject.toml (if present).
3. Detects the GitHub repo URL from git remote origin (if available).
4. Prints created file paths relative to the current shell directory, so folio init tmp/project reports tmp/project/docs.yaml.
5. Detects the Python source directory by checking, in order:
   • src/<package_name>/ (src layout)
   • src/ (generic src directory)
   • <package_name>/ (flat layout)
   • <project_name>/ (flat layout with project name)
6. Displays the detected project settings, pre-fills them, then prompts for docstring style and visual preset (or uses defaults with --yes).
7. Generates a docs.yaml file with the chosen theme preset.
8. Creates a docs/ directory with a starter index.md file if one doesn’t exist.
9. Creates a GitHub Pages workflow at .github/workflows/pages.yml if it does not already exist.

Examples:

# Interactive setup
folio init
 
# Non-interactive with defaults
folio init --yes
 
# Initialize a specific project
folio init /path/to/my-project -y

Exit codes:

folio build

Parse Python source code and documentation files, then generate a static documentation site.

folio build [OPTIONS] [DIRECTORY]

What it does:

1. Loads the config file from the project directory.
2. Parses Python source files and extracts docstrings, class hierarchies, and module structure.
3. Converts Markdown documentation files to MDX.
4. Generates the Nextra site in a .build/ directory.
5. Runs the Next.js build to produce the final output.

Build output uses the same compact terminal rhythm as folio init: a centered Folio banner followed by short status rows for sources, template prep, page generation, link checks, dependencies, export, completion, and the ready output path. Warnings stay attached to their step instead of appearing as raw Python warning traces. During static export, Folio prints the full export log once in a bordered build output panel and also saves it to .build/.folio-build.log.

The incremental cache tracks source file hashes plus config, template, and generator inputs. Changing docs.yaml, Folio’s generator code, or the site template invalidates generated pages even when Python and Markdown sources are unchanged.

Examples:

# Build docs for the current directory
folio build
 
# Build with verbose output
folio build -v
 
# Build a project in a different directory
folio build /path/to/project
 
# Use a custom config file
folio build --config my-docs.yaml
 
# Build and open a local static preview
folio build --open

folio build --open is intentionally blocking after the build: it starts a static preview server and waits until you press Ctrl+C.

Exit codes:

folio serve

Build the documentation and start a local development server with hot reloading. This is the primary command during development.

folio serve [OPTIONS] [DIRECTORY]

What it does:

1. Performs the same build steps as folio build.
2. Starts a Next.js development server on the specified port.
3. File watching: after the dev server starts, Folio watches your Python and Markdown source files for changes. Edits are automatically detected, the affected pages are regenerated, and the browser updates via hot reload.
4. Incremental builds: subsequent serve runs reuse cached dependencies (.build/node_modules/) and skip pnpm install when deps haven’t changed.
5. Keeps the server running until interrupted with Ctrl+C.

The --clean flag forces a full rebuild from scratch, clearing all caches.

Examples:

# Start the dev server
folio serve
 
# Serve on a custom port and open the browser
folio serve --port 8080 --open
 
# Serve a different project with verbose output
folio serve ../my-lib -v -o
 

Exit codes:

folio coverage

Analyze docstring coverage for configured Python source files.

folio coverage [OPTIONS] [DIRECTORY]

Examples:

folio coverage
folio coverage --min 80
folio coverage --verbose

Exit codes:

folio clean

Remove generated build artifacts and output directories.

folio clean [OPTIONS] [DIRECTORY]

What it does:

Removes two directories:

1. .build/ — the intermediate Nextra project used during the build process.
2. The output directory — by default _site/, or whatever output is set to in docs.yaml. The clean command reads this value directly from YAML, so cleanup still works if a configured plugin is missing or broken.

If neither directory exists, it prints “Nothing to clean.”

Examples:

# Clean the current project
folio clean
 
# Clean a specific project
folio clean /path/to/project
 
# Example output:
# Cleaned: .build, _site

Exit codes:

Error Messages

Here are common errors you might encounter and what they mean:

Error: Config file not found: docs.yaml No docs.yaml was found in the project directory. Run folio init to create one, or specify the correct path with --config.

Build failed: ... The build process encountered an error. Run with --verbose for detailed output. Common causes include syntax errors in Python source files, invalid YAML in the config, or missing dependencies.

docs.yaml already exists, skipping. The init command found an existing config file and did not overwrite it. This is informational, not an error.

Typical Workflow

A typical documentation workflow looks like this:

# 1. Initialize (one time)
folio init
 
# 2. Edit docs.yaml to customize settings
 
# 3. Start the dev server while writing docs
folio serve --open
 
# 4. Build for production
folio build
 
# 5. Deploy the _site/ directory to your hosting provider
 
# 6. Clean up build artifacts when needed
folio clean