Debian Codegraph @

debian/manpage/cyclopts.1

raw
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)