CYCLOPTS(1)

NAME
cyclopts - command-line interface for running and documenting Cyclopts applications

SYNOPSIS
cyclopts [OPTIONS] COMMAND [ARGUMENTS]

cyclopts run SCRIPT [ARGS...]

cyclopts generate-docs [OPTIONS] SCRIPT [ARGS]

DESCRIPTION
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.

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.

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 help message and exit.

--version
    Display application version and exit.

--install-completion
    Install shell completion support persistently for the current user.

    Note: When installed via the Debian package, shell completion for bash, zsh, and fish is automatically available system-wide without requiring this command.

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 are passed directly to the loaded application.

  generate-docs

cyclopts generate-docs SCRIPT
    Generate documentation for a Cyclopts application.

-o, --output FILE
    Write output to the specified file instead of stdout.

-f, --format FORMAT
    Specify output format.

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

--include-hidden
    Include hidden commands in the generated documentation.

--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.

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
cyclopts run executes Python scripts dynamically, so ensure that all dependencies required by the script are installed in the current environment.

When using the script.py:app_object notation, the specified object must be a valid Cyclopts application instance.

The documentation generated by cyclopts generate-docs is derived directly from the application's structure, ensuring that CLI documentation stays consistent with the source code.

FILES

*.py
    Python scripts containing Cyclopts applications.

LICENSE
Refer to the Cyclopts project license at /usr/share/doc/python3-cyclopts/copyright

AUTHOR
This manual page was written by Nilson Ferreira da Silva (nilsonfsilva@hotmail.com) for the Debian project (but may be used by others).

SEE ALSO
python3(1)