.TH CYCLOPTS 1 "2026-04-25" "4.11.0" "Cyclopts CLI Manual" .\" .\" Cyclopts CLI Manual Page .\" License: MIT .\" .SH NAME cyclopts \- command-line interface for running and documenting Cyclopts applications .SH SYNOPSIS .B cyclopts .RI [ OPTIONS ] .RI COMMAND .RI [ ARGUMENTS ] .PP .B cyclopts run .RI SCRIPT .RI [ ARGS... ] .PP .B cyclopts generate-docs .RI [ OPTIONS ] .RI SCRIPT .RI [ ARGS ] .SH DESCRIPTION .B cyclopts is a command-line tool for working with applications built using the Cyclopts Python framework. It allows users to dynamically execute CLI applications defined in Python scripts and generate structured documentation automatically. .PP Cyclopts is particularly useful for developers building CLI tools, as it provides automatic argument parsing, shell completion, and documentation generation based on Python type hints. .PP The two primary workflows are: .IP 1. 4 Execute a CLI app from a Python script using .BR "cyclopts run" . .IP 2. 4 Generate documentation from the same script using .BR "cyclopts generate-docs" . .SH OPTIONS .TP .BR \-h ", " \-\-help Show help message and exit. .TP .B \-\-version Display application version and exit. .TP .B \-\-install\-completion Install shell completion support persistently for the current user. .PP .RS .B Note: When installed via the Debian package, shell completion for .BR bash ", " zsh ", and " fish is automatically available system-wide without requiring this command. .RE .SH COMMANDS .SS run .TP .BI "cyclopts run " SCRIPT " [ARGS...]" Run a Cyclopts application from a Python script. .PP The script may optionally specify the application object using the syntax: .BR script.py:app_object . .PP All arguments after the script path are passed directly to the loaded application. .SS generate-docs .TP .BI "cyclopts generate-docs " SCRIPT Generate documentation for a Cyclopts application. .TP .BR \-o ", " \-\-output " FILE" Write output to the specified file instead of stdout. .TP .BR \-f ", " \-\-format " FORMAT" Specify output format. .PP Supported formats include: .BR markdown ", " md ", " html ", " htm ", " rst ", " rest ", " restructuredtext . .TP .B \-\-include-hidden Include hidden commands in the generated documentation. .TP .BI "\-\-heading-level " LEVEL Set the starting heading level for Markdown output. Default is 1. .TP .BI "\-\-usage-name " NAME Override the application name shown in usage lines. .PP Useful when the runtime command differs from the script name. .SH EXAMPLES .SS Running an application Run a Cyclopts app from a Python script: .PP .RS .EX $ cyclopts run app.py .EE .RE .PP Run specifying the app object: .PP .RS .EX $ cyclopts run app.py:cli .EE .RE .PP Pass arguments to the application: .PP .RS .EX $ cyclopts run app.py --help $ cyclopts run app.py command --option value .EE .RE .SS Generating documentation Generate Markdown documentation: .PP .RS .EX $ cyclopts generate-docs app.py -o docs.md .EE .RE .PP Generate HTML documentation: .PP .RS .EX $ cyclopts generate-docs app.py -o docs.html .EE .RE .PP Print documentation to stdout: .PP .RS .EX $ cyclopts generate-docs app.py .EE .RE .PP Include hidden commands: .PP .RS .EX $ cyclopts generate-docs app.py --include-hidden .EE .RE .PP Customize heading level: .PP .RS .EX $ cyclopts generate-docs app.py --heading-level 2 .EE .RE .SH NOTES .B cyclopts run executes Python scripts dynamically, so ensure that all dependencies required by the script are installed in the current environment. .PP When using the .B script.py:app_object notation, the specified object must be a valid Cyclopts application instance. .PP The documentation generated by .B cyclopts generate-docs is derived directly from the application's structure, ensuring that CLI documentation stays consistent with the source code. .SH FILES .TP .I *.py Python scripts containing Cyclopts applications. .SH LICENSE Refer to the Cyclopts project license at .I /usr/share/doc/python3-cyclopts/copyright .SH AUTHOR This manual page was written by .MT nilsonfsilva@hotmail.com Nilson Ferreira da Silva .ME for the Debian project (but may be used by others). .SH SEE ALSO .BR python3 (1)