| 1 |
.TH CYCLOPTS 1 "2026-04-25" "4.11.0" "Cyclopts CLI Manual" |
| 2 |
.\" |
| 3 |
.\" Cyclopts CLI Manual Page |
| 4 |
.\" License: MIT |
| 5 |
.\" |
| 6 |
.SH NAME |
| 7 |
cyclopts \- command-line interface for running and documenting Cyclopts applications |
| 8 |
.SH SYNOPSIS |
| 9 |
.B cyclopts |
| 10 |
.RI [ OPTIONS ] |
| 11 |
.RI COMMAND |
| 12 |
.RI [ ARGUMENTS ] |
| 13 |
.PP |
| 14 |
.B cyclopts run |
| 15 |
.RI SCRIPT |
| 16 |
.RI [ ARGS... ] |
| 17 |
.PP |
| 18 |
.B cyclopts generate-docs |
| 19 |
.RI [ OPTIONS ] |
| 20 |
.RI SCRIPT |
| 21 |
.RI [ ARGS ] |
| 22 |
.SH DESCRIPTION |
| 23 |
.B cyclopts |
| 24 |
is a command-line tool for working with applications built using the |
| 25 |
Cyclopts Python framework. It allows users to dynamically execute CLI |
| 26 |
applications defined in Python scripts and generate structured |
| 27 |
documentation automatically. |
| 28 |
.PP |
| 29 |
Cyclopts is particularly useful for developers building CLI tools, |
| 30 |
as it provides automatic argument parsing, shell completion, |
| 31 |
and documentation generation based on Python type hints. |
| 32 |
.PP |
| 33 |
The two primary workflows are: |
| 34 |
.IP 1. 4 |
| 35 |
Execute a CLI app from a Python script using |
| 36 |
.BR "cyclopts run" . |
| 37 |
.IP 2. 4 |
| 38 |
Generate documentation from the same script using |
| 39 |
.BR "cyclopts generate-docs" . |
| 40 |
.SH OPTIONS |
| 41 |
.TP |
| 42 |
.BR \-h ", " \-\-help |
| 43 |
Show help message and exit. |
| 44 |
.TP |
| 45 |
.B \-\-version |
| 46 |
Display application version and exit. |
| 47 |
.TP |
| 48 |
.B \-\-install\-completion |
| 49 |
Install shell completion support persistently for the current user. |
| 50 |
.PP |
| 51 |
.RS |
| 52 |
.B Note: |
| 53 |
When installed via the Debian package, shell completion for |
| 54 |
.BR bash ", " zsh ", and " fish |
| 55 |
is automatically available system-wide without requiring this command. |
| 56 |
.RE |
| 57 |
.SH COMMANDS |
| 58 |
.SS run |
| 59 |
.TP |
| 60 |
.BI "cyclopts run " SCRIPT " [ARGS...]" |
| 61 |
Run a Cyclopts application from a Python script. |
| 62 |
.PP |
| 63 |
The script may optionally specify the application object using |
| 64 |
the syntax: |
| 65 |
.BR script.py:app_object . |
| 66 |
.PP |
| 67 |
All arguments after the script path are passed directly to the |
| 68 |
loaded application. |
| 69 |
.SS generate-docs |
| 70 |
.TP |
| 71 |
.BI "cyclopts generate-docs " SCRIPT |
| 72 |
Generate documentation for a Cyclopts application. |
| 73 |
.TP |
| 74 |
.BR \-o ", " \-\-output " FILE" |
| 75 |
Write output to the specified file instead of stdout. |
| 76 |
.TP |
| 77 |
.BR \-f ", " \-\-format " FORMAT" |
| 78 |
Specify output format. |
| 79 |
.PP |
| 80 |
Supported formats include: |
| 81 |
.BR markdown ", " md ", " html ", " htm ", " rst ", " rest ", " restructuredtext . |
| 82 |
.TP |
| 83 |
.B \-\-include-hidden |
| 84 |
Include hidden commands in the generated documentation. |
| 85 |
.TP |
| 86 |
.BI "\-\-heading-level " LEVEL |
| 87 |
Set the starting heading level for Markdown output. |
| 88 |
Default is 1. |
| 89 |
.TP |
| 90 |
.BI "\-\-usage-name " NAME |
| 91 |
Override the application name shown in usage lines. |
| 92 |
.PP |
| 93 |
Useful when the runtime command differs from the script name. |
| 94 |
.SH EXAMPLES |
| 95 |
.SS Running an application |
| 96 |
Run a Cyclopts app from a Python script: |
| 97 |
.PP |
| 98 |
.RS |
| 99 |
.EX |
| 100 |
$ cyclopts run app.py |
| 101 |
.EE |
| 102 |
.RE |
| 103 |
.PP |
| 104 |
Run specifying the app object: |
| 105 |
.PP |
| 106 |
.RS |
| 107 |
.EX |
| 108 |
$ cyclopts run app.py:cli |
| 109 |
.EE |
| 110 |
.RE |
| 111 |
.PP |
| 112 |
Pass arguments to the application: |
| 113 |
.PP |
| 114 |
.RS |
| 115 |
.EX |
| 116 |
$ cyclopts run app.py --help |
| 117 |
$ cyclopts run app.py command --option value |
| 118 |
.EE |
| 119 |
.RE |
| 120 |
.SS Generating documentation |
| 121 |
Generate Markdown documentation: |
| 122 |
.PP |
| 123 |
.RS |
| 124 |
.EX |
| 125 |
$ cyclopts generate-docs app.py -o docs.md |
| 126 |
.EE |
| 127 |
.RE |
| 128 |
.PP |
| 129 |
Generate HTML documentation: |
| 130 |
.PP |
| 131 |
.RS |
| 132 |
.EX |
| 133 |
$ cyclopts generate-docs app.py -o docs.html |
| 134 |
.EE |
| 135 |
.RE |
| 136 |
.PP |
| 137 |
Print documentation to stdout: |
| 138 |
.PP |
| 139 |
.RS |
| 140 |
.EX |
| 141 |
$ cyclopts generate-docs app.py |
| 142 |
.EE |
| 143 |
.RE |
| 144 |
.PP |
| 145 |
Include hidden commands: |
| 146 |
.PP |
| 147 |
.RS |
| 148 |
.EX |
| 149 |
$ cyclopts generate-docs app.py --include-hidden |
| 150 |
.EE |
| 151 |
.RE |
| 152 |
.PP |
| 153 |
Customize heading level: |
| 154 |
.PP |
| 155 |
.RS |
| 156 |
.EX |
| 157 |
$ cyclopts generate-docs app.py --heading-level 2 |
| 158 |
.EE |
| 159 |
.RE |
| 160 |
.SH NOTES |
| 161 |
.B cyclopts run |
| 162 |
executes Python scripts dynamically, so ensure that all dependencies |
| 163 |
required by the script are installed in the current environment. |
| 164 |
.PP |
| 165 |
When using the |
| 166 |
.B script.py:app_object |
| 167 |
notation, the specified object must be a valid Cyclopts application |
| 168 |
instance. |
| 169 |
.PP |
| 170 |
The documentation generated by |
| 171 |
.B cyclopts generate-docs |
| 172 |
is derived directly from the application's structure, ensuring that |
| 173 |
CLI documentation stays consistent with the source code. |
| 174 |
.SH FILES |
| 175 |
.TP |
| 176 |
.I *.py |
| 177 |
Python scripts containing Cyclopts applications. |
| 178 |
.SH LICENSE |
| 179 |
Refer to the Cyclopts project license at |
| 180 |
.I /usr/share/doc/python3-cyclopts/copyright |
| 181 |
.SH AUTHOR |
| 182 |
This manual page was written by |
| 183 |
.MT [email protected] |
| 184 |
Nilson Ferreira da Silva |
| 185 |
.ME |
| 186 |
for the Debian project (but may be used by others). |
| 187 |
.SH SEE ALSO |
| 188 |
.BR python3 (1) |