CYCLOPTS(1)

📦
version 4.17.0 · 3 versions
, in ubuntu stonking

💖 CYCLOPTS(1) 💖

okay bestie, welcome to the Cyclopts CLI Manual — this is the cyclopts man page and it's lowkey the cutest little command-line tool for running and documenting Cyclopts applications. sit down, grab a boba, let's get into it ✨

🎀 NAME 🎀

cyclopts — the command-line interface for running and documenting Cyclopts applications. that's the whole vibe, no cap.

✨ SYNOPSIS ✨

cyclopts [OPTIONS] COMMAND [ARGUMENTS]

cyclopts run SCRIPT [ARGS...]

cyclopts generate-docs [OPTIONS] SCRIPT [ARGS]

🦋 DESCRIPTION 🦋

so cyclopts is a command-line tool for working with apps built using the Cyclopts Python framework. it lets you dynamically execute CLI applications that are defined in Python scripts, and also generate structured documentation automatically. it's giving two jobs, one icon 💅

Cyclopts is especially useful for developers building CLI tools, because it hands you automatic argument parsing, shell completion, and documentation generation — all derived from your Python type hints. the way that it just... knows your types. obsessed 😭

the two primary workflows are:

  1. Execute a CLI app from a Python script using cyclopts run.
  2. Generate documentation from the same script using cyclopts generate-docs.

💅 OPTIONS 💅

  • -h, --help — show the help message and exit. classic. iconic.
  • --version — display the application version and exit.
  • --install-completion — install shell completion support persistently for the current user.
note bestie: if you installed this via the Debian package, shell completion for bash, zsh, and fish is automatically available system-wide without you needing to run this command at all. slay 💖

👑 COMMANDS 👑

run 🏃‍♀️

cyclopts run SCRIPT [ARGS...]

Run a Cyclopts application from a Python script.

the script may optionally specify the application object using the syntax: script.py:app_object.

all arguments after the script path get passed directly to the loaded application. no middleman, no edits, direct handoff. periodt.

generate-docs 📝

cyclopts generate-docs SCRIPT

Generate documentation for a Cyclopts application. it literally reads your app's structure and writes the docs for you. main character energy fr fr.

  • -o, --output _FILE_ — write output to the specified file instead of stdout.
  • -f, --format _FORMAT_ — specify the output format.

supported formats include: markdown, md, html, htm, rst, rest, restructuredtext.

  • --include-hidden — include hidden commands in the generated documentation. yes, even the secret ones 👀
  • --heading-level _LEVEL_ — set the starting heading level for Markdown output. default is 1.
  • --usage-name _NAME_ — override the application name shown in usage lines.

useful when the runtime command differs from the script name. iykyk.

🌈 EXAMPLES 🌈

Running an application 🏃‍♀️✨

run a Cyclopts app from a Python script:

$ cyclopts run app.py

run specifying the app object:

$ cyclopts run app.py:cli

pass arguments to the application:

$ cyclopts run app.py --help
$ cyclopts run app.py command --option value

Generating documentation 📚💖

generate Markdown documentation:

$ cyclopts generate-docs app.py -o docs.md

generate HTML documentation:

$ cyclopts generate-docs app.py -o docs.html

print documentation to stdout:

$ cyclopts generate-docs app.py

include hidden commands:

$ cyclopts generate-docs app.py --include-hidden

customize heading level:

$ cyclopts generate-docs app.py --heading-level 2

🫶 NOTES 🫶

ok real talk for a sec because this one matters.

cyclopts run executes Python scripts dynamically, so make sure all the dependencies required by the script are installed in the current environment. otherwise it's gonna be a whole mess, bestie, and not the cute kind 😭

when using the script.py:app_object notation, the specified object must be a valid Cyclopts application instance. no impostors allowed 💀

the documentation generated by cyclopts generate-docs is derived directly from the application's structure, which means your CLI documentation stays consistent with the source code. the way it just stays in sync... no cap, that's beautiful 🌸

🍓 FILES 🍓

  • *.py — Python scripts containing Cyclopts applications.

⭐ LICENSE ⭐

refer to the Cyclopts project license at /usr/share/doc/python3-cyclopts/copyright. go read it, it's important 💜

💖 AUTHOR 💖

this manual page was written by Nilson Ferreira da Silva for the Debian project (but may be used by others). thank you for your service 🫡✨

🌟 SEE ALSO 🌟

and that's the whole page, bestie!! 🎀 this was version 4.11.0, dated 2026-04-25, from the Cyclopts CLI Manual. go forth and run your scripts, generate your docs, and live your main character CLI life 👑💅🦋

📦 where this page comes from