cyclopts - Man Page

The most basic Cyclopts application is as follows:

from cyclopts import App

app = App()

@app.default
def main():
    print("Hello World!")

if __name__ == "__main__":
    app()

Save this as main.py and execute it to see:

$ python main.py
Hello World!

The App <#cyclopts.App> class offers various configuration options that we'll explore in more detail later. The app object has a decorator method, default <#cyclopts.App.default>, which registers a function as the default action. In this example, the main function is our default action, and is executed when no CLI command is provided.

Let's add some arguments to make this program a little more interesting.

from cyclopts import App

app = App()

@app.default
def main(name):
    print(f"Hello {name}!")

if __name__ == "__main__":
    app()

Executing the script with the argument Alice produces the following:

$ python main.py Alice
Hello Alice!

Code explanation:

1. The function main() was registered to app as the default action.
2. Calling app() at the bottom triggers the app to begin parsing CLI inputs.

3. Cyclopts identifies "Alice" as a positional argument and matches it to the parameter name. In the absence of an explicit type hint, Cyclopts defaults to parsing the value as a str.

   Note:

   Without a type annotation, Cyclopts will actually first attempt to use the type of the parameter's default value. If the parameter doesn't have a default value, it will then fallback to str. See Coercion Rules <#coercion-rules>.

4. Cyclopts calls the registered default function main("Alice"), and the greeting is printed.

Extending the example, lets add more arguments and type hints:

from cyclopts import App

app = App()

@app.default
def main(name: str, count: int, formal: bool = False):
    for _ in range(count):
       if formal:
          print(f"Hello {name}!")
       else:
          print(f"Hey {name}!")

if __name__ == "__main__":
    app()

$ python main.py Alice 3
Hey Alice!
Hey Alice!
Hey Alice!

$ python main.py Alice 3 --formal
Hello Alice!
Hello Alice!
Hello Alice!

The command line input "3" is converted to an integer because the parameter count has the type hint int <https://docs.python.org/3/library/functions.html#int>. Boolean parameters (e.g., --formal in this example) are interpreted as flags. Cyclopts natively handles all python builtin types (and more! <#coercion-rules>). Cyclopts adheres to Python's argument binding rules, allowing for both positional and keyword arguments. All of the following CLI invocations are equivalent:

$ python main.py Alice 3                  # Supplying arguments positionally.
$ python main.py --name Alice --count 3   # Supplying arguments via keywords.
$ python main.py --name=Alice --count=3   # Using = for matching keywords to values is allowed.
$ python main.py --count 3 --name=Alice   # Keyword order does not matter.
$ python main.py Alice --count 3          # Positional followed by keyword
$ python main.py --count 3 Alice          # Keywords can come before positional if the keyword is later in the function signature.
$ python main.py --count 3 -- Alice       # Using the POSIX convention to indicate the end of keywords

Like calling functions in python, positional arguments cannot be specified after a prior argument in the function signature was specified via keyword. For example, you cannot supply the count value "3" positionally while the value for name is specified via keyword:

# The following are NOT allowed.
$ python main.py --name=Alice 3  # invalid python: main(name="Alice", 3)
$ python main.py 3 --name=Alice  # invalid python: main(3, name="Alice")

All CLI apps need to have a help page explaining how to use the application. By default, Cyclopts adds the --help (and the shortform -h) commands to your CLI. We can add application-level help documentation when creating our app:

from cyclopts import App

app = App(help="Help string for this demo application.")

@app.default
def main(name: str, count: int):
    for _ in range(count):
        print(f"Hello {name}!")

if __name__ == "__main__":
    app()

$ python main.py --help
Usage: main COMMAND [ARGS] [OPTIONS]

Help string for this demo application.

╭─ Commands ──────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                           │
│ --version  Display application version.                             │
╰─────────────────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────────────────╮
│ *  NAME --name    [required]                                        │
│ *  COUNT --count  [required]                                        │
╰─────────────────────────────────────────────────────────────────────╯

Note:

Help flags can be changed with help_flags <#cyclopts.App.help_flags>.

Let's add some help documentation for our parameters. Cyclopts uses the function's docstring and can interpret ReST, Google, Numpydoc-style and Epydoc docstrings (shoutout to docstring_parser <https://github.com/rr-/docstring_parser>).

from cyclopts import App

app = App()

@app.default
def main(name: str, count: int):
    """Help string for this demo application.

    Parameters
    ----------
    name: str
        Name of the user to be greeted.
    count: int
        Number of times to greet.
    """
    for _ in range(count):
        print(f"Hello {name}!")

if __name__ == "__main__":
    app()

$ python main.py --help
Usage: main COMMAND [ARGS] [OPTIONS]

Help string for this demo application.

╭─ Commands ──────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                           │
│ --version  Display application version.                             │
╰─────────────────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────────────────╮
│ *  NAME --name    Name of the user to be greeted. [required]        │
│ *  COUNT --count  Number of times to greet. [required]              │
╰─────────────────────────────────────────────────────────────────────╯

Note:

If App.help <#cyclopts.App.help> is not explicitly set, Cyclopts will fallback to the first line (short description) of the registered @app.default function's docstring.

An alternative, terser API is available for simple applications with a single command. The run() <#cyclopts.run> function takes in a single callable (usually a function) and runs it as a Cyclopts application.

import cyclopts

def main(name: str, count: int):
    for _ in range(count):
        print(f"Hello {name}!")

if __name__ == "__main__":
    cyclopts.run(main)

The run() <#cyclopts.run> function is intentionally simple. If greater control is required, then use the conventional App <#cyclopts.App> interface.

The @app.command <#cyclopts.App.command> decorator adds a command to a Cyclopts application.

from cyclopts import App

app = App()

@app.command
def fizz(n: int):
    print(f"FIZZ: {n}")

@app.command
def buzz(n: int):
    print(f"BUZZ: {n}")

app()

We can now control which command runs from the CLI:

$ my-script fizz 3
FIZZ: 3

$ my-script buzz 4
BUZZ: 4

$ my-script fuzz
╭─ Error ────────────────────────────────────────────────────────────────────╮
│ Unknown command "fuzz". Did you mean "fizz"?                               │
╰────────────────────────────────────────────────────────────────────────────╯

The app.command <#cyclopts.App.command> method can also register another Cyclopts App <#cyclopts.App> as a command.

from cyclopts import App

app = App()
sub_app = App(name="foo")  # "foo" would be a better variable name than "sub_app".
# "sub_app" in this example emphasizes the name comes from name="foo".
app.command(sub_app)  # Registers sub_app to command "foo"
# Or, as a one-liner:  sub_app = app.command(App(name="foo"))


@sub_app.command
def bar(n: int):
    print(f"BAR: {n}")


# Alternatively, access subapps from app like a dictionary.
@app["foo"].command
def baz(n: int):
    print(f"BAZ: {n}")


app()

$ my-script foo bar 3
BAR: 3

$ my-script foo baz 4
BAZ: 4

The subcommand may have their own registered default action. Cyclopts's command structure is fully recursive.

Sometimes you want to make all commands from a sub-app directly accessible from the parent app, without requiring users to type the intermediate subcommand name.

You can flatten a sub-app by registering it with the special name="*":

from cyclopts import App

app = App()
tools_app = App(name="tools")

@tools_app.command
def compress(file: str):
    print(f"Compressing {file}")

@tools_app.command
def extract(file: str):
    print(f"Extracting {file}")

# Flatten: make all tools_app commands directly accessible
app.command(tools_app, name="*")

app()

$ my-script compress data.txt
Compressing data.txt

$ my-script extract archive.zip
Extracting archive.zip

Caveats of flattening:

• Parent app commands take precedence over flattened commands if there are name collisions.
• Multiple sub-apps can be flattened into the same parent app.
• You cannot supply additional configuration kwargs when using name="*".
• Only App <#cyclopts.App> instances can be flattened (not functions or import paths).

Flattening is useful for organizing related commands into logical groups in your code while keeping the CLI interface simple and flat.

Subcommands inherit configuration from their parent apps.

from cyclopts import App

# Root app with specific error handling
root_app = App(
    exit_on_error=False,
    print_error=False,
)

# Child app inherits parent's settings
child_app = root_app.command(App(name="child"))

@child_app.default
def child_action():
    return "Child executed successfully"

# Child can override parent settings if needed
grandchild_app = child_app.command(App(name="grandchild", exit_on_error=True))

When parent_app("child ...") is called, the child command will use the parent's error handling settings unless explicitly overridden.

By default, commands are registered to the python function's name with underscores replaced with hyphens. Any leading or trailing underscores will be stripped. For example, the function _foo_bar() will become the command foo-bar. This renaming is done because CLI programs generally tend to use hyphens instead of underscores. The name transform can be configured by App.name_transform <#cyclopts.App.name_transform>. For example, to make CLI command names be identical to their python function name counterparts, we can configure App <#cyclopts.App> as follows:

from cyclopts import App

app = App(name_transform=lambda s: s)

@app.command
def foo_bar():  # will now be "foo_bar" instead of "foo-bar"
    print("running function foo_bar")

app()

$ my-script foo_bar
running function foo_bar

Alternatively, the name can be manually changed in the @app.command <#cyclopts.App.command> decorator. Manually set names are not subject to App.name_transform <#cyclopts.App.name_transform>.

from cyclopts import App

app = App()

@app.command(name="bar")
def foo():  # function name will NOT be used.
    print("Hello World!")

app()

$ my-script bar
Hello World!

Finally, if you would like to register an additional name to the Cyclopts-derived names, you can set an alias <#cyclopts.App.alias>:

from cyclopts import App

app = App()

@app.command(alias="bar")
def foo():  # both "foo" and "bar" will trigger this function.
    print("Running foo.")

app()

$ my-script foo
Running bar.

$ my-script bar
Running bar.

There are a few ways to add a help string to a command:

1. If the function has a docstring, the short description will be used as the help string for the command. This is generally the preferred method of providing help strings.

2. If the registered command is a sub app, the sub app's help <#cyclopts.App.help> field will be used.

   sub_app = App(name="foo", help="Help text for foo.")
   app.command(sub_app)

3. The help <#cyclopts.App.help> field of @app.command <#cyclopts.App.command>. If provided, the docstring or subapp help field will not be used.

   from cyclopts import App
   
   app = App()
   
   @app.command
   def foo():
       """Help string for foo."""
       pass
   
   @app.command(help="Help string for bar.")
   def bar():
       """This got overridden."""
   
   app()

   $ my-script --help
   ╭─ Commands ────────────────────────────────────────────────────────────╮
   │ bar        Help string for bar.                                       │
   │ foo        Help string for foo.                                       │
   │ --help,-h  Display this message and exit.                             │
   │ --version  Display application version.                               │
   ╰───────────────────────────────────────────────────────────────────────╯

Cyclopts also works with async commands; when an async command is encountered, an event loop will be automatically created using the specified backend parameter (default asyncio <https://docs.python.org/3/library/asyncio.html#module-asyncio>).

import asyncio
from cyclopts import App

app = App()

@app.command
async def foo():
    await asyncio.sleep(10)

app()

When calling from within an existing async context, await <https://docs.python.org/3/reference/expressions.html#await> the async method run_async() <#cyclopts.App.run_async>:

async def main():
    result = await app.run_async(["foo"])
    # Instead of: app(["foo"]) which would raise RuntimeError

Cyclopts does not modify the decorated function in any way. The returned function is the exact same function being decorated and can be used exactly as if it were not decorated by Cyclopts.

For improved CLI startup performance with large applications, see Lazy Loading <#lazy-loading>.

Like command names <#command-changing-name>, CLI parameter names are derived from their python counterparts. However, sometimes customization is needed.

Parameter names (and their short forms) can be manually specified:

from cyclopts import App, Parameter
from typing import Annotated

app = App()

@app.default
def main(
    *,
    foo: Annotated[str, Parameter(name=["--foo", "-f"])],  # Adding a short-form
    # Equivalently, you could have done Parameter(alias="-f")
    bar: Annotated[str, Parameter(name="--something-else")],
):
    pass

app()

$ my-script --help

Usage: main COMMAND [OPTIONS]
╭─ Commands ──────────────────────────────────────────────╮
│ --help -h  Display this message and exit.               │
│ --version  Display application version.                 │
╰─────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────╮
│ *  --foo             -f  [required]                     │
│ *  --something-else      [required]                     │
╰─────────────────────────────────────────────────────────╯

Manually set names via Parameter.name <#cyclopts.Parameter.name> are not subject to Parameter.name_transform <#cyclopts.Parameter.name_transform>. Alternatively, additional names can be added to the Cyclopts-derived names (instead of completely overriding them) with Parameter.alias <#cyclopts.Parameter.alias>.

Note:

@app.default
def main(internal_name: Annotated[str, Parameter(name="external-name")]):
    """Command description.

    Parameters
    ----------
    internal_name:            # Use the Python variable name
        Help text here.
    """

The name transform function that converts the python variable name to it's CLI counterpart can be configured by setting Parameter.name_transform <#cyclopts.Parameter.name_transform> (defaults to default_name_transform() <#cyclopts.default_name_transform>).

from cyclopts import App, Parameter
from typing import Annotated

app = App()

def name_transform(s: str) -> str:
    return s.upper()

@app.default
def main(
    *,
    foo: Annotated[str, Parameter(name_transform=name_transform)],
    bar: Annotated[str, Parameter(name_transform=name_transform)],
):
    pass

app()

$ my-script --help
Usage: main COMMAND [OPTIONS]

╭─ Commands ──────────────────────────────────────────────╮
│ --help -h  Display this message and exit.               │
│ --version  Display application version.                 │
╰─────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────╮
│ *  --FOO  [required]                                    │
│ *  --BAR  [required]                                    │
╰─────────────────────────────────────────────────────────╯

Notice how the parameter is now --FOO instead of the standard --foo.

Note:

Generally, it is not very useful to set the name transform on individual parameters; it would be easier/clearer to manually specify the name. However, we can change the default name transform for the entire app by configuring the app's default_parameter <#default-parameter>.

To change the name_transform <#cyclopts.Parameter.name_transform> across your entire app, add the following to your App <#cyclopts.App> configuration:

app = App(
    default_parameter=Parameter(name_transform=my_custom_name_transform),
)

It is recommended to use docstrings for your parameter help, but if necessary, you can explicitly set a help string:

@app.command
def foo(value: Annotated[int, Parameter(help="THIS IS USED.")]):
    """
    Parameters
    ----------
    value: int
        This description is not used; got overridden.
    """

$ my-script foo --help
╭─ Parameters ──────────────────────────────────────────────────╮
│ *  VALUE,--value  THIS IS USED. [required]                    │
╰───────────────────────────────────────────────────────────────╯

Cyclopts has a powerful coercion engine that automatically converts CLI string tokens to the types hinted in a function signature. However, sometimes a custom converter <#cyclopts.Parameter.converter> is required to transform the input string tokens into the desired type.

Lets consider a case where we want the user to specify a file size, and we want to allows suffixes like "MB".

from cyclopts import App, Parameter, Token
from typing import Annotated, Sequence
from pathlib import Path

app = App()

mapping = {
    "kb": 1024,
    "mb": 1024 * 1024,
    "gb": 1024 * 1024 * 1024,
}

def byte_units(type_, tokens: Sequence[Token]) -> int:
    # type_ is ``int``,
    value = tokens[0].value.lower()
    try:
        return type_(value)  # If this works, it didn't have a suffix.
    except ValueError:
        pass
    number, suffix = value[:-2], value[-2:]
    return int(number) * mapping[suffix]

@app.command
def zero(file: Path, size: Annotated[int, Parameter(converter=byte_units)]):
    """Creates a file of all-zeros."""
    print(f"Writing {size} zeros to {file}.")
    file.write_bytes(bytes(size))

app()

$ my-script zero out.bin 100
Writing 100 zeros to out.bin.

$ my-script zero out.bin 1kb
Writing 1024 zeros to out.bin.

$ my-script zero out.bin 3mb
Writing 3145728 zeros to out.bin.

The converter function gets the annotated type, and the Token <#cyclopts.Token> s parsed for this argument. Tokens are Cyclopt's way of bookkeeping user inputs; in the last command the tokens object would look like:

 # tokens is a length-1 tuple. The variable "size" only takes in 1 token:
 tuple(
   Token(
      keyword=None,  # "3mb" was provided positionally, not by keyword
      value='3mb',   # The string from the command line
      source='cli',  # The value came from the command line, as opposed to other Cyclopts mechanisms.
      index=0,       # For the variable "size", this is the first (0th) token.
   ),
)

By default, Cyclopts infers how many tokens a parameter should consume from its type hint. For example, int <https://docs.python.org/3/library/functions.html#int> consumes 1 token, tuple[int, int] consumes 2, and list[int] consumes all remaining tokens. When using custom converters, you may need to override this inference with Parameter.n_tokens <#cyclopts.Parameter.n_tokens>:

from cyclopts import App, Parameter
from typing import Annotated

class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

def parse_point(type_, tokens):
    """Parse a coordinate string like '10,20' into a Point."""
    x, y = tokens[0].value.split(",")
    return Point(int(x), int(y))

app = App()

@app.default
def main(pos: Annotated[Point, Parameter(n_tokens=1, converter=parse_point, accepts_keys=False)]):
    """Without n_tokens=1, Cyclopts would expect 2 tokens based on Point's __init__ signature."""
    print(f"Position: ({pos.x}, {pos.y})")

app()

$ my-script --pos 10,20
Position: (10, 20)

The Parameter.accepts_keys <#cyclopts.Parameter.accepts_keys> parameter prevents Cyclopts from generating nested options like --pos.x and --pos.y.

Alternative to the above syntax, you can directly decorate the converter function itself with Parameter <#cyclopts.Parameter> to define its behavior. This keeps all the information organized in a single location.

from cyclopts import App, Parameter
from typing import Annotated

class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

@Parameter(n_tokens=1, accepts_keys=False)
def parse_point(type_, tokens):
    """Parse a coordinate string like '10,20' into a Point."""
    x, y = tokens[0].value.split(",")
    return Point(int(x), int(y))

app = App()

@app.default
def main(pos: Annotated[Point, Parameter(converter=parse_point)]):
    """The converter's n_tokens and accepts_keys are automatically inherited."""
    print(f"Position: ({pos.x}, {pos.y})")

app()

$ my-script --pos 10,20
Position: (10, 20)

You can also decorate classes directly with the converter:

@Parameter(converter=parse_point)
class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

@app.default
def main(pos: Point):
    """No Annotated wrapper needed - converter is part of the class definition."""
    print(f"Position: ({pos.x}, {pos.y})")

Converter functions are often closely associated with the class they create, making classmethods a natural choice. Cyclopts supports using classmethods as converters through forward string references (for class decoration) or direct references (for function annotations):

from cyclopts import App, Parameter
from typing import Annotated

# Decorate the classmethod to configure n_tokens and accepts_keys
# (decorator must go above @classmethod)
@Parameter(converter="parse")
class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

    @Parameter(n_tokens=1, accepts_keys=False)
    @classmethod
    def parse(cls, tokens):
        """Parse a coordinate string like '10,20' into a Point.

        Note: classmethod signature is (cls, tokens), not (type_, tokens)
        """
        x, y = tokens[0].value.split(",")
        return cls(int(x), int(y))

app = App()

@app.default
def main(pos: Point):
    """The classmethod's n_tokens and accepts_keys are automatically inherited."""
    print(f"Position: ({pos.x}, {pos.y})")

app()

$ my-script --pos 10,20
Position: (10, 20)

Alternatively, you can reference the classmethod directly in function annotations:

class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

    @classmethod
    def parse(cls, tokens):
        x, y = tokens[0].value.split(",")
        return cls(int(x), int(y))

@app.default
def main(pos: Annotated[Point, Parameter(converter=Point.parse, n_tokens=1, accepts_keys=False)]):
    print(f"Position: ({pos.x}, {pos.y})")

Note on classmethod signatures: Classmethods used as converters should have the signature (cls, tokens) rather than (type_, tokens). Cyclopts automatically detects bound methods and calls them with just the tokens parameter, since cls is already bound.

Just because data is of the correct type, doesn't mean it's valid. If we had a program that accepts integer user age as an input, -1 is an integer, but not a valid age.

from cyclopts import App, Parameter
from typing import Annotated

app = App()

def validate_age(type_, value):
    if value < 0:
        raise ValueError("Negative ages not allowed.")
    if value > 150:
        raise ValueError("You are too old to be using this application.")

@app.default
def allowed_to_buy_alcohol(age: Annotated[int, Parameter(validator=validate_age)]):
    print("Under 21: prohibited." if age < 21 else "Good to go!")

app()

$ my-script 30
Good to go!

$ my-script 10
Under 21: prohibited.

$ my-script -1
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ Invalid value "-1" for "AGE". Negative ages not allowed.                     │
╰──────────────────────────────────────────────────────────────────────────────╯

$ my-script 200
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ Invalid value "200" for "AGE". You are too old to be using this application. │
╰──────────────────────────────────────────────────────────────────────────────╯

Certain builtin error types (ValueError <https://docs.python.org/3/library/exceptions.html#ValueError>, TypeError <https://docs.python.org/3/library/exceptions.html#TypeError>, AssertionError <https://docs.python.org/3/library/exceptions.html#AssertionError>) will be re-interpreted by Cyclopts and formatted into a prettier message for the application user.

Cyclopts has some builtin validators <#parameter-validators> for common situations We can create a similar app as above:

from cyclopts import App, Parameter, validators
from typing import Annotated

app = App()

@app.default
def allowed_to_buy_alcohol(age: Annotated[int, Parameter(validator=validators.Number(gte=0, lte=150))]):
    # gte - greater than or equal to
    # lte - less than or equal to
    print("Under 21: prohibited." if age < 21 else "Good to go!")

app()

Taking this one step further, Cyclopts has some builtin convenience types <#annotated-types>. If we didn't care about the upper age bound, we could simplify the application to:

from cyclopts import App
from cyclopts.types import NonNegativeInt

app = App()

@app.default
def allowed_to_buy_alcohol(age: NonNegativeInt):
    print("Under 21: prohibited." if age < 21 else "Good to go!")

app()

Cyclopts can combine multiple Parameter <#cyclopts.Parameter> annotations together. Say you want to define a new int <https://docs.python.org/3/library/functions.html#int> type that uses the byte-centric converter from above.

We can define the type:

ByteSize = Annotated[int, Parameter(converter=byte_units)]

We can then either directly annotate a function parameter with this:

@app.command
def zero(size: ByteSize):
    pass

or even stack annotations to add additional features, like a validator:

def must_be_multiple_of_4096(type_, value):
    assert value % 4096 == 0, "Size must be a multiple of 4096"


@app.command
def zero(size: Annotated[ByteSize, Parameter(validator=must_be_multiple_of_4096)]):
    pass

Python automatically flattens out annotations, so this is interpreted as:

Annotated[ByteSize, Parameter(converter=byte_units), Parameter(validator=must_be_multiple_of_4096)]

Cyclopts will search right-to-left for set parameter attributes until one is found. I.e. right-most parameter attributes have the highest priority.

$ my-script 1234
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ Invalid value "1234" for "SIZE". Size must be a multiple of 4096             │
╰──────────────────────────────────────────────────────────────────────────────╯

See Parameter Resolution Order <#parameter-resolution-order> for more details.

When resolving what the Parameter <#cyclopts.Parameter> values for an individual function parameter should be, explicitly set attributes of higher priority Parameter <#cyclopts.Parameter> s override lower priority Parameter <#cyclopts.Parameter> s. The resolution order is as follows:

1. Highest Priority: Parameter-annotated command function signature Annotated[..., Parameter()].
2. Group.default_parameter <#cyclopts.Group.default_parameter> that the parameter belongs to.
3. App.default_parameter <#cyclopts.App.default_parameter> of the app that registered the command.
4. Group.default_parameter <#cyclopts.Group.default_parameter> of the app that the function belongs to.
5. Lowest Priority: (2-4) recursively of the parenting app call-chain.

Any of Parameter's fields can be set to None to revert back to the true-original Cyclopts default.

The Parameter.parse <#cyclopts.Parameter.parse> attribute can accept a regex pattern to selectively skip parameters based on their name. This is useful for defining "private" parameters that are externally injected (e.g. a Meta App <#meta-app>, dependency-injection framework, etc) rather than parsed from the CLI.

For example, to skip all underscore-prefixed parameters:

from typing import Annotated
from cyclopts import App, Parameter

# The regex "^(?!_)" matches names that do NOT start with underscore.
app = App(default_parameter=Parameter(parse="^(?!_)"))

@app.command
def greet(name: str, *, _db: Database):
    user = _db.get_user(name)
    print(f"Hello {user.full_name}!")

@app.meta.default
def launcher(*tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)]):
    # Create shared resources
    db = Database("myapp.db")

    # Parse CLI and get ignored (non-parsed) parameters
    command, bound, ignored = app.parse_args(tokens)

    # Inject ignored parameters
    for name, type_ in ignored.items():
        if type_ is Database:
            bound.kwargs[name] = db

    return command(*bound.args, **bound.kwargs)

if __name__ == "__main__":
    app.meta()

$ my-script --help
Usage: my-script COMMAND

╭─ Commands ────────────────────────────────────────────────────╮
│ greet                                                         │
│ --help,-h  Display this message and exit.                     │
│ --version  Display application version.                       │
╰───────────────────────────────────────────────────────────────╯

$ my-script greet --help
Usage: my-script greet [ARGS] [OPTIONS]

╭─ Parameters ──────────────────────────────────────────────────╮
│ *  NAME,--name  [required]                                    │
╰───────────────────────────────────────────────────────────────╯

Notice that _db does not appear in the help screen. Parameters that don't match the regex pattern are added to the ignored dictionary returned by App.parse_args() <#cyclopts.App.parse_args>, making them available for meta-app injection.

Like all other Parameter configurations, explicitly annotating with parse=True overrides the app-level regex:

from typing import Annotated
from cyclopts import App, Parameter

app = App(default_parameter=Parameter(parse="^(?!_)"))

@app.default
def main(name: str, *, _verbose: Annotated[bool, Parameter(parse=True)] = False):
    """_verbose IS parsed despite the underscore prefix"""

Important:

Parameters that are not parsed (either via parse=False or a non-matching regex pattern) must be either:

• Keyword-only (defined after * in the function signature), or

• Have a default value

  # Valid: keyword-only parameter
  def main(*, _context: dict): ...
  
  # Valid: has default value
  def main(_context: dict = None): ...
  
  # Invalid: positional without default - raises ValueError
  def main(_context: dict): ...

An example of using groups to organize commands:

from cyclopts import App

app = App()

# Change the group of "--help" and "--version" to the implicitly created "Admin" group.
app["--help"].group = "Admin"
app["--version"].group = "Admin"

@app.command(group="Admin")
def info():
    """Print debugging system information."""
    print("Displaying system info.")

@app.command
def download(path, url):
    """Download a file."""
    print(f"Downloading {url} to {path}.")

@app.command
def upload(path, url):
    """Upload a file."""
    print(f"Downloading {url} to {path}.")

app()

$ python my-script.py --help
Usage: my-script.py COMMAND

╭─ Admin ──────────────────────────────────────────────────────────────────────╮
│ info       Print debugging system information.                               │
│ --help,-h  Display this message and exit.                                    │
│ --version  Display application version.                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ download  Download a file.                                                   │
│ upload    Upload a file.                                                     │
╰──────────────────────────────────────────────────────────────────────────────╯

The default group is defined by the registering app's App.group_commands <#cyclopts.App.group_commands>, which defaults to a group named "Commands".

Like commands above, parameter groups allow us to organize parameters on the help page. They also allow us to add additional inter-parameter validators (e.g. mutually-exclusive parameters). An example of using groups with parameters:

from cyclopts import App, Group, Parameter, validators
from typing import Annotated

app = App()

vehicle_type_group = Group(
    "Vehicle (choose one)",
    default_parameter=Parameter(negative=""),  # Disable "--no-" flags
    validator=validators.MutuallyExclusive(),  # Only one option is allowed to be selected.
)

@app.command
def create(
    *,  # force all subsequent variables to be keyword-only
    # Using an explicitly created group object.
    car: Annotated[bool, Parameter(group=vehicle_type_group)] = False,
    truck: Annotated[bool, Parameter(group=vehicle_type_group)] = False,
    # Implicitly creating an "Engine" group.
    hp: Annotated[float, Parameter(group="Engine")] = 200,
    cylinders: Annotated[int, Parameter(group="Engine")] = 6,
    # You can explicitly create groups in-line.
    wheel_diameter: Annotated[float, Parameter(group=Group("Wheels"))] = 18,
    # Groups within the function signature can always be referenced with a string.
    rims: Annotated[bool, Parameter(group="Wheels")] = False,
):
    pass

app()

$ python my-script.py create --help
Usage: my-script.py create [OPTIONS]

╭─ Engine ──────────────────────────────────────────────────────╮
│ --hp         [default: 200]                                   │
│ --cylinders  [default: 6]                                     │
╰───────────────────────────────────────────────────────────────╯
╭─ Vehicle (choose one) ────────────────────────────────────────╮
│ --car    [default: False]                                     │
│ --truck  [default: False]                                     │
╰───────────────────────────────────────────────────────────────╯
╭─ Wheels ──────────────────────────────────────────────────────╮
│ --wheel-diameter  [default: 18]                               │
│ --rims --no-rims  [default: False]                            │
╰───────────────────────────────────────────────────────────────╯

$ python my-script.py create --car --truck
╭─ Error ───────────────────────────────────────────────────────╮
│ Invalid values for group "Vehicle (choose one)". Mutually     │
│ exclusive arguments: {--car, --truck}                         │
╰───────────────────────────────────────────────────────────────╯

In this example, we use the MutuallyExclusive <#cyclopts.validators.MutuallyExclusive> validator to make it so the user can only specify --car or --truck.

The default groups are defined by the registering app:

• App.group_arguments <#cyclopts.App.group_arguments> for positional-only arguments, which defaults to a group named "Arguments".
• App.group_parameters <#cyclopts.App.group_parameters> for all other parameters, which defaults to a group named "Parameters".

Group validators offer a way of jointly validating group parameter members of CLI-provided values. Groups with an empty name, or with show=False, are a way of using group validators without impacting the help-page.

from cyclopts import App, Group, Parameter, validators
from typing import Annotated

app = App()

mutually_exclusive = Group(
   # This Group has no name, so it won't impact the help page.
   validator=validators.MutuallyExclusive(),
   # show_default=False - Showing "[default: False]" isn't too meaningful for mutually-exclusive options.
   # negative="" - Don't create a "--no-" flag
   default_parameter=Parameter(show_default=False, negative=""),
)

@app.command
def foo(
    car: Annotated[bool, Parameter(group=(app.group_parameters, mutually_exclusive))] = False,
    truck: Annotated[bool, Parameter(group=(app.group_parameters, mutually_exclusive))] = False,
):
    print(f"{car=} {truck=}")

app()

$ python demo.py foo --help
Usage: demo.py foo [ARGS] [OPTIONS]

╭─ Parameters ──────────────────────────────────────────────────────╮
│ CAR,--car                                                         │
│ TRUCK,--truck                                                     │
╰───────────────────────────────────────────────────────────────────╯

$ python demo.py foo --car
car=True truck=False

$ python demo.py foo --truck
car=False truck=True

$ python demo.py foo --car --truck
╭─ Error ───────────────────────────────────────────────────────────╮
│  Mutually exclusive arguments: {--car, --truck}                   │
╰───────────────────────────────────────────────────────────────────╯

See Group.validator <#cyclopts.Group.validator> for details.

Cyclopts has some builtin group-validators for common use-cases. <#group-validators>

Groups form titled panels on the help-page.

Groups with an empty name, or with show=False <#cyclopts.Group.show>, are not shown on the help-page. This is useful for applying additional grouping logic (such as applying a LimitedChoice <#cyclopts.validators.LimitedChoice> validator) without impacting the help-page.

By default, the ordering of panels is alphabetical. However, the sorting can be manipulated by Group.sort_key <#cyclopts.Group.sort_key>. See it's documentation for usage.

The Group.create_ordered() <#cyclopts.Group.create_ordered> convenience classmethod creates a Group <#cyclopts.Group> with a sort_key <#cyclopts.Group.sort_key> value drawn drawn from a global monotonically increasing counter. This means that the order in the help-page will match the order that the groups were instantiated.

from cyclopts import App, Group

app = App()

plants = Group.create_ordered("Plants")
animals = Group.create_ordered("Animals")
fungi = Group.create_ordered("Fungi")

@app.command(group=animals)
def zebra():
    pass

@app.command(group=plants)
def daisy():
    pass

@app.command(group=fungi)
def portobello():
    pass

app()

$ my-script --help

Usage: scratch.py COMMAND

╭─ Plants ───────────────────────────────────────────────────────────╮
│ daisy                                                              │
╰────────────────────────────────────────────────────────────────────╯
╭─ Animals ──────────────────────────────────────────────────────────╮
│ zebra                                                              │
╰────────────────────────────────────────────────────────────────────╯
╭─ Fungi ────────────────────────────────────────────────────────────╮
│ portobello                                                         │
╰────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                          │
│ --version  Display application version.                            │
╰────────────────────────────────────────────────────────────────────╯

Even when using Group.create_ordered() <#cyclopts.Group.create_ordered>, a sort_key <#cyclopts.Group.sort_key> can still be supplied; the global counter will only be used to break sorting ties.

The Path <#cyclopts.validators.Path> validator ensures certain properties of the parsed pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> object, such as asserting the file must exist.

from cyclopts import App, Parameter, validators
from typing import Annotated
from pathlib import Path

app = App()

@app.default()
def foo(path: Annotated[Path, Parameter(validator=validators.Path(exists=True))]):
    print(f"File contents:\n{path.read_text()}")

app()

$ echo Hello World > my_file.txt

$ my-script my_file.txt
File contents:
Hello World

$ my-script this_file_does_not_exist.txt
╭─ Error ────────────────────────────────────────────────────────────╮
│ Invalid value "this_file_does_not_exist.txt" for "PATH".           │
│ "this_file_does_not_exist.txt" does not exist.                     │
╰────────────────────────────────────────────────────────────────────╯

See Annotated Path Types <#annotated-path-types> for Annotated-Type equivalents of common Path converter/validators.

The Number <#cyclopts.validators.Number> validator can set minimum and maximum input values.

from cyclopts import App, Parameter, validators
from typing import Annotated

app = App()

@app.default()
def foo(n: Annotated[int, Parameter(validator=validators.Number(gte=0, lt=16))]):
    print(f"Your number in hex is {str(hex(n))[2]}.")

app()

$ my-script 0
Your number in hex is 0.

$ my-script 15
Your number in hex is f.

$ my-script 16
╭─ Error ────────────────────────────────────────────────────────────╮
│ Invalid value "16" for "N". Must be < 16.                          │
╰────────────────────────────────────────────────────────────────────╯

See Annotated Number Types <#annotated-number-types> for Annotated-Type equivalents of common Number converter/validators.

Limits the number of specified arguments within the group. Most commonly used for mutually-exclusive arguments (default behavior).

from cyclopts import App, Group, Parameter, validators
from typing import Annotated

app = App()

vehicle = Group(
    "Vehicle (choose one)",
    default_parameter=Parameter(negative=""),  # Disable "--no-" flags
    validator=validators.LimitedChoice(),  # Mutually Exclusive Options
)

@app.default
def main(
    *,
    car: Annotated[bool, Parameter(group=vehicle)] = False,
    truck: Annotated[bool, Parameter(group=vehicle)] = False,
):
    if car:
        print("I'm driving a car.")
    if truck:
        print("I'm driving a truck.")

app()

$ python drive.py --help
Usage: main COMMAND [OPTIONS]

╭─ Commands ─────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                          │
│ --version  Display application version.                            │
╰────────────────────────────────────────────────────────────────────╯
╭─ Vehicle (choose one) ─────────────────────────────────────────────╮
│ --car    [default: False]                                          │
│ --truck  [default: False]                                          │
╰────────────────────────────────────────────────────────────────────╯

$ python drive.py --car
I'm driving a car.

$ python drive.py --car --truck
╭─ Error ────────────────────────────────────────────────────────────╮
│ Invalid values for group "Vehicle (choose one)". Mutually          │
│ exclusive arguments: {--car, --truck}                              │
╰────────────────────────────────────────────────────────────────────╯

See the LimitedChoice <#cyclopts.validators.LimitedChoice> docs for more info.

Alias for LimitedChoice <#cyclopts.validators.LimitedChoice> with default arguments. Exists primarily because the usage/implication will be more directly obvious and searchable to developers than LimitedChoice <#cyclopts.validators.LimitedChoice>. Since this class takes no arguments, an already instantiated version mutually_exclusive <#cyclopts.validators.mutually_exclusive> is also provided for convenience.

Group validator that enforces that either all parameters in the group must be supplied an argument, or none of them.

from typing import Annotated

from cyclopts import App, Group, Parameter
from cyclopts.validators import all_or_none

app = App()

group_1 = Group(validator=all_or_none)
group_2 = Group(validator=all_or_none)


@app.default
def default(
    foo: Annotated[bool, Parameter(group=group_1)] = False,
    bar: Annotated[bool, Parameter(group=group_1)] = False,
    fizz: Annotated[bool, Parameter(group=group_2)] = False,
    buzz: Annotated[bool, Parameter(group=group_2)] = False,
):
    print(f"{foo=} {bar=}")
    print(f"{fizz=} {buzz=}")


if __name__ == "__main__":
    app()

$ python all_or_none.py
foo=False bar=False
fizz=False buzz=False

$ python all_or_none.py --foo
╭─ Error ──────────────────────────────────────────────────────────╮
│ Missing argument: --bar                                          │
╰──────────────────────────────────────────────────────────────────╯

$ python all_or_none.py --foo --bar
foo=True bar=True
fizz=False buzz=False

$ python all_or_none.py --foo --bar --fizz
╭─ Error ────────────────────────────────────────────────────────────╮
│ Missing argument: --buzz                                           │
╰────────────────────────────────────────────────────────────────────╯

$ python all_or_none.py --foo --bar --fizz --buzz
foo=True bar=True
fizz=True buzz=True

See the all_or_none <#cyclopts.validators.all_or_none> docs for more info.

While the standard markup language for docstrings in Python is reStructuredText (see PEP-0287 <https://peps.python.org/pep-0287/>), Cyclopts defaults to Markdown for better readability and simplicity. Cyclopts mostly respects PEP-0257 <https://peps.python.org/pep-0257/>, but has some slight differences for developer ergonomics:

1. The "summary line" (AKA short-description) may actually be multiple lines. Cyclopts will unwrap the first block of text and interpret it as the short description. The first block of text ends at the first double-newline (i.e. a single blank line) is reached.

   def my_command():
       """
       This entire sentence
       is part of the short description and will
       have all the newlines removed.
   
       This is the beginning of the long description.
       """

2. If a docstring is provided with a long description, it must also have a short description.

By default, Cyclopts parses docstring descriptions as markdown and renders it appropriately. To change the markup format, set the App.help_format <#cyclopts.App.help_format> field accordingly. The different options are described below.

Subapps inherit their parent's App.help_format <#cyclopts.App.help_format> unless explicitly overridden. I.e. you only need to set App.help_format <#cyclopts.App.help_format> in your main root application for all docstrings to be parsed appropriately.

Do not perform any additional parsing, display supplied text as-is.

from cyclopts import App

app = App(help_format="plaintext")

@app.default
def default():
    """My application summary.

    This is a pretty standard docstring; if there's a really long sentence
    I should probably wrap it because people don't like code that is more
    than 80 columns long.

    In this new paragraph, I would like to discuss the benefits of relaxing 80 cols to 120 cols.
    More text in this paragraph.

    Some new paragraph.
    """

app()

Usage: default COMMAND

My application summary.

This is a pretty standard docstring; if there's a really long
sentence
I should probably wrap it because people don't like code that is
more
than 80 columns long.

In this new paragraph, I would like to discuss the benefits of
relaxing 80 cols to 120 cols.
More text in this paragraph.

Some new paragraph.

╭─ Commands ─────────────────────────────────────────────────────╮
│ --help,-h  Display this message and exit.                      │
│ --version  Display application version.                        │
╰────────────────────────────────────────────────────────────────╯

Most noteworthy, is no additional text reflow is performed; newlines are presented as-is.

Displays text as Rich Markup <https://rich.readthedocs.io/en/stable/markup.html>.

Note:

from cyclopts import App

app = App(help_format="rich")

@app.default
def default():
   """Rich can display colors like [red]red[/red] easily.

   However, I cannot be bothered to figure out how to show that in documentation.
   """

app()

ReStructuredText can be enabled by setting help_format to "restructuredtext" or "rst".

app = App(help_format="restructuredtext")  # or "rst"

@app.default
def default():
    """My application summary.

    We can do RST things like have **bold text**.
    More words in this paragraph.

    This is a new paragraph with some bulletpoints below:

    * bullet point 1.
    * bullet point 2.
    """

app()

Resulting help:

Under most circumstances, plaintext (without any additional markup) looks prettier and reflows better when interpreted as restructuredtext (or markdown, for that matter).

Markdown is the default parsing behavior of Cyclopts, so help_format won't need to be explicitly set. It's another popular markup language that Cyclopts can render.

app = App(help_format="markdown")  # or "md"
# or don't supply help_format at all; markdown is default.


@app.default
def default():
    """My application summary.

    We can do markdown things like have **bold text**.
    [Hyperlinks work as well.](https://cyclopts.readthedocs.io)
    """

Resulting help:

The default --help flags can be changed to different name(s) via the help_flags parameter.

app = cyclopts.App(help_flags="--show-help")
app = cyclopts.App(help_flags=["--send-help", "--send-help-plz", "-h"])

To disable the help-page entirely, set help_flags to an empty string or iterable.

app = cyclopts.App(help_flags="")
app = cyclopts.App(help_flags=[])

An epilogue is text displayed at the end of the help screen, after all command and parameter panels. This is commonly used for version information, support contact details, or additional notes.

The epilogue is set via the App.help_epilogue <#cyclopts.App.help_epilogue> attribute:

from cyclopts import App

app = App(
    name="myapp",
    help="My application description.",
    help_epilogue="Support: support@example.com"
)

@app.default
def main():
    """Main command."""
    pass

app()

$ myapp --help
Usage: myapp [ARGS]

My application description.

╭─ Commands ────────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                             │
│ --version  Display application version.                               │
╰───────────────────────────────────────────────────────────────────────╯

Support: support@example.com

Like App.help_format <#cyclopts.App.help_format>, epilogues inherit from parent to child apps. This allows you to set a single epilogue that applies across your entire application:

parent = App(
    name="myapp",
    help_epilogue="Version 1.0.0 | support@example.com"
)

# Child inherits parent's epilogue
child = App(name="process", help="Process data files.")
parent.command(child)

# Another child overrides with its own epilogue
admin = App(
    name="admin",
    help="Admin commands.",
    help_epilogue="Admin Tools v2.0 | USE WITH CAUTION"
)
parent.command(admin)

parent()

$ myapp process --help
Usage: myapp process

Process data files.

Version 1.0.0 | support@example.com    # Inherited from parent

$ myapp admin --help
Usage: myapp admin

Admin commands.

Admin Tools v2.0 | USE WITH CAUTION    # Overridden by child

To disable the epilogue for a specific subcommand, set it to an empty string:

no_epilogue = App(name="internal", help_epilogue="")
parent.command(no_epilogue)

For advanced customization of help screen appearance, including custom formatters, styled panels, and dynamic column layouts, see Help Customization <#help-customization>.

Shell completion systems (bash, zsh, fish) can only provide completion for installed commands (executables in your $PATH), not for arbitrary Python scripts like python myapp.py. This is a fundamental limitation of how shells work.

To work around this during development, Cyclopts provides a cyclopts run command that acts as a wrapper:

$ cyclopts run myapp.py --help
$ cyclopts run myapp.py:app --verbose

Since cyclopts itself is an installed command, the shell can provide completion for it. The cyclopts run command then loads and executes your script, giving you completion for your development scripts without needing to package and install them.

Script Path Format:

• cyclopts run script.py - Auto-detects the App object. If an App object cannot be determined, it will raise an error.
• cyclopts run script.py:app - Explicitly specifies the App object to run

This is particularly useful during development before packaging your application.

Virtual Environment Behavior:

cyclopts run imports your script directly into the same Python process (no subprocess is created). This means:

• It uses whatever Python interpreter is currently running cyclopts
• Your script has access to all packages installed in the current environment
• You must install cyclopts in your project's virtual environment

• To use: activate your venv, then run cyclopts run script.py

  $ source .venv/bin/activate  # or your venv activation method
  $ cyclopts run myapp.py

Note:

Completion for your script's commands comes through the cyclopts CLI completion. Install it once with: cyclopts --install-completion

Warning:

Performance: cyclopts run uses dynamic completion, which imports your script and calls Python on every tab press. This can be slow if your script has heavy imports.

To mitigate slow imports during development, consider using Lazy Loading <#lazy-loading> for your commands. For production or frequent use, install static completion using the methods below. Static completion is pre-generated and does not call Python, making it instantaneous.

To install completion specifically for your standalone script (without using cyclopts run), you can use the Manual Installation approach below with your script's App object.

Add completion installation to your CLI application using App.register_install_completion_command <#cyclopts.App.register_install_completion_command>:

from cyclopts import App

app = App(name="myapp")
app.register_install_completion_command()

# Your commands here...

if __name__ == "__main__":
    app()

Users can then install completion by running:

myapp --install-completion

For programmatic control, use App.install_completion <#cyclopts.App.install_completion> directly:

from cyclopts import App
from pathlib import Path

app = App(name="myapp")

# Install for current shell
install_path = app.install_completion()
print(f"Installed completion to {install_path}")

# Install for specific shell
install_path = app.install_completion(shell="zsh")

# Install to custom location
install_path = app.install_completion(
    shell="bash",
    output=Path("/custom/path/completion.sh"),
)

• Zsh: ~/.zsh/completions/_<app_name>
• Bash: ~/.local/share/bash-completion/completions/<app_name>
• Fish: ~/.config/fish/completions/<app_name>.fish

To generate a completion script without installing it, use App.generate_completion <#cyclopts.App.generate_completion>:

from cyclopts import App

app = App(name="myapp")
script = app.generate_completion(shell="zsh")
print(script)

By default, Cyclopts modifies your shell RC file to enable completion:

• Zsh: Adds to ~/.zshrc
• Bash: Adds to ~/.bashrc
• Fish: No modification needed (automatically loads from ~/.config/fish/completions/)

After installation, restart your shell or source the RC file.

To install without modifying shell RC files, use:

app.register_install_completion_command(add_to_startup=False)

If no explicit type hint is provided:

• If the parameter has a non-None default value, interpret the type as type(default_value).

  from cyclopts import App
  
  app = App()
  
  @app.default
  def default(value=5):
      print(f"{value=} {type(value)=}")
  
  app()

  $ my-program 3
  value=3 type(value)=<class 'int'>

• Otherwise, interpret the type as string.

  from cyclopts import App
  
  app = App()
  
  @app.default
  def default(value):
      print(f"{value=} {type(value)=}")
  
  app()

  $ my-program foo
  value='foo' type(value)=<class 'str'>

A standalone Any type hint is equivalent to No Hint

No operation is performed, CLI tokens are natively strings.

from cyclopts import App

app = App()

@app.default
def default(value: str):
    print(f"{value=} {type(value)=}")

app()

$ my-program foo
value='foo' type(value)=<class 'str'>

For convenience, Cyclopts provides a richer feature-set of parsing integers than just naively calling int.

• Accepts vanilla decimal values (e.g. 123, 3.1415). Floating-point values will be rounded prior to casting to an int.
• Accepts binary values (strings starting with 0b)
• Accepts octal values (strings starting with 0o)
• Accepts hexadecimal values (strings starting with 0x).

For parameters that need to track the number of times a flag appears (e.g., verbosity levels like -vvv), use Parameter.count <#cyclopts.Parameter.count> with an int <https://docs.python.org/3/library/functions.html#int> type hint.

from cyclopts import App, Parameter
from typing import Annotated

app = App()

@app.default
def main(verbose: Annotated[int, Parameter(alias="-v", count=True)] = 0):
    print(f"Verbosity level: {verbose}")

app()

$ my-program
Verbosity level: 0

$ my-program -v
Verbosity level: 1

$ my-program -vvv
Verbosity level: 3

$ my-program --verbose --verbose
Verbosity level: 2

$ my-program -v --verbose -vv
Verbosity level: 4

Token gets cast as float(token). For example, float("3.14").

Token gets cast as complex(token). For example, complex("3+5j")

1. If specified as a keyword, booleans are interpreted flags that take no parameter. The default false-like flag are --no-FLAG-NAME. See Parameter.negative <#cyclopts.Parameter.negative> for more about this feature.

   Example:

   from cyclopts import App
   
   app = App()
   
   @app.command
   def foo(my_flag: bool):
       print(my_flag)
   
   app()

   $ my-program foo --my-flag
   True
   
   $ my-program foo --no-my-flag
   False

2. If specified as a positional argument, a case-insensitive lookup is performed:

   • If the token is a true-like value {"yes", "y", "1", "true", "t"}, then it is parsed as True <https://docs.python.org/3/library/constants.html#True>.
   • If the token is a false-like value {"no", "n", "0", "false", "f"}, then it is parsed as False <https://docs.python.org/3/library/constants.html#False>.
   • Otherwise, a CoercionError <#cyclopts.CoercionError> will be raised.

   Cyclopts is stricter than traditional bool <https://docs.python.org/3/library/functions.html#bool> casting; the provided value must be one of the above. For example, 2 is not considered a true-like value and will raise an error.

   $ my-program foo 1
   True
   
   $ my-program foo 0
   False
   
   $ my-program foo 2
   ╭─ Error ───────────────────────────────────────╮
   │ Invalid value for "--my-flag": unable to      │
   │ convert "2" into bool.                        │
   ╰───────────────────────────────────────────────╯
   
   $ my-program foo not-a-true-or-false-value
   ╭─ Error ─────────────────────────────────────────────────╮
   │ Invalid value for "--my-flag": unable to convert        │
   │ "not-a-true-or-false-value" into bool.                  │
   ╰─────────────────────────────────────────────────────────╯

3. If specified as a keyword with a value attached with an =, then the provided value will be parsed according to positional argument rules above (2).

   from cyclopts import App
   
   app = App()
   
   @app.command
   def foo(my_flag: bool):
       print(my_flag)
   
    app()

   $ my-program foo --my-flag=true
   True
   
   $ my-program foo --my-flag=false
   False
   
   $ my-program foo --no-my-flag=true
   False
   
   $ my-program foo --no-my-flag=false
   True

Unlike more simple types like str <https://docs.python.org/3/library/stdtypes.html#str> and int <https://docs.python.org/3/library/functions.html#int>, lists use different parsing rules depending on whether the values are provided positionally or by keyword.

When arguments are provided positionally:

• If Parameter.allow_leading_hyphen <#cyclopts.Parameter.allow_leading_hyphen> is False <https://docs.python.org/3/library/constants.html#False> (default behavior), reaching an option-like token will stop parsing for this parameter. If the number of consumed tokens is not a multiple of the required number of tokens to create an element of the list, a MissingArgumentError <#cyclopts.MissingArgumentError> will be raised.

  from cyclopts import App
  
  app = App()
  
  @app.command
  def foo(values: list[int]):  # 1 CLI token per element
     print(values)
  
  @app.command
  def bar(values: list[tuple[int, str]]):  # 2 CLI tokens per element
     print(values)
  
  app()

  $ my-program foo 1 2 3
  [1, 2, 3]
  
  $ my-program bar 1 one 2 two
  [(1, 'one'), (2, 'two')]
  
  $ my-program bar 1 one 2
  ╭─ Error ─────────────────────────────────────────────────────╮
  │ Command "bar" parameter "--values" requires 2 arguments.    │
  │ Only got 1.                                                 │
  ╰─────────────────────────────────────────────────────────────╯

• If Parameter.allow_leading_hyphen <#cyclopts.Parameter.allow_leading_hyphen> is True <https://docs.python.org/3/library/constants.html#True>, CLI tokens will be consumed unconditionally until exhausted.

  from cyclopts import App, Parameter
  from pathlib import Path
  from typing import Annotated
  
  app = App()
  
  @app.default
  def main(
     files: Annotated[list[Path], Parameter(allow_leading_hyphen=True)],
     some_flag: bool = False,
   ):
     print(f"{some_flag=}")
     print(f"Analyzing files {files}")
  
  app()

  $ my-program foo.bin bar.bin --fizz.bin buzz.bin --some-flag
  some_flag=True
  Analyzing files [PosixPath('foo.bin'), PosixPath('bar.bin'), PosixPath('--fizz.bin'), PosixPath('buzz.bin')]

  Known keyword arguments are parsed first (in this case, --some-flag). To unambiguously pass in values positionally, provide them after a bare --:

  $ my-program -- foo.bin bar.bin --fizz.bin buzz.bin --some-flag
  some_flag=False
  Analyzing files [PosixPath('foo.bin'), PosixPath('bar.bin'), PosixPath('--fizz.bin'), PosixPath('buzz.bin'), PosixPath('--some-flag')]

When arguments are provided by keyword:

• Tokens will be consumed until enough data is collected to form the type-hinted object.
• The keyword can be specified multiple times.

• If Parameter.allow_leading_hyphen <#cyclopts.Parameter.allow_leading_hyphen> is False <https://docs.python.org/3/library/constants.html#False> (default behavior), reaching an option-like token will raise MissingArgumentError <#cyclopts.MissingArgumentError> if insufficient tokens have been parsed.

  from cyclopts import App
  
  app = App()
  
  @app.command
  def foo(values: list[int]):  # 1 CLI token per element
     print(values)
  
  @app.command
  def bar(values: list[tuple[int, str]]):  # 2 CLI tokens per element
     print(values)
  
  app()

  $ my-program foo --values 1 --values 2 --values 3
  [1, 2, 3]
  
  $ my-program bar --values 1 one --values 2 two
  [(1, 'one'), (2, 'two')]
  
  $ my-program bar --values 1 --values 2
  ╭─ Error ─────────────────────────────────────────────────────╮
  │ Command "bar" parameter "--values" requires 2 arguments.    │
  │ Only got 1.                                                 │
  ╰─────────────────────────────────────────────────────────────╯

• If Parameter.consume_multiple <#cyclopts.Parameter.consume_multiple> is True <https://docs.python.org/3/library/constants.html#True>, all remaining tokens will be consumed (until an option-like token is reached if Parameter.allow_leading_hyphen <#cyclopts.Parameter.allow_leading_hyphen> is False <https://docs.python.org/3/library/constants.html#False>)

  from cyclopts import App, Parameter
  from typing import Annotated
  
  app = App()
  
  @app.default
  def foo(values: Annotated[list[int], Parameter(consume_multiple=True)]):  # 1 CLI token per element
     print(values)
  
  app()

  $ my-program foo --values 1 2 3
  [1, 2, 3]

Commonly, if we want a default list for a parameter in a function, we set the default value to None in the signature and then set it to the actual list in the function body:

def foo(extensions: Optional[list] = None):
   if extensions is None:
      extensions = [".png", ".jpg"]

We do this because mutable defaults is a common unexpected source of bugs in python <https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments>.

However, sometimes we actually want to specify an empty list. To get an empty list pass in the flag --empty-MY-LIST-NAME.

from cyclopts import App

app = App()

@app.default
def main(extensions: list | None = None):
   if extensions is None:
      extensions = [".png", ".jpg"]
   print(f"{extensions=}")

app()

$ my-program
extensions=['.png', '.jpg']

$ my-program --empty-extensions
extensions=[]

See Parameter.negative <#cyclopts.Parameter.negative> for more about this feature.

When a list is positional-only, it will consume tokens such that it leaves enough tokens for subsequent positional-only parameters.

from pathlib import Path
from cyclopts import App

app = App()

@app.default
def main(srcs: list[Path], dst: Path, /):  # "/" makes all prior parameters POSITIONAL_ONLY
    print(f"Processing files {srcs!r} to {dst!r}.")

app()

$ my-program foo.bin bar.bin output.bin
Processing files [PosixPath('foo.bin'), PosixPath('bar.bin')] to PosixPath('output.bin').

The console wildcard * is expanded by the console, so this example will naturally work with wildcards.

$ ls foo
buzz.bin fizz.bin

$ my-program foo/*.bin output.bin
Processing files [PosixPath('foo/buzz.bin'), PosixPath('foo/fizz.bin')] to PosixPath('output.bin').

Follows the same rules as List. The passed in data will be a list <https://docs.python.org/3/library/stdtypes.html#list>.

Follows the same rules as List. The passed in data will be a list <https://docs.python.org/3/library/stdtypes.html#list>.

Follows the same rules as List, but the resulting datatype is a set <https://docs.python.org/3/library/stdtypes.html#set>.

Follows the same rules as Set, but the resulting datatype is a frozenset <https://docs.python.org/3/library/stdtypes.html#frozenset>.

• The inner type hint(s) will be applied independently to each element. Enough CLI tokens will be consumed to populate the inner types.
• Nested fixed-length tuples are allowed: E.g. tuple[tuple[int, str], str] will consume 3 CLI tokens.

• Indeterminite-size tuples tuple[type, ...] are only supported at the root-annotation level and behave similarly to List.

  from cyclopts import App
  
  app = App()
  
  @app.default
  def default(coordinates: tuple[float, float, str]):
     print(f"{coordinates=}")
  
  app()

And invoke our script:

$ my-program --coordinates 3.14 2.718 my-coord-name
coordinates=(3.14, 2.718, 'my-coord-name')

Cyclopts can populate dictionaries using keyword dot-notation:

from cyclopts import App

app = App()

@app.default
def default(message: str, *, mapping: dict[str, str] | None = None):
    if mapping:
        for find, replace in mapping.items():
            message = message.replace(find, replace)
    print(message)

app()

$ my_program 'Hello Cyclopts users!'
Hello Cyclopts users!

$ my_program 'Hello Cyclopts users!' --mapping.Hello Hey
Hey Cyclopts users!

$ my_program 'Hello Cyclopts users!' --mapping.Hello Hey --mapping.users developers
Hey Cyclopts developers!

Due to the way of specifying keys, it is recommended to make dict parameters keyword-only; dicts cannot be populated positionally. If you do not wish for the user to be able to specify arbitrary keys, see User-Defined Classes. For specifying arbitrary keywords at the root level, see kwargs <#args-kwargs-kwargs>.

The unioned types will be iterated left-to-right until a successful coercion is performed. None <https://docs.python.org/3/library/constants.html#None> type hints are ignored.

from cyclopts import App
from typing import Union

app = App()

@app.default
def default(a: Union[None, int, str]):
    print(type(a))

app()

$ my-program 10
<class 'int'>

$ my-program bar
<class 'str'>

Optional[...] is syntactic sugar for Union[..., None].  See Union rules.

The Literal <https://docs.python.org/3/library/typing.html#typing.Literal> type is a good option for limiting user input to a set of choices. Like Union, the Literal <https://docs.python.org/3/library/typing.html#typing.Literal> options will be iterated left-to-right until a successful coercion is performed. Cyclopts attempts to coerce the input token into the type of each Literal <https://docs.python.org/3/library/typing.html#typing.Literal> option.

from cyclopts import App
from typing import Literal

app = App()

@app.default
def default(value: Literal["foo", "bar", 3]):
    print(f"{value=} {type(value)=}")

app()

$ my-program foo
value='foo' type(value)=<class 'str'>

$ my-program bar
value='bar' type(value)=<class 'str'>

$ my-program 3
value=3 type(value)=<class 'int'>

$ my-program fizz
╭─ Error ─────────────────────────────────────────────────╮
│ Invalid value for "VALUE": unable to convert "fizz"     │
│ into one of {'foo', 'bar', 3}.                          │
╰─────────────────────────────────────────────────────────╯

While Literal is the recommended way of providing the user a set of choices, another method is using Enum <https://docs.python.org/3/library/enum.html#enum.Enum>.

The Parameter.name_transform <#cyclopts.Parameter.name_transform> gets applied to all Enum <https://docs.python.org/3/library/enum.html#enum.Enum> names, as well as the CLI provided token. By default,this means that a case-insensitive name lookup is performed. If an enum name contains an underscore, the CLI parameter may instead contain a hyphen, -. Leading/Trailing underscores will be stripped.

If coming from Typer <https://typer.tiangolo.com>, Cyclopts Enum handling is the reverse of Typer. Typer attempts to match the token to an Enum value; Cyclopts attempts to match the token to an Enum name. This is done because generally the name of the enum is meant to be human readable, while the value has some program/machine significance.

As a real-world example, the PNG image format supports 5 different color-types <https://www.w3.org/TR/2003/REC-PNG-20031110/#6Colour-values>, which gets encoded into a 1-byte int in the image header <https://www.w3.org/TR/2003/REC-PNG-20031110/#11IHDR>.

from cyclopts import App
from enum import IntEnum

app = App()

class ColorType(IntEnum):
    GRAYSCALE = 0
    RGB = 2
    PALETTE = 3
    GRAYSCALE_ALPHA = 4
    RGBA = 6

@app.default
def default(color_type: ColorType = ColorType.RGB):
    print(f"Writing color-type value: {color_type} to the image header.")

app()

$ my-program
Writing color-type value: 2 to the image header.

$ my-program grayscale-alpha
Writing color-type value: 4 to the image header.

Flag <https://docs.python.org/3/library/enum.html#enum.Flag> enums (and by extension, IntFlag <https://docs.python.org/3/library/enum.html#enum.IntFlag>) are treated as a collection of boolean flags.

The Parameter.name_transform <#cyclopts.Parameter.name_transform> gets applied to all Flag <https://docs.python.org/3/library/enum.html#enum.Flag> names, as well as the CLI provided token. By default, this means that a case-insensitive name lookup is performed. If an enum name contains an underscore, the CLI parameter may instead contain a hyphen, -. Leading/Trailing underscores will be stripped.

from cyclopts import App
from enum import Flag, auto

app = App()

class Permission(Flag):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()

@app.default
def default(permissions: Permission = Permission.READ):
    print(f"Permissions: {permissions}")

app()

$ my-program
Permissions: Permission.READ

$ my-program write
Permissions: Permission.WRITE

$ my-program read write
Permissions: Permission.READ|WRITE

$ my-program --permissions.write
Permissions: Permission.WRITE

$ my-program --permissions.write --permissions.read
Permissions: Permission.READ|WRITE

Note:

If you want to directly expose the flags as booleans (e.g. --read), then see Namespace Flattening <#namespace-flattening>.

Cyclopts supports parsing dates into a date <https://docs.python.org/3/library/datetime.html#datetime.date> object. It uses fromisoformat() <https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat> under the hood, so the only supported format is %Y-%m-%d (e.g. 1956-01-31). However, if you use newer Python (>= 3.11), it also supports other formats such as %Y%m%d (e.g., 20191204), 2021-W01-1, etc, defined by ISO 8601.

Cyclopts supports parsing timestamps into a datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime> object. The supplied time must be in one of the following formats:

• %Y-%m-%d (e.g. 1956-01-31)
• %Y-%m-%dT%H:%M:%S (e.g. 1956-01-31T10:00:00)
• %Y-%m-%d %H:%M:%S  (e.g. 1956-01-31 10:00:00)
• %Y-%m-%dT%H:%M:%S%z  (e.g. 1956-01-31T10:00:00+0000)
• %Y-%m-%dT%H:%M:%S.%f  (e.g. 1956-01-31T10:00:00.123456)
• %Y-%m-%dT%H:%M:%S.%f%z  (e.g. 1956-01-31T10:00:00.123456+0000)

Cyclopts supports parsing time durations into a timedelta <https://docs.python.org/3/library/datetime.html#datetime.timedelta> object. The supplied time must be in one of the following formats:

• 30s - 30 seconds
• 5m - 5 minutes
• 2h - 2 hours
• 1d - 1 day
• 3w - 3 weeks
• 6M - 6 months (approximate)
• 1y - 1 year (approximate)

Combining durations is also supported:

• "1h30m" - 1 hour and 30 minutes
• "1d12h" - 1 day and 12 hours

Cyclopts supports classically defined user classes, as well as classes defined by the following dataclass-like libraries:

• attrs <https://www.attrs.org/en/stable/>
• dataclass <https://docs.python.org/3/library/dataclasses.html>
• NamedTuple <https://docs.python.org/3/library/typing.html#typing.NamedTuple>
• pydantic <https://docs.pydantic.dev/latest/>
• TypedDict <https://docs.python.org/3/library/typing.html#typing.TypedDict>

Note:

For pydantic classes, Cyclopts will not internally perform type conversions and instead relies on pydantic's coercion engine.

Subkey parsing allows for assigning values positionally and by keyword with a dot-separator.

from cyclopts import App
from dataclasses import dataclass
from typing import Literal

app = App()

@dataclass
class User:
   name: str
   age: int
   region: Literal["us", "ca"] = "us"

@app.default
def main(user: User):
   print(user)

app()

$ my-program --help
Usage: main COMMAND [ARGS] [OPTIONS]

╭─ Commands ──────────────────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                                       │
│ --version  Display application version.                                         │
╰─────────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────────────────────────────╮
│ *  USER.NAME --user.name      [required]                                        │
│ *  USER.AGE --user.age        [required]                                        │
│    USER.REGION --user.region  [choices: us, ca] [default: us]                   │
╰─────────────────────────────────────────────────────────────────────────────────╯

$ my-program 'Bob Smith' 30
User(name='Bob Smith', age=30, region='us')

$ my-program --user.name 'Bob Smith' --user.age 30
User(name='Bob Smith', age=30, region='us')

$ my-program --user.name 'Bob Smith' 30 --user.region=ca
User(name='Bob Smith', age=30, region='ca')

Cyclopts will recursively search for Parameter <#cyclopts.Parameter> annotations and respect them:

from cyclopts import App, Parameter
from dataclasses import dataclass
from typing import Annotated

app = App()

@dataclass
class User:
   # Beginning with "--" will completely override the parenting parameter name.
   name: Annotated[str, Parameter(name="--nickname")]
   # Not beginning with "--" will tack it on to the parenting parameter name.
   age: Annotated[int, Parameter(name="years-young")]

@app.default
def main(user: Annotated[User, Parameter(name="player")]):
   print(user)

app()

$ my-program --help
Usage: main COMMAND [ARGS] [OPTIONS]

╭─ Commands ────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                 │
│ --version  Display application version.                   │
╰───────────────────────────────────────────────────────────╯
╭─ Parameters ──────────────────────────────────────────────╮
│ *  NICKNAME --nickname     [required]                     │
│ *  PLAYER.YEARS-YOUNG      [required]                     │
│      --player.years-young                                 │
╰───────────────────────────────────────────────────────────╯

The special parameter name "*" will remove the immediate parameter's name from the dotted-hierarchal name:

from cyclopts import App, Parameter
from dataclasses import dataclass
from typing import Annotated

app = App()

@dataclass
class User:
   name: str
   age: int

@app.default
def main(user: Annotated[User, Parameter(name="*")]):
   print(user)

app()

$ my-program --help
Usage: main COMMAND [ARGS] [OPTIONS]

╭─ Commands ─────────────────────────────────────────────╮
│ --help -h  Display this message and exit.              │
│ --version  Display application version.                │
╰────────────────────────────────────────────────────────╯
╭─ Parameters ───────────────────────────────────────────╮
│ *  NAME --name  [required]                             │
│ *  AGE --age    [required]                             │
╰────────────────────────────────────────────────────────╯

This can be used to conveniently share parameters between commands, and to create a global config object. See Sharing Parameters <#sharing-parameters>.

Docstrings from the class are used for the help page. Docstrings from the command have priority over class docstrings, if supplied:

from cyclopts import App
from dataclasses import dataclass

app = App()

@dataclass
class User:
   name: str
   "First and last name of the user."

   age: int
   "Age in years of the user."

@app.default
def main(user: User):
   """A short summary of what this program does.

   Parameters
   ----------
   user.age: int
      User's age docstring from the command docstring.
   """
   print(user)

app()

$ my-program --help
Usage: main COMMAND [ARGS] [OPTIONS]

A short summary of what this program does.

╭─ Commands ──────────────────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                                       │
│ --version  Display application version.                                         │
╰─────────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ────────────────────────────────────────────────────────────────────╮
│ *  USER.NAME --user.name  First and last name of the user. [required]           │
│ *  USER.AGE --user.age    User's age docstring from the command docstring.      │
│                           [required]                                            │
╰─────────────────────────────────────────────────────────────────────────────────╯

If the class is annotated with Parameter(accepts_keys=False), then no dot-notation subkeys are exported. The class parameter will consume enough tokens to populate the required positional arguments.

from cyclopts import App, Parameter
from dataclasses import dataclass
from typing import Annotated, Literal

app = App()

@dataclass
class User:
   name: str
   age: int
   region: Literal["us", "ca"] = "us"

@app.default
def main(user: Annotated[User, Parameter(accepts_keys=False)]):
   print(user)

app()

$ my-program --help
Usage: main COMMAND [ARGS] [OPTIONS]

╭─ Commands ─────────────────────────────────────────────────────────────────────╮
│ --help -h  Display this message and exit.                                      │
│ --version  Display application version.                                        │
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ───────────────────────────────────────────────────────────────────╮
│ *  USER --user  [required]                                                     │
╰────────────────────────────────────────────────────────────────────────────────╯

$ my-program 'Bob Smith' 27
User(name='Bob Smith', age=27, region='us')

$ my-program 'Bob Smith'
╭─ Error ────────────────────────────────────────────────────────────────────────╮
│ Parameter "--user" requires 2 arguments. Only got 1.                           │
╰────────────────────────────────────────────────────────────────────────────────╯

In this example, we are unable to change the region parameter of User from the CLI.

Cyclopts has several builtin validators for common CLI inputs.

class cyclopts.validators.LimitedChoice(min: int <https://docs.python.org/3/library/functions.html#int> = 0, max: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, allow_none: bool <https://docs.python.org/3/library/functions.html#bool> = False)

Group validator that limits the number of selections per group.

Commonly used for enforcing mutually-exclusive parameters (default behavior).

Parameters

• min (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum (inclusive) number of CLI parameters allowed. If negative, then all parameters in the group must have CLI values provided.
• max (int <https://docs.python.org/3/library/functions.html#int> | None) -- The maximum (inclusive) number of CLI parameters allowed. Defaults to 1 if min==0, min otherwise.
• allow_none (bool <https://docs.python.org/3/library/functions.html#bool>) -- If True <https://docs.python.org/3/library/constants.html#True>, also allow 0 CLI parameters (even if min is greater than 0). Defaults to False <https://docs.python.org/3/library/constants.html#False>.

class cyclopts.validators.MutuallyExclusive

Alias for LimitedChoice to make intentions more obvious.

Only 1 argument in the group can be supplied a value.

cyclopts.validators.mutually_exclusive = <cyclopts.validators._group.MutuallyExclusive object>

Instantiated version of MutuallyExclusive. Can be used directly in group validators:

import cyclopts
from cyclopts import Group

mutually_exclusive_group = Group(validator=cyclopts.validators.mutually_exclusive)

cyclopts.validators.all_or_none = <cyclopts.validators._group.LimitedChoice object>

Group validator that enforces that either all parameters in the group must be supplied an argument, or none of them.

class cyclopts.validators.Number(*, lt: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None> = None, lte: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None> = None, gt: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None> = None, gte: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None> = None, modulo: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None> = None)

Limit input number to a value range.

Example Usage:

from cyclopts import App, Parameter, validators
from typing import Annotated

app = App()


@app.default
def main(age: Annotated[int, Parameter(validator=validators.Number(gte=0, lte=150))]):
    print(f"You are {age} years old.")


app()

$ my-script 100
You are 100 years old.

$ my-script -1
╭─ Error ───────────────────────────────────────────────────────╮
│ Invalid value "-1" for "AGE". Must be >= 0.                   │
╰───────────────────────────────────────────────────────────────╯

$ my-script 200
╭─ Error ───────────────────────────────────────────────────────╮
│ Invalid value "200" for "AGE". Must be <= 150.                │
╰───────────────────────────────────────────────────────────────╯

lt: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None>

Input value must be less than this value.

lte: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None>

Input value must be less than or equal this value.

gt: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None>

Input value must be greater than this value.

gte: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None>

Input value must be greater than or equal this value.

modulo: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None>

Input value must be a multiple of this value.

class cyclopts.validators.Path(*, exists: bool <https://docs.python.org/3/library/functions.html#bool> = False, file_okay: bool <https://docs.python.org/3/library/functions.html#bool> = True, dir_okay: bool <https://docs.python.org/3/library/functions.html#bool> = True, ext: None <https://docs.python.org/3/library/constants.html#None> | Any <https://docs.python.org/3/library/typing.html#typing.Any> | Iterable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable>[Any <https://docs.python.org/3/library/typing.html#typing.Any>] = None)

Assertions on properties of pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>.

Example Usage:

from cyclopts import App, Parameter, validators
from pathlib import Path
from typing import Annotated

app = App()


@app.default
def main(
    # ``src`` must be a file that exists.
    src: Annotated[Path, Parameter(validator=validators.Path(exists=True, dir_okay=False))],
    # ``dst`` must be a path that does **not** exist.
    dst: Annotated[Path, Parameter(validator=validators.Path(dir_okay=False, file_okay=False))],
):
    "Copies src->dst."
    dst.write_bytes(src.read_bytes())


app()

$ my-script foo.bin bar.bin  # if foo.bin does not exist
╭─ Error ───────────────────────────────────────────────────────╮
│ Invalid value "foo.bin" for "SRC". "foo.bin" does not exist.  │
╰───────────────────────────────────────────────────────────────╯

$ my-script foo.bin bar.bin  # if bar.bin exists
╭─ Error ───────────────────────────────────────────────────────╮
│ Invalid value "bar.bin" for "DST". "bar.bin" already exists.  │
╰───────────────────────────────────────────────────────────────╯

exists: bool <https://docs.python.org/3/library/functions.html#bool>

If True <https://docs.python.org/3/library/constants.html#True>, specified path must exist. Defaults to False <https://docs.python.org/3/library/constants.html#False>.

file_okay: bool <https://docs.python.org/3/library/functions.html#bool>

If path exists, check it's type:

• If True <https://docs.python.org/3/library/constants.html#True>, specified path may be an existing file.
• If False <https://docs.python.org/3/library/constants.html#False>, then existing files are not allowed.

Defaults to True <https://docs.python.org/3/library/constants.html#True>.

dir_okay: bool <https://docs.python.org/3/library/functions.html#bool>

If path exists, check it's type:

• If True <https://docs.python.org/3/library/constants.html#True>, specified path may be an existing directory.
• If False <https://docs.python.org/3/library/constants.html#False>, then existing directories are not allowed.

Defaults to True <https://docs.python.org/3/library/constants.html#True>.

ext: str <https://docs.python.org/3/library/stdtypes.html#str> | Sequence <https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence>[str <https://docs.python.org/3/library/stdtypes.html#str>]

Supplied path must have this extension (case insensitive). May or may not include the ".".

Cyclopts has builtin pre-defined annotated-types for common conversion and validation configurations. Most definitions in this section are simply predefined annotations for convenience:

Annotated[..., Parameter(...)]

Custom classes that provide additional functionality beyond simple annotations will be noted.

Due to Cyclopts's advanced Parameter resolution engine, these annotations can themselves be annotated to further configure behavior. E.g:

Annotated[PositiveInt, Parameter(...)]

Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> annotated types for checking existence, type, and performing path-resolution. All of these types will also work on sequence of paths (e.g. tuple[Path, Path] or list[Path]).

class cyclopts.types.StdioPath

Note:

This is a custom class, not a simple Annotated <https://docs.python.org/3/library/typing.html#typing.Annotated> type alias.

Requires Python 3.12+ due to Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> subclassing support.

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> subclass that treats - as stdin (for reading) or stdout (for writing). This follows common Unix convention <https://clig.dev/#arguments-and-flags>.

StdioPath is pre-configured with allow_leading_hyphen=True, so - can be passed as an argument without being interpreted as an option.

STDIO_STRING: str <https://docs.python.org/3/library/stdtypes.html#str> = "-"

Class attribute defining the string that triggers stdio behavior. Override in subclasses to use a different string.

is_stdio: bool <https://docs.python.org/3/library/functions.html#bool>

Returns True <https://docs.python.org/3/library/constants.html#True> if this path represents stdin/stdout (i.e., str(self) == STDIO_STRING). Override this property in subclasses for custom matching logic (e.g., matching multiple strings).

Basic usage:

from cyclopts import App
from cyclopts.types import StdioPath

app = App()

@app.default
def main(input_file: StdioPath):
    data = input_file.read_text()
    print(data.upper())

app()

$ echo "hello" | python my_script.py -
HELLO

$ python my_script.py data.txt
<contents of data.txt uppercased>

To default to stdin/stdout when no argument is provided:

@app.default
def main(input_file: StdioPath = StdioPath("-")):
    data = input_file.read_text()
    print(data.upper())

See Reading/Writing From File or Stdin/Stdout <#reading-writing-from-file-or-stdin-stdout> for more examples.

Subclassing

To use a different trigger string or custom matching logic, subclass StdioPath:

from cyclopts.types import StdioPath

# Simple: different trigger string
class StdinPath(StdioPath):
    STDIO_STRING = "STDIN"

class StdoutPath(StdioPath):
    STDIO_STRING = "STDOUT"

# Advanced: match multiple strings
class MultiStdioPath(StdioPath):
    @property
    def is_stdio(self) -> bool:
        return str(self) in ("-", "STDIN", "STDOUT")

cyclopts.types.ExistingPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file or directory that must exist.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=True, ext=()),))]

cyclopts.types.NonExistentPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file or directory that must not exist.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=()),))]

cyclopts.types.ResolvedPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file or directory. resolve() <https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve> is invoked prior to returning the path.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(converter=<function _path_resolve_converter at 0x7f8742aa9d20>)]

cyclopts.types.ResolvedExistingPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file or directory that must exist. resolve() <https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve> is invoked prior to returning the path.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=True, ext=()),)), Parameter(converter=<function _path_resolve_converter at 0x7f8742aa9d20>)]

cyclopts.types.Directory

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must be a directory (or not exist).

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=True, ext=()),))]

cyclopts.types.ExistingDirectory

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> directory that must exist.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=False, dir_okay=True, ext=()),))]

cyclopts.types.NonExistentDirectory

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> directory that must not exist.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=()),))]

cyclopts.types.ResolvedDirectory

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> directory. resolve() <https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve> is invoked prior to returning the path.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=True, ext=()),)), Parameter(converter=<function _path_resolve_converter at 0x7f8742aa9d20>)]

cyclopts.types.ResolvedExistingDirectory

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> directory that must exist. resolve() <https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve> is invoked prior to returning the path.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=False, dir_okay=True, ext=()),)), Parameter(converter=<function _path_resolve_converter at 0x7f8742aa9d20>)]

cyclopts.types.File

A File that must be a file (or not exist).

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=()),))]

cyclopts.types.ExistingFile

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file that must exist.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=()),))]

cyclopts.types.NonExistentFile

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file that must not exist.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=()),))]

cyclopts.types.ResolvedFile

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file. resolve() <https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve> is invoked prior to returning the path.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=()),)), Parameter(converter=<function _path_resolve_converter at 0x7f8742aa9d20>)]

cyclopts.types.ResolvedExistingFile

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> file that must exist. resolve() <https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve> is invoked prior to returning the path.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=()),)), Parameter(converter=<function _path_resolve_converter at 0x7f8742aa9d20>)]

cyclopts.types.BinPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension bin.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('bin',)),))]

cyclopts.types.ExistingBinPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension bin.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('bin',)),))]

cyclopts.types.NonExistentBinPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension bin.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('bin',)),))]

cyclopts.types.CsvPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension csv.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('csv',)),))]

cyclopts.types.ExistingCsvPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension csv.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('csv',)),))]

cyclopts.types.NonExistentCsvPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension csv.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('csv',)),))]

cyclopts.types.TxtPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension txt.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('txt',)),))]

cyclopts.types.ExistingTxtPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension txt.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('txt',)),))]

cyclopts.types.NonExistentTxtPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension txt.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('txt',)),))]

cyclopts.types.ImagePath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension in {png, jpg, jpeg}.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('png', 'jpg', 'jpeg')),))]

cyclopts.types.ExistingImagePath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension in {png, jpg, jpeg}.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('png', 'jpg', 'jpeg')),))]

cyclopts.types.NonExistentImagePath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension in {png, jpg, jpeg}.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('png', 'jpg', 'jpeg')),))]

cyclopts.types.Mp4Path

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension mp4.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('mp4',)),))]

cyclopts.types.ExistingMp4Path

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension mp4.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('mp4',)),))]

cyclopts.types.NonExistentMp4Path

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension mp4.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('mp4',)),))]

cyclopts.types.JsonPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension json.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('json',)),))]

cyclopts.types.ExistingJsonPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension json.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('json',)),))]

cyclopts.types.NonExistentJsonPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension json.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('json',)),))]

cyclopts.types.TomlPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension toml.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('toml',)),))]

cyclopts.types.ExistingTomlPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension toml.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('toml',)),))]

cyclopts.types.NonExistentTomlPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension toml.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('toml',)),))]

cyclopts.types.YamlPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must have extension yaml.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=True, dir_okay=False, ext=('yaml',)),))]

cyclopts.types.ExistingYamlPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must exist and have extension yaml.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=True, file_okay=True, dir_okay=False, ext=('yaml',)),))]

cyclopts.types.NonExistentYamlPath

A Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> that must not exist and have extension yaml.

alias of Annotated[Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>, Parameter(validator=(Path(exists=False, file_okay=False, dir_okay=False, ext=('yaml',)),))]

Annotated types for checking common int/float value constraints. All of these types will also work on sequence of numbers (e.g. tuple[int, int] or list[float]).

cyclopts.types.PositiveFloat

A float that must be >0.

alias of Annotated[float <https://docs.python.org/3/library/functions.html#float>, Parameter(validator=(Number(lt=None, lte=None, gt=0, gte=None, modulo=None),))]

cyclopts.types.NonNegativeFloat

A float that must be >=0.

alias of Annotated[float <https://docs.python.org/3/library/functions.html#float>, Parameter(validator=(Number(lt=None, lte=None, gt=None, gte=0, modulo=None),))]

cyclopts.types.NegativeFloat

A float that must be <0.

alias of Annotated[float <https://docs.python.org/3/library/functions.html#float>, Parameter(validator=(Number(lt=0, lte=None, gt=None, gte=None, modulo=None),))]

cyclopts.types.NonPositiveFloat

A float that must be <=0.

alias of Annotated[float <https://docs.python.org/3/library/functions.html#float>, Parameter(validator=(Number(lt=None, lte=0, gt=None, gte=None, modulo=None),))]

cyclopts.types.PositiveInt

An int that must be >0.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=None, gt=0, gte=None, modulo=None),))]

cyclopts.types.NonNegativeInt

An int that must be >=0.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=None, gt=None, gte=0, modulo=None),))]

cyclopts.types.NegativeInt

An int that must be <0.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=0, lte=None, gt=None, gte=None, modulo=None),))]

cyclopts.types.NonPositiveInt

An int that must be <=0.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=0, gt=None, gte=None, modulo=None),))]

cyclopts.types.UInt8

An unsigned 8-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=255, gt=None, gte=0, modulo=None),))]

cyclopts.types.HexUInt8

An unsigned 8-bit integer who's default value will be displayed as hexadecimal in the help-page.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=255, gt=None, gte=0, modulo=None),)), Parameter(show_default=functools.partial(<function _hex_formatter at 0x7f8742aa9f30>, digits=2))]

cyclopts.types.Int8

A signed 8-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=127, gt=None, gte=-128, modulo=None),))]

cyclopts.types.UInt16

An unsigned 16-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=65535, gt=None, gte=0, modulo=None),))]

cyclopts.types.HexUInt16

An unsigned 16-bit integer who's default value will be displayed as hexadecimal in the help-page.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=65535, gt=None, gte=0, modulo=None),)), Parameter(show_default=functools.partial(<function _hex_formatter at 0x7f8742aa9f30>, digits=4))]

cyclopts.types.Int16

A signed 16-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=32767, gt=None, gte=-32768, modulo=None),))]

cyclopts.types.UInt32

An unsigned 32-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=4294967296, lte=None, gt=None, gte=0, modulo=None),))]

cyclopts.types.HexUInt32

An unsigned 32-bit integer who's default value will be displayed as hexadecimal in the help-page.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=4294967296, lte=None, gt=None, gte=0, modulo=None),)), Parameter(show_default=functools.partial(<function _hex_formatter at 0x7f8742aa9f30>, digits=8))]

cyclopts.types.Int32

A signed 32-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=2147483648, lte=None, gt=None, gte=-2147483648, modulo=None),))]

cyclopts.types.UInt64

An unsigned 64-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=18446744073709551616, lte=None, gt=None, gte=0, modulo=None),))]

cyclopts.types.HexUInt64

An unsigned 64-bit integer who's default value will be displayed as hexadecimal in the help-page.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=18446744073709551616, lte=None, gt=None, gte=0, modulo=None),)), Parameter(show_default=functools.partial(<function _hex_formatter at 0x7f8742aa9f30>, digits=16))]

cyclopts.types.Int64

A signed 64-bit integer.

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=9223372036854775808, lte=None, gt=None, gte=-9223372036854775808, modulo=None),))]

Annotated types for parsing a json-string from the CLI.

cyclopts.types.Json

Parse a json-string from the CLI.

Note: Since Cyclopts v3.6.0, all dataclass-like classes now natively attempt to parse json-strings, so practical use-case of this annotation is limited.

Usage example:

from cyclopts import App, types

app = App()

@app.default
def main(json: types.Json):
    print(json)

app()

$ my-script '{"foo": 1, "bar": 2}'
{'foo': 1, 'bar': 2}

alias of Annotated[Any <https://docs.python.org/3/library/typing.html#typing.Any>, Parameter(converter=<function _json_converter at 0x7f8742aa9a60>)]

Annotated types for common web-related values.

cyclopts.types.Email

An email address string with simple validation.

alias of Annotated[str <https://docs.python.org/3/library/stdtypes.html#str>, Parameter(validator=(<function _email_validator at 0x7f8742aa9b10>,))]

cyclopts.types.Port

An int <https://docs.python.org/3/library/functions.html#int> limited to range [0, 65535].

alias of Annotated[int <https://docs.python.org/3/library/functions.html#int>, Parameter(validator=(Number(lt=None, lte=65535, gt=None, gte=0, modulo=None),))]

cyclopts.types.URL

A str <https://docs.python.org/3/library/stdtypes.html#str> URL string with some simple validation.

alias of Annotated[str <https://docs.python.org/3/library/stdtypes.html#str>, Parameter(validator=(<function _url_validator at 0x7f8742aa96f0>,))]

Cyclopts provides a flexible help formatting system for customizing the help-page's appearance.

class cyclopts.help.protocols.HelpFormatter(*args, **kwargs)

Protocol for help formatter functions.

It's the Formatter's job to transform a HelpPanel into rendered text on the display.

Implementations may optionally provide the following methods for custom rendering of "usage" and "description". If these methods are not provided, default rendering will be used.

def render_usage(self, console: Console, options: ConsoleOptions, usage: Any) -> None:
    """Render the usage line."""
    ...

def render_description(self, console: Console, options: ConsoleOptions, description: Any) -> None:
    """Render the description."""
    ...

__call__(console: Console, options: ConsoleOptions, panel: HelpPanel <#cyclopts.help.HelpPanel>) -> None <https://docs.python.org/3/library/constants.html#None>

Format and render a single help panel.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• panel (HelpPanel <#cyclopts.help.HelpPanel>) -- Help panel to render (commands, parameters, etc).

class cyclopts.help.DefaultFormatter(*, panel_spec: PanelSpec <#cyclopts.help.PanelSpec> | None <https://docs.python.org/3/library/constants.html#None> = None, table_spec: TableSpec <#cyclopts.help.TableSpec> | None <https://docs.python.org/3/library/constants.html#None> = None, column_specs: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...] | ColumnSpecBuilder <#cyclopts.help.protocols.ColumnSpecBuilder> | None <https://docs.python.org/3/library/constants.html#None> = None)

Default help formatter using Rich library with customizable specs.

Parameters

• panel_spec (Optional[PanelSpec <#cyclopts.help.PanelSpec>]) -- Panel specification for the outer box/panel styling.
• table_spec (Optional[TableSpec <#cyclopts.help.TableSpec>]) -- Table specification for table styling (borders, padding, etc).
• column_specs (Optional[Union[tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...], ColumnSpecBuilder <#cyclopts.help.protocols.ColumnSpecBuilder>]]) -- Column specifications or builder function for table columns.

Notes

The relationship between these specs can be visualized as:

╭─ Commands ───────────────────────────────────────────────────────╮  ← panel_spec
│ serve     Start the development server                           │     (border, title)
│ --help    Display this message and exit.                         │
╰──────────────────────────────────────────────────────────────────╯
 ↑         ↑
 col[0]    col[1]
 (name)    (description)

╭─ Parameters ─────────────────────────────────────────────────────╮  ← panel_spec
│ *  PORT --port        Server port number [required]              │
│    VERBOSE --verbose  Enable verbose output [default: False]     │
╰──────────────────────────────────────────────────────────────────╯
 ↑  ↑                  ↑
 │  col[1]             col[2]
 │  (name/flags)       (description)
 │
 col[0]
 (required marker)

Where:

• panel_spec controls the outer panel appearance (border, title, etc.)
• table_spec controls the inner table styling (no visible borders by default)
• column_specs defines individual columns (width, style, alignment, etc.)

panel_spec: PanelSpec <#cyclopts.help.PanelSpec> | None <https://docs.python.org/3/library/constants.html#None>

Panel specification for the outer box/panel styling (border, title, padding, etc).

table_spec: TableSpec <#cyclopts.help.TableSpec> | None <https://docs.python.org/3/library/constants.html#None>

Table specification for table styling (borders, padding, column separation, etc).

column_specs: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...] | ColumnSpecBuilder <#cyclopts.help.protocols.ColumnSpecBuilder> | None <https://docs.python.org/3/library/constants.html#None>

Column specifications or builder function for table columns (width, style, alignment, etc).

classmethod with_newline_metadata(**kwargs)

Create formatter with metadata on separate lines.

Returns a DefaultFormatter configured to display parameter metadata (choices, env vars, defaults) on separate indented lines rather than inline with descriptions.

Parameters

**kwargs -- Additional keyword arguments to pass to DefaultFormatter constructor.

Returns

Configured formatter instance with newline metadata display.

Return type

DefaultFormatter <#cyclopts.help.DefaultFormatter>

Examples

>>> from cyclopts import App
>>> from cyclopts.help import DefaultFormatter
>>> app = App(help_formatter=DefaultFormatter.with_newline_metadata())

__call__(console: Console, options: ConsoleOptions, panel: HelpPanel <#cyclopts.help.HelpPanel>) -> None <https://docs.python.org/3/library/constants.html#None>

Format and render a single help panel using Rich.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• panel (HelpPanel <#cyclopts.help.HelpPanel>) -- Help panel to render.

render_usage(console: Console, options: ConsoleOptions, usage: Any <https://docs.python.org/3/library/typing.html#typing.Any>) -> None <https://docs.python.org/3/library/constants.html#None>

Render the usage line.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• usage (Any) -- The usage line (Text or str).

render_description(console: Console, options: ConsoleOptions, description: Any <https://docs.python.org/3/library/typing.html#typing.Any>) -> None <https://docs.python.org/3/library/constants.html#None>

Render the description.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• description (Any) -- The description (can be various Rich renderables).

class cyclopts.help.PlainFormatter(indent_width: int <https://docs.python.org/3/library/functions.html#int> = 2, max_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None)

Plain text formatter for improved accessibility.

Parameters

• indent_width (int <https://docs.python.org/3/library/functions.html#int>) -- Number of spaces to indent entries (default: 2).
• max_width (Optional[int <https://docs.python.org/3/library/functions.html#int>]) -- Maximum line width for wrapping text.

__call__(console: Console, options: ConsoleOptions, panel: HelpPanel <#cyclopts.help.HelpPanel>) -> None <https://docs.python.org/3/library/constants.html#None>

Format and render a single help panel as plain text.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• panel (HelpPanel <#cyclopts.help.HelpPanel>) -- Help panel to render.

render_usage(console: Console, options: ConsoleOptions, usage: Any <https://docs.python.org/3/library/typing.html#typing.Any>) -> None <https://docs.python.org/3/library/constants.html#None>

Render the usage line.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• usage (Any) -- The usage line (Text or str).

render_description(console: Console, options: ConsoleOptions, description: Any <https://docs.python.org/3/library/typing.html#typing.Any>) -> None <https://docs.python.org/3/library/constants.html#None>

Render the description.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- Console to render to.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• description (Any) -- The description (can be various Rich renderables).

class cyclopts.help.protocols.ColumnSpecBuilder(*args, **kwargs)

Protocol for ColumnSpecBuilders.

__call__(console: Console, options: ConsoleOptions, entries: list <https://docs.python.org/3/library/stdtypes.html#list>[HelpEntry <#cyclopts.help.HelpEntry>]) -> tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...]

Build column specifications based on console settings and entries.

Parameters

• console (Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console>) -- The Rich console instance.
• options (ConsoleOptions <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.ConsoleOptions>) -- Console rendering options.
• entries (list <https://docs.python.org/3/library/stdtypes.html#list>[HelpEntry <#cyclopts.help.HelpEntry>]) -- List of help entries to be displayed.

Returns

Tuple of column specifications for table rendering.

Return type

tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...]

class cyclopts.help.PanelSpec(title: RenderableType | None <https://docs.python.org/3/library/constants.html#None> = None, subtitle: RenderableType | None <https://docs.python.org/3/library/constants.html#None> = None, title_align: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['left', 'center', 'right'] = 'left', subtitle_align: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['left', 'center', 'right'] = 'center', style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = 'none', border_style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = 'none', box: Box | None <https://docs.python.org/3/library/constants.html#None> = None, padding: PaddingDimensions = (0, 1), expand: bool <https://docs.python.org/3/library/functions.html#bool> = True, width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, height: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, safe_box: bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None> = None, highlight: bool <https://docs.python.org/3/library/functions.html#bool> = False)

Specification for panel (outer box) styling.

Used by DefaultFormatter to control the appearance of the outer panel that wraps help sections. This spec defines the panel's border, title, subtitle, and overall styling.

See also:

DefaultFormatter

The formatter that uses these specs.

TableSpec

Specification for the inner table.

ColumnSpec

Specification for individual columns.

title: RenderableType | None <https://docs.python.org/3/library/constants.html#None>

Title text displayed at the top of the panel.

Corresponds to the title parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

subtitle: RenderableType | None <https://docs.python.org/3/library/constants.html#None>

Subtitle text displayed at the bottom of the panel.

Corresponds to the subtitle parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

title_align: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['left', 'center', 'right']

Alignment of the title text within the panel.

Corresponds to the title_align parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

subtitle_align: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['left', 'center', 'right']

Alignment of the subtitle text within the panel.

Corresponds to the subtitle_align parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Style applied to the panel background.

Corresponds to the style parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

border_style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Style applied to the panel border.

Corresponds to the border_style parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

box: Box | None <https://docs.python.org/3/library/constants.html#None>

Box drawing style for the panel border.

Corresponds to the box parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>. See rich.box for available styles. Defaults to rich.box.ROUNDED.

padding: PaddingDimensions

Padding inside the panel (top/bottom, left/right) or (top, right, bottom, left).

Corresponds to the padding parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

expand: bool <https://docs.python.org/3/library/functions.html#bool>

Whether the panel should expand to fill available width.

Corresponds to the expand parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Fixed width for the panel in characters.

Corresponds to the width parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

height: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Fixed height for the panel in lines.

Corresponds to the height parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

safe_box: bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None>

Whether to use ASCII-safe box characters for compatibility.

Corresponds to the safe_box parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

highlight: bool <https://docs.python.org/3/library/functions.html#bool>

Enable automatic highlighting of panel contents.

Corresponds to the highlight parameter of Panel <https://rich.readthedocs.io/en/stable/reference/panel.html#rich.panel.Panel>.

build(renderable: RenderableType, **overrides) -> Panel

Create a Panel around renderable. Use kwargs to override spec per render.

copy(**kwargs)

class cyclopts.help.TableSpec(title: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None, caption: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None, style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, border_style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, header_style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, footer_style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, box: Box | None <https://docs.python.org/3/library/constants.html#None> = None, show_header: bool <https://docs.python.org/3/library/functions.html#bool> = False, show_footer: bool <https://docs.python.org/3/library/functions.html#bool> = False, show_lines: bool <https://docs.python.org/3/library/functions.html#bool> = False, show_edge: bool <https://docs.python.org/3/library/functions.html#bool> = True, expand: bool <https://docs.python.org/3/library/functions.html#bool> = False, pad_edge: bool <https://docs.python.org/3/library/functions.html#bool> = False, padding: PaddingDimensions = (0, 2, 0, 0), collapse_padding: bool <https://docs.python.org/3/library/functions.html#bool> = False, width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, min_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, safe_box: bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None> = None)

Specification for table layout and styling.

Used by DefaultFormatter to control the appearance of tables that display commands and parameters. This spec defines table-wide properties like borders, headers, and padding.

See also:

DefaultFormatter

The formatter that uses these specs.

ColumnSpec

Specification for individual columns.

PanelSpec

Specification for the outer panel.

title: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>

Title text displayed above the table.

Corresponds to the title parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

caption: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>

Caption text displayed below the table.

Corresponds to the caption parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Default style applied to the entire table.

Corresponds to the style parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

border_style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Style applied to table borders.

Corresponds to the border_style parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

header_style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Default style for all table headers (can be overridden per column).

Corresponds to the header_style parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

footer_style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Default style for all table footers (can be overridden per column).

Corresponds to the footer_style parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

box: Box | None <https://docs.python.org/3/library/constants.html#None>

Box drawing style for the table borders.

Corresponds to the box parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>. See rich.box for available styles.

show_header: bool <https://docs.python.org/3/library/functions.html#bool>

Whether to display column headers.

Corresponds to the show_header parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

show_footer: bool <https://docs.python.org/3/library/functions.html#bool>

Whether to display column footers.

Corresponds to the show_footer parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

show_lines: bool <https://docs.python.org/3/library/functions.html#bool>

Whether to show horizontal lines between rows.

Corresponds to the show_lines parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

show_edge: bool <https://docs.python.org/3/library/functions.html#bool>

Whether to draw a box around the outside of the table.

Corresponds to the show_edge parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

expand: bool <https://docs.python.org/3/library/functions.html#bool>

Whether the table should expand to fill available width.

Corresponds to the expand parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

pad_edge: bool <https://docs.python.org/3/library/functions.html#bool>

Whether to add padding to the table edges.

Corresponds to the pad_edge parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

padding: PaddingDimensions

Padding around cell content (top, right, bottom, left).

Corresponds to the padding parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

collapse_padding: bool <https://docs.python.org/3/library/functions.html#bool>

Whether to collapse padding when adjacent cells are empty.

Corresponds to the collapse_padding parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Fixed width for the table in characters.

Corresponds to the width parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

min_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Minimum width for the table in characters.

Corresponds to the min_width parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

safe_box: bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None>

Whether to use ASCII-safe box characters for compatibility.

Corresponds to the safe_box parameter of Table <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table>.

build(columns: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...], entries: Iterable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable>[HelpEntry <#cyclopts.help.HelpEntry>], **overrides) -> Table

Construct and populate a rich.Table.

Parameters

• columns (tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[ColumnSpec <#cyclopts.help.ColumnSpec>, ...]) -- Column specifications defining the table structure.
• entries (Iterable[HelpEntry <#cyclopts.help.HelpEntry>]) -- Table entries to populate the table with.
• **overrides -- Per-render overrides for table settings.

Returns

A populated Rich Table.

Return type

Table

copy(**kwargs)

class cyclopts.help.ColumnSpec(renderer: str <https://docs.python.org/3/library/stdtypes.html#str> | Renderer, header: str <https://docs.python.org/3/library/stdtypes.html#str> = '', footer: str <https://docs.python.org/3/library/stdtypes.html#str> = '', header_style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, footer_style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, style: StyleType | None <https://docs.python.org/3/library/constants.html#None> = None, justify: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['default', 'left', 'center', 'right', 'full'] = 'left', vertical: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['top', 'middle', 'bottom'] = 'top', overflow: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['fold', 'crop', 'ellipsis', 'ignore'] = 'ellipsis', width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, min_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, max_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, ratio: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None, no_wrap: bool <https://docs.python.org/3/library/functions.html#bool> = False, highlight: bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None> = None)

Specification for a single column in a help table.

Used by DefaultFormatter to define how individual columns are rendered in help tables. Each column can have its own renderer, styling, and layout properties.

See also:

DefaultFormatter

The formatter that uses these specs.

TableSpec

Specification for the entire table.

PanelSpec

Specification for the outer panel.

renderer: str <https://docs.python.org/3/library/stdtypes.html#str> | Renderer

Specifies how to extract and render cell content from a HelpEntry.

Can be either:

• A string: The attribute name to retrieve from HelpEntry (e.g., 'names', 'description', 'required', 'type'). The string is displayed as-is.
• A callable: A function matching the Renderer protocol. The function receives a HelpEntry and should return a RenderableType (str, Text <https://rich.readthedocs.io/en/stable/reference/text.html#rich.text.Text>, or other Rich renderable).

Examples:

# String renderer - get attribute directly
ColumnSpec(renderer="description")

# Callable renderer - custom formatting
def format_names(entry: HelpEntry) -> str:
    return ", ".join(entry.names) if entry.names else ""
ColumnSpec(renderer=format_names)

header: str <https://docs.python.org/3/library/stdtypes.html#str>

Column header text displayed at the top of the column.

Example:

header="Options" renders:
┌─────────┬─────────────┐
│ Options │ Description │
├─────────┼─────────────┤
│ --help  │ Show help   │
└─────────┴─────────────┘

footer: str <https://docs.python.org/3/library/stdtypes.html#str>

Column footer text displayed at the bottom of the column.

Example:

footer="Required" renders:
┌──────────┬────────────┐
│ --help   │ Show help  │
├──────────┼────────────┤
│ Required │            │
└──────────┴────────────┘

header_style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Style applied to the column header text.

Corresponds to the header_style parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

footer_style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Style applied to the column footer text.

Corresponds to the footer_style parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

style: StyleType | None <https://docs.python.org/3/library/constants.html#None>

Default style applied to all cells in this column.

Corresponds to the style parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

justify: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['default', 'left', 'center', 'right', 'full']

Text justification within the column.

Corresponds to the justify parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

vertical: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['top', 'middle', 'bottom']

Vertical alignment of text within cells.

Corresponds to the vertical parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

overflow: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['fold', 'crop', 'ellipsis', 'ignore']

How to handle text that exceeds column width.

Corresponds to the overflow parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Fixed width for the column in characters.

Corresponds to the width parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

min_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Minimum width for the column in characters.

Corresponds to the min_width parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

max_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Maximum width for the column in characters.

Corresponds to the max_width parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

ratio: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>

Relative width ratio compared to other columns.

Corresponds to the ratio parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

no_wrap: bool <https://docs.python.org/3/library/functions.html#bool>

Prevent text wrapping in the column.

Corresponds to the no_wrap parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

highlight: bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None>

Enable automatic highlighting of text in the column.

Corresponds to the highlight parameter of rich.table.Table.add_column() <https://rich.readthedocs.io/en/stable/reference/table.html#rich.table.Table.add_column>.

copy(**kwargs)

class cyclopts.help.NameRenderer(max_width: int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None> = None)

Renderer for parameter/command names with optional text wrapping.

Parameters

max_width (int <https://docs.python.org/3/library/functions.html#int> | None) -- Maximum width for wrapping. If None, no wrapping is applied.

Initialize the renderer with formatting options.

Parameters

max_width (int <https://docs.python.org/3/library/functions.html#int> | None) -- Maximum width for wrapping. If None, no wrapping is applied.

__call__(entry: HelpEntry <#cyclopts.help.HelpEntry>) -> RenderableType

Render the names column with optional text wrapping.

Parameters

entry (HelpEntry <#cyclopts.help.HelpEntry>) -- The table entry to render.

Returns

Combined names and shorts, optionally wrapped. Order: positive_names, positive_shorts, negative_names, negative_shorts

Return type

RenderableType

class cyclopts.help.DescriptionRenderer(newline_metadata: bool <https://docs.python.org/3/library/functions.html#bool> = False)

Renderer for descriptions with configurable metadata formatting.

Parameters

newline_metadata (bool <https://docs.python.org/3/library/functions.html#bool>) -- If True, display metadata (choices, env vars, defaults) on separate lines. If False (default), display metadata inline with the description.

Initialize the renderer with formatting options.

Parameters

newline_metadata (bool <https://docs.python.org/3/library/functions.html#bool>) -- If True, display metadata on separate lines instead of inline.

__call__(entry: HelpEntry <#cyclopts.help.HelpEntry>) -> RenderableType

Render parameter description with metadata annotations.

Enriches the base description with choices, environment variables, default values, and required status.

Parameters

entry (HelpEntry <#cyclopts.help.HelpEntry>) -- The table entry to render.

Returns

Description with appended metadata.

Return type

RenderableType

class cyclopts.help.AsteriskRenderer

Renderer for required parameter asterisk indicator.

A simple renderer that displays an asterisk (*) for required parameters.

__call__(entry: HelpEntry <#cyclopts.help.HelpEntry>) -> RenderableType

Render an asterisk for required parameters.

Parameters

entry (HelpEntry <#cyclopts.help.HelpEntry>) -- The table entry to render.

Returns

An asterisk if the entry is required, empty string otherwise.

Return type

RenderableType

class cyclopts.help.HelpPanel(format: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['command', 'parameter'], title: RenderableType, description=None, entries: list <https://docs.python.org/3/library/stdtypes.html#list>[HelpEntry <#cyclopts.help.HelpEntry>] = NOTHING)

Data container for help panel information.

format: Literal <https://docs.python.org/3/library/typing.html#typing.Literal>['command', 'parameter']

Panel format type.

title: RenderableType

The title text displayed at the top of the help panel.

description: Any <https://docs.python.org/3/library/typing.html#typing.Any>

Optional description text displayed below the title.

Typically a str <https://docs.python.org/3/library/stdtypes.html#str> or a RenderableType <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.RenderableType>

entries: list <https://docs.python.org/3/library/stdtypes.html#list>[HelpEntry <#cyclopts.help.HelpEntry>]

List of help entries to display (in order) in the panel.

copy(**kwargs)

class cyclopts.help.HelpEntry(*, positive_names: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] = (), positive_shorts: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] = (), negative_names: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] = (), negative_shorts: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] = (), description: Any <https://docs.python.org/3/library/typing.html#typing.Any> = None, required: bool <https://docs.python.org/3/library/functions.html#bool> = False, sort_key: Any <https://docs.python.org/3/library/typing.html#typing.Any> = None, type: Any <https://docs.python.org/3/library/typing.html#typing.Any> | None <https://docs.python.org/3/library/constants.html#None> = None, choices: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] | None <https://docs.python.org/3/library/constants.html#None> = None, env_var: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] | None <https://docs.python.org/3/library/constants.html#None> = None, default: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None)

Container for help table entry data.

positive_names: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

Positive long option names (e.g., "--verbose", "--dry-run").

positive_shorts: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

Positive short option names (e.g., "-v", "-n").

negative_names: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

Negative long option names (e.g., "--no-verbose", "--no-dry-run").

negative_shorts: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

Negative short option names (e.g., "-N"). Rarely used.

property names: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

All long option names (positive + negative). For backward compatibility.

property shorts: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

All short option names (positive + negative). For backward compatibility.

property all_options: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...]

positive longs, positive shorts, negative longs, negative shorts.

Type

All options in display order

description: Any <https://docs.python.org/3/library/typing.html#typing.Any>

Help text description for this entry.

Typically a str <https://docs.python.org/3/library/stdtypes.html#str> or a RenderableType <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.RenderableType>

required: bool <https://docs.python.org/3/library/functions.html#bool>

Whether this parameter/command is required.

sort_key: Any <https://docs.python.org/3/library/typing.html#typing.Any>

Custom sorting key for ordering entries.

type: Any <https://docs.python.org/3/library/typing.html#typing.Any> | None <https://docs.python.org/3/library/constants.html#None>

Type annotation of the parameter.

choices: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] | None <https://docs.python.org/3/library/constants.html#None>

Available choices for this parameter.

env_var: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[str <https://docs.python.org/3/library/stdtypes.html#str>, ...] | None <https://docs.python.org/3/library/constants.html#None>

Environment variable names that can set this parameter.

default: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>

Default value for this parameter to display. None means no default to show.

copy(**kwargs)

Cyclopts has builtin configuration classes to be used with App.config for loading user-defined defaults in many common scenarios. All Cyclopts builtins index into the configuration file with the following rules:

1.

Apply root_keys (if provided) to enter the project's configuration namespace.

2.

Apply the command name(s) to enter the current command's configuration namespace.

3.

Apply each key/value pair if CLI arguments have not been provided for that parameter.

class cyclopts.config.Toml(path, *, root_keys: None <https://docs.python.org/3/library/constants.html#None> | Any <https://docs.python.org/3/library/typing.html#typing.Any> | Iterable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable>[Any <https://docs.python.org/3/library/typing.html#typing.Any>] = (), allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False, use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True, source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None, must_exist: bool <https://docs.python.org/3/library/functions.html#bool> = False, search_parents: bool <https://docs.python.org/3/library/functions.html#bool> = False)

Automatically read configuration from Toml file.

path: str <https://docs.python.org/3/library/stdtypes.html#str> | pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>

Path to TOML configuration file.

source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None

Identifier for the configuration source, used in error messages. If not provided, defaults to the absolute path of the configuration file.

root_keys: Iterable[str <https://docs.python.org/3/library/stdtypes.html#str>] = None

The key or sequence of keys that lead to the root configuration structure for this app. For example, if referencing a pyproject.toml, it is common to store all of your projects configuration under:

[tool.myproject]

So, your Cyclopts App should be configured as:

app = cyclopts.App(config=cyclopts.config.Toml("pyproject.toml", root_keys=("tool", "myproject")))

must_exist: bool <https://docs.python.org/3/library/functions.html#bool> = False

The configuration file MUST exist. Raises FileNotFoundError <https://docs.python.org/3/library/exceptions.html#FileNotFoundError> if it does not exist.

search_parents: bool <https://docs.python.org/3/library/functions.html#bool> = False

If path doesn't exist, iteratively search parenting directories for a same-named configuration file. Raises FileNotFoundError <https://docs.python.org/3/library/exceptions.html#FileNotFoundError> if no configuration file is found.

allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False

Allow for unknown keys. Otherwise, if an unknown key is provided, raises UnknownOptionError.

use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True

Use the sequence of commands as keys into the configuration.

For example, the following CLI invocation:

$ python my-script.py my-command

Would search into ["my-command"] for values.

class cyclopts.config.Yaml(path, *, root_keys: None <https://docs.python.org/3/library/constants.html#None> | Any <https://docs.python.org/3/library/typing.html#typing.Any> | Iterable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable>[Any <https://docs.python.org/3/library/typing.html#typing.Any>] = (), allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False, use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True, source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None, must_exist: bool <https://docs.python.org/3/library/functions.html#bool> = False, search_parents: bool <https://docs.python.org/3/library/functions.html#bool> = False)

Automatically read configuration from YAML file.

path: str <https://docs.python.org/3/library/stdtypes.html#str> | pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>

Path to YAML configuration file.

source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None

Identifier for the configuration source, used in error messages. If not provided, defaults to the absolute path of the configuration file.

root_keys: Iterable[str <https://docs.python.org/3/library/stdtypes.html#str>] = None

The key or sequence of keys that lead to the root configuration structure for this app. For example, if referencing a common config.yaml that is shared with other applications, it is common to store your projects configuration under a key like myproject:.

Your Cyclopts App would be configured as:

app = cyclopts.App(config=cyclopts.config.Yaml("config.yaml", root_keys="myproject"))

must_exist: bool <https://docs.python.org/3/library/functions.html#bool> = False

The configuration file MUST exist. Raises FileNotFoundError <https://docs.python.org/3/library/exceptions.html#FileNotFoundError> if it does not exist.

search_parents: bool <https://docs.python.org/3/library/functions.html#bool> = False

If path doesn't exist, iteratively search parenting directories for a same-named configuration file. Raises FileNotFoundError <https://docs.python.org/3/library/exceptions.html#FileNotFoundError> if no configuration file is found.

allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False

Allow for unknown keys. Otherwise, if an unknown key is provided, raises UnknownOptionError.

use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True

Use the sequence of commands as keys into the configuration.

For example, the following CLI invocation:

$ python my-script.py my-command

Would search into ["my-command"] for values.

class cyclopts.config.Json(path, *, root_keys: None <https://docs.python.org/3/library/constants.html#None> | Any <https://docs.python.org/3/library/typing.html#typing.Any> | Iterable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable>[Any <https://docs.python.org/3/library/typing.html#typing.Any>] = (), allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False, use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True, source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None, must_exist: bool <https://docs.python.org/3/library/functions.html#bool> = False, search_parents: bool <https://docs.python.org/3/library/functions.html#bool> = False)

Automatically read configuration from Json file.

path: str <https://docs.python.org/3/library/stdtypes.html#str> | pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>

Path to JSON configuration file.

source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None

Identifier for the configuration source, used in error messages. If not provided, defaults to the absolute path of the configuration file. Can be customized to provide more descriptive error context.

Example:

app = cyclopts.App(config=cyclopts.config.Json("config.json", source="production-config"))

root_keys: Iterable[str <https://docs.python.org/3/library/stdtypes.html#str>] = None

The key or sequence of keys that lead to the root configuration structure for this app. For example, if referencing a common config.json that is shared with other applications, it is common to store your projects configuration under a key like "myproject":.

Your Cyclopts App would be configured as:

app = cyclopts.App(config=cyclopts.config.Json("config.json", root_keys="myproject"))

must_exist: bool <https://docs.python.org/3/library/functions.html#bool> = False

The configuration file MUST exist. Raises FileNotFoundError <https://docs.python.org/3/library/exceptions.html#FileNotFoundError> if it does not exist.

search_parents: bool <https://docs.python.org/3/library/functions.html#bool> = False

If path doesn't exist, iteratively search parenting directories for a same-named configuration file. Raises FileNotFoundError <https://docs.python.org/3/library/exceptions.html#FileNotFoundError> if no configuration file is found.

allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False

Allow for unknown keys. Otherwise, if an unknown key is provided, raises UnknownOptionError.

use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True

Use the sequence of commands as keys into the configuration.

For example, the following CLI invocation:

$ python my-script.py my-command

Would search into ["my-command"] for values.

class cyclopts.config.Dict(data: dict <https://docs.python.org/3/library/stdtypes.html#dict>[str <https://docs.python.org/3/library/stdtypes.html#str>, Any <https://docs.python.org/3/library/typing.html#typing.Any>], *, root_keys: None <https://docs.python.org/3/library/constants.html#None> | Any <https://docs.python.org/3/library/typing.html#typing.Any> | Iterable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable>[Any <https://docs.python.org/3/library/typing.html#typing.Any>] = (), allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False, use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True, source: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None)

Configuration source from an in-memory dictionary.

Useful for programmatically generated configurations.

Use an in-memory Python dictionary as configuration source.

data: dict <https://docs.python.org/3/library/stdtypes.html#dict>[str <https://docs.python.org/3/library/stdtypes.html#str>, Any]

The configuration dictionary.

source: str <https://docs.python.org/3/library/stdtypes.html#str> = "dict"

Identifier for the configuration source, used in error messages.

root_keys: Iterable[str <https://docs.python.org/3/library/stdtypes.html#str>] = ()

The key or sequence of keys that lead to the root configuration structure for this app.

allow_unknown: bool <https://docs.python.org/3/library/functions.html#bool> = False

Allow for unknown keys. Otherwise, if an unknown key is provided, raises UnknownOptionError.

use_commands_as_keys: bool <https://docs.python.org/3/library/functions.html#bool> = True

Use the sequence of commands as keys into the configuration.

class cyclopts.config.Env(prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = '', *, source: str <https://docs.python.org/3/library/stdtypes.html#str> = 'env', command: bool <https://docs.python.org/3/library/functions.html#bool> = True, show: bool <https://docs.python.org/3/library/functions.html#bool> = True)

Automatically derive environment variable names to read configurations from.

For example, consider the following app:

import cyclopts

app = cyclopts.App(config=cyclopts.config.Env("MY_SCRIPT_"))

@app.command
def my_command(foo, bar):
    print(f"{foo=} {bar=}")

app()

If values for foo and bar are not supplied by the command line, the app will check the environment variables MY_SCRIPT_MY_COMMAND_FOO and MY_SCRIPT_MY_COMMAND_BAR, respectively:

$ python my_script.py my-command 1 2
foo=1 bar=2

$ export MY_SCRIPT_MY_COMMAND_FOO=100
$ python my_script.py my-command --bar=2
foo=100 bar=2
$ python my_script.py my-command 1 2
foo=1 bar=2

prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ""

String to prepend to all autogenerated environment variable names. Typically ends in _, and is something like MY_APP_.

source: str <https://docs.python.org/3/library/stdtypes.html#str> = "env"

Identifier for the configuration source, used in error messages and token tracking. Defaults to "env".

command: bool <https://docs.python.org/3/library/functions.html#bool> = True

If True <https://docs.python.org/3/library/constants.html#True>, add the command's name (uppercase) after prefix.

show: bool <https://docs.python.org/3/library/functions.html#bool> = True

If True <https://docs.python.org/3/library/constants.html#True>, then show the environment variables on the help-page.

exception cyclopts.CycloptsError

Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

Root exception for runtime errors.

As CycloptsErrors bubble up the Cyclopts call-stack, more information is added to it.

msg: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>

If set, override automatic message generation.

verbose: bool <https://docs.python.org/3/library/functions.html#bool>

More verbose error messages; aimed towards developers debugging their Cyclopts app. Defaults to False.

root_input_tokens: list <https://docs.python.org/3/library/stdtypes.html#list>[str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>

The parsed CLI tokens that were initially fed into the App.

unused_tokens: list <https://docs.python.org/3/library/stdtypes.html#list>[str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>

Leftover tokens after parsing is complete.

target: Callable <https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable> | None <https://docs.python.org/3/library/constants.html#None>

The python function associated with the command being parsed.

argument: Argument <#cyclopts.Argument> | None <https://docs.python.org/3/library/constants.html#None>

Argument that was matched.

command_chain: Sequence <https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence>[str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>

List of command that lead to target.

app: App <#cyclopts.App> | None <https://docs.python.org/3/library/constants.html#None>

The Cyclopts application itself.

console: Console | None <https://docs.python.org/3/library/constants.html#None>

Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console> to display runtime errors.

exception cyclopts.ValidationError

Bases: CycloptsError

Validator function raised an exception.

exception_message: str <https://docs.python.org/3/library/stdtypes.html#str>

Parenting Assertion/Value/Type Error message.

group: Group <#cyclopts.Group> | None <https://docs.python.org/3/library/constants.html#None>

If a group validator caused the exception.

value: Any <https://docs.python.org/3/library/typing.html#typing.Any>

Converted value that failed validation.

exception cyclopts.UnknownOptionError

Bases: CycloptsError

Unknown/unregistered option provided by the cli.

A nearest-neighbor parameter suggestion may be printed.

token: Token <#cyclopts.Token>

Token without a matching parameter.

argument_collection: ArgumentCollection <#cyclopts.ArgumentCollection>

Argument collection of plausible options.

exception cyclopts.CoercionError

Bases: CycloptsError

There was an error performing automatic type coercion.

token: Token <#cyclopts.Token> | None <https://docs.python.org/3/library/constants.html#None>

Input token that couldn't be coerced.

target_type: type <#cyclopts.help.HelpEntry.type> | None <https://docs.python.org/3/library/constants.html#None>

Intended type to coerce into.

exception cyclopts.UnknownCommandError

Bases: CycloptsError

CLI token combination did not yield a valid command.

msg

If set, override automatic message generation.

verbose

More verbose error messages; aimed towards developers debugging their Cyclopts app. Defaults to False.

root_input_tokens

The parsed CLI tokens that were initially fed into the App.

unused_tokens

Leftover tokens after parsing is complete.

target

The python function associated with the command being parsed.

argument

Argument that was matched.

command_chain

List of command that lead to target.

app

The Cyclopts application itself.

console

Console <https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console> to display runtime errors.

exception cyclopts.UnusedCliTokensError

Bases: CycloptsError

Not all CLI tokens were used as expected.

exception cyclopts.MissingArgumentError

Bases: CycloptsError

A required argument was not provided.

tokens_so_far: list <https://docs.python.org/3/library/stdtypes.html#list>[str <https://docs.python.org/3/library/stdtypes.html#str>]

If the matched parameter requires multiple tokens, these are the ones we have parsed so far.

keyword: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>

The keyword that was used when the error was raised (e.g., '-o' instead of '--option').

exception cyclopts.RequiresEqualsError

Bases: CycloptsError

A long option requires = to assign a value (e.g., --option=value).

keyword: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>

The keyword that was used (e.g., '--name').

exception cyclopts.RepeatArgumentError

Bases: CycloptsError

The same parameter has erroneously been specified multiple times.

token: Token <#cyclopts.Token>

The repeated token.

exception cyclopts.MixedArgumentError

Bases: CycloptsError

Cannot supply keywords and non-keywords to the same argument.

class cyclopts.CommandCollisionError

Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

A command with the same name has already been registered to the app.

exception cyclopts.CombinedShortOptionError

Bases: CycloptsError

Cannot combine short, token-consuming options with short flags.

class cyclopts.EditorError

Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

Root editor-related error.

Root exception raised by all exceptions in edit().

class cyclopts.EditorNotFoundError

Bases: EditorError

Could not find a valid text editor for :func`.edit`.

class cyclopts.EditorDidNotSaveError

Bases: EditorError

User did not save upon exiting edit().

class cyclopts.EditorDidNotChangeError

Bases: EditorError

User did not edit file contents in edit().

cyclopts --install-completion [OPTIONS]

Register shell-completion for the cyclopts CLI itself.

Parameters:

--shell

Shell type for completion. If not specified, attempts to auto-detect current shell. [Choices: zsh, bash, fish]

--output,  -o

Output path for the completion script. If not specified, uses shell-specific default.

cyclopts generate-docs [OPTIONS] SCRIPT [ARGS]

Generate documentation for a Cyclopts application.

Parameters:

SCRIPT, --script

Python script path, optionally with ':app_object' notation to specify the App object. If not specified, will search for App objects in the script's global namespace. [Required]

OUTPUT, --output, -o

Output file path. If not specified, prints to stdout.

--format, -f

Output format for documentation. If not specified, inferred from output file extension. [Choices: markdown, md, html, htm, rst, rest, restructuredtext]

--include-hidden

Include hidden commands in documentation. [Default: False]

--heading-level

Starting heading level for markdown format. [Default: 1]

cyclopts run SCRIPT [ARGS...]

Run a Cyclopts application from a Python script with dynamic shell completion.

All arguments after the script path are passed to the loaded application.

Shell completion is available. Run once to install (persistent): cyclopts --install-completion

Arguments:

SCRIPT

Python script path with optional ':app_object' notation. [Required]

ARGS

Arguments to pass to the loaded application.

Due to quirks in the python-typing system, Cyclopts can only support some scenarios surrounding PEP-0563 <https://peps.python.org/563>, the strinigization of type hints via from __future__ import annotations. Notably, this can also sometimes break dataclass definitions when inheritance from multiple python modules is involved. Attempts have been made to improve Cyclopts support, but there are the following blockers:

1. CPython has some bugs <https://github.com/python/cpython/issues/89687> around typing.get_type_hints() <https://docs.python.org/3/library/typing.html#typing.get_type_hints>. It is outside the scope of Cyclopts to compensate for the complex task of type-hint scoping and resolution.
2. Particularly with dataclasses, it looks like they will be fixing these bugs, but it would only be backported to 3.13 and 3.14 <https://github.com/python/cpython/issues/133956#issuecomment-2883646533>. This limitation to very modern python versions makes a lot of PEP-0563 moot.
3. PEP-0649 <https://peps.python.org/649> and PEP-0749 <https://peps.python.org/749> deprecate the usage of from __future__ import annotations. This suggests that it is not worth the long-term maintenance of supporting the complications of this feature.

Original discussion on GitHub. <https://github.com/BrianPugh/cyclopts/issues/439>

Instead of importing and registering a function directly:

from cyclopts import App
from myapp.commands.users import create, delete, list_users  # Imported immediately

app = App()
user_app = App(name="user")

user_app.command(create)
user_app.command(delete)
user_app.command(list_users, name="list")

app.command(user_app)

Use an import path string:

from cyclopts import App

app = App()
user_app = App(name="user")

# No imports! Modules loaded only when commands execute
user_app.command("myapp.commands.users:create")
user_app.command("myapp.commands.users:delete")
user_app.command("myapp.commands.users:list_users", name="list")

app.command(user_app)

The import path format is "module.path:function_name", similar to setuptools entry points.

Lazy commands are resolved/imported in these situations:

• Command Execution - When the user runs that specific command
• Help Generation - When displaying help that includes the command
• Direct Access - When accessing via app["command_name"]

In order to benefit from lazy loading, you have to make sure that the files are not imported by other means when your CLI starts up.

The import path string has two parts separated by a colon (:):

Module Path (before the :)

The Python module to import, using dot notation (e.g., myapp.commands.users).

Attribute Name (after the :)

The function or App to get from the module using getattr() <https://docs.python.org/3/library/functions.html#getattr>.

Examples:

# Simple function in a module
app.command("myapp.commands:create_user")

# Nested module path
app.command("myapp.admin.database.operations:migrate")

# Import an App instance, exposed to the CLI as "admin"
app.command("myapp.admin:admin_app", name="admin")

Note:

The attribute name (after :) is the actual Python name, not the CLI command name. Use the name parameter to specify the CLI command name.

The name parameter specifies how the command appears in the CLI, while the import path specifies what code to execute. They can be completely different:

from cyclopts import App

user_app = App(name="user")

# Function name: "list_users"
# CLI command name: "list"
user_app.command("myapp.commands.users:list_users", name="list")

# Function name: "delete"
# CLI command name: "remove"
user_app.command("myapp.commands.users:delete", name="remove")

$ myapp user list --limit 10
# Imports and runs myapp.commands.users:list_users

$ myapp user remove --username alice
# Imports and runs myapp.commands.users:delete

If name is not specified, Cyclopts derives it from the function name with App.name_transform <#cyclopts.App.name_transform> applied (typically converting underscores to hyphens).

If an import path/configuration is invalid, the error occurs when the command is executed, not when it's registered:

from cyclopts import App

app = App()

# This won't error immediately - registration succeeds
app.command("nonexistent.module:func")

app()

$ myapp func
# Now the error occurs:
ImportError: Cannot import module 'nonexistent.module'

To catch import errors early, you can access the command during testing:

import pytest
from cyclopts import App

def test_lazy_commands_are_importable():
    app = App()
    app.command("myapp.commands:create")

    # This will trigger the import and fail if path is wrong
    resolved = app["create"]
    assert resolved is not None

Tip:

TL;DR: Define Group <#cyclopts.Group> objects used by commands in your main CLI module, NOT in lazy-loaded modules.

Group <#cyclopts.Group> objects defined in unresolved lazy modules won't be available until those modules are explicitly imported. To avoid this, define Group <#cyclopts.Group> objects in non-lazy modules.

# myapp/cli.py (always imported)
from cyclopts import App, Group

# Define Group objects here
admin_group = Group("Admin Commands", validator=require_admin_role)
db_group = Group("Database", default_parameter=Parameter(envvar_prefix="DB_"))

app = App()

# Lazy commands can reference the Group objects
app.command("myapp.admin:create_user", group=admin_group)
app.command("myapp.admin:delete_user", group=admin_group)
app.command("myapp.db:migrate", group=db_group)

What to avoid: Defining Group objects inside lazy-loaded modules:

# myapp/admin.py (lazy-loaded)
from cyclopts import App, Group

# BAD: This Group won't be available to other commands until this module is imported
admin_group = Group("Admin Commands", validator=require_admin_role)

def create_user():
    ...

If you reference a group by string (e.g., group="Admin Commands") and the Group <#cyclopts.Group> object with that name is only defined in an unresolved lazy module, the group won't be available until that lazy module is imported. This means that:

• Validators defined on the lazy-loaded Group <#cyclopts.Group> won't be applied to commands in other modules.
• Group.default_parameter <#cyclopts.Group.default_parameter> and other settings won't be inherited by commands referencing the group by string.

Once the lazy module is imported (e.g., by executing one of its commands), the Group <#cyclopts.Group> object becomes available and subsequent operations will use it correctly.

The App <#cyclopts.App> class accepts a help_formatter parameter that controls the default formatting for all help output:

from cyclopts import App
from cyclopts.help import DefaultFormatter, PlainFormatter

# Use a built-in formatter by name: {"default", "plain"}
app = App(help_formatter="plain")

# Or pass a formatter instance with custom configuration
app = App(
    help_formatter=DefaultFormatter(
        # Custom configuration options
    )
)

# Or use a completely custom formatter; see HelpFormatter protocol.
app = App(help_formatter=MyCustomFormatter())

Individual Group <#cyclopts.Group> instances can have their own help_formatter that overrides the app-level default:

from cyclopts import App, Group
from cyclopts.help import DefaultFormatter, PanelSpec
from rich.box import DOUBLE

# Create a group with custom formatting
advanced_group = Group(
    "Advanced Options",
    help_formatter=DefaultFormatter(
        panel_spec=PanelSpec(
            border_style="red",
            box=DOUBLE,
        )
    )
)

# The app can have a different default formatter
app = App(help_formatter="plain")

# Parameters in advanced_group will use the group's formatter,
# while other parameters use the app's formatter

The DefaultFormatter <#cyclopts.help.DefaultFormatter> is the default help formatter that uses Rich <https://github.com/Textualize/rich> for beautiful terminal output with colors, borders, and structured layouts.

from cyclopts import App

# Explicitly use the default formatter (same as not specifying)
app = App(help_formatter="default")

@app.default
def main(name: str, count: int = 1):
    """A simple greeting application.

    Parameters
    ----------
    name : str
        Person to greet.
    count : int
        Number of times to greet.
    """
    for _ in range(count):
        print(f"Hello, {name}!")

if __name__ == "__main__":
    app()

Output:

The PlainFormatter <#cyclopts.help.PlainFormatter> provides accessibility-focused plain text output without colors or special characters, ideal for screen readers and simpler terminals.

from cyclopts import App

# Use plain text formatter for accessibility
app = App(help_formatter="plain")

@app.default
def main(name: str, count: int = 1):
    """A simple greeting application.

    Parameters
    ----------
    name : str
        Person to greet.
    count : int
        Number of times to greet.
    """
    for _ in range(count):
        print(f"Hello, {name}!")

if __name__ == "__main__":
    app()

Output:

Usage: demo.py [ARGS] [OPTIONS]

A simple greeting application.

Commands:
--help, -h: Display this message and exit.
--version: Display application version.

Parameters:
NAME, --name: Person to greet.
COUNT, --count: Number of times to greet.

The DefaultFormatter <#cyclopts.help.DefaultFormatter> accepts several customization options through its initialization parameters.

The PanelSpec <#cyclopts.help.PanelSpec> controls the outer panel appearance:

from cyclopts import App
from cyclopts.help import DefaultFormatter, PanelSpec
from rich.box import DOUBLE

app = App(
    help_formatter=DefaultFormatter(
        panel_spec=PanelSpec(
            box=DOUBLE,              # Use double-line borders
            border_style="blue",     # Blue border color
            padding=(1, 2),         # (vertical, horizontal) padding
            expand=True,            # Expand to full terminal width
        )
    )
)

@app.default
def main(path: str, verbose: bool = False):
    """Process a file with custom panel styling."""
    print(f"Processing {path}")

if __name__ == "__main__":
    app()

Output:

The TableSpec <#cyclopts.help.TableSpec> controls the table styling within panels:

from cyclopts import App
from cyclopts.help import DefaultFormatter, TableSpec

app = App(
    help_formatter=DefaultFormatter(
        table_spec=TableSpec(
            show_header=True,  # Show column headers
            show_lines=True,  # Show lines between rows
            show_edge=False,  # Remove outer table border
            border_style="green",  # Green table elements
            padding=(0, 2, 0, 0),  # Extra right padding
            box=SQUARE,  # otherwise we won't see the lines
        )
    )
)

@app.default
def main(path: str, verbose: bool = False):
    """Process a file with custom table styling."""
    print(f"Processing {path}")

if __name__ == "__main__":
    app()

Output:

You can combine both panel and table specifications:

from cyclopts import App
from cyclopts.help import DefaultFormatter, PanelSpec, TableSpec
from rich.box import ROUNDED

app = App(
    help_formatter=DefaultFormatter(
        panel_spec=PanelSpec(
            box=ROUNDED,
            border_style="cyan",
            padding=(0, 1),
        ),
        table_spec=TableSpec(
            show_header=False,
            show_lines=False,
            padding=(0, 1),
        )
    )
)

@app.default
def main(path: str, verbose: bool = False):
    """Process a file with combined customizations."""
    print(f"Processing {path}")

if __name__ == "__main__":
    app()

Output:

Different parameter groups can have different formatting styles, allowing you to visually distinguish between different types of options:

from cyclopts import App, Group, Parameter
from cyclopts.help import DefaultFormatter, PanelSpec
from rich.box import DOUBLE, MINIMAL
from typing import Annotated

# Create groups with different styles
required_group = Group(
    "Required Options",
    help_formatter=DefaultFormatter(
        panel_spec=PanelSpec(
            box=DOUBLE,
            border_style="red bold",
        )
    )
)

optional_group = Group(
    "Optional Settings",
    help_formatter=DefaultFormatter(
        panel_spec=PanelSpec(
            box=MINIMAL,
            border_style="green",
        )
    )
)

app = App()

@app.default
def main(
    # Required parameters with red double border
    input_file: Annotated[str, Parameter(group=required_group)],
    output_dir: Annotated[str, Parameter(group=required_group)],

    # Optional parameters with green minimal border
    verbose: Annotated[bool, Parameter(group=optional_group)] = False,
    threads: Annotated[int, Parameter(group=optional_group)] = 4,
):
    """Process files with styled help groups."""
    print(f"Processing {input_file} -> {output_dir}")
    if verbose:
        print(f"Using {threads} threads")

if __name__ == "__main__":
    app()

Output:

For complete control over the help table layout, you can define custom columns using ColumnSpec <#cyclopts.help.ColumnSpec>:

from cyclopts import App, Group, Parameter
from cyclopts.help import DefaultFormatter, ColumnSpec, TableSpec
from typing import Annotated

# Define custom column renderers
def names_renderer(entry):
    """Combine parameter names and shorts."""
    names = " ".join(entry.names) if entry.names else ""
    shorts = " ".join(entry.shorts) if entry.shorts else ""
    return f"{names} {shorts}".strip()

def type_renderer(entry):
    """Show the parameter type."""
    from cyclopts.annotations import get_hint_name
    return get_hint_name(entry.type) if entry.type else ""

# Create custom columns
custom_group = Group(
    "Custom Layout",
    help_formatter=DefaultFormatter(
        table_spec=TableSpec(show_header=True),
        column_specs=(
            ColumnSpec(
                renderer=lambda e: "★" if e.required else " ",
                header="",
                width=2,
                style="yellow bold",
            ),
            ColumnSpec(
                renderer=names_renderer,
                header="Option",
                style="cyan",
                max_width=30,
            ),
            ColumnSpec(
                renderer=type_renderer,
                header="Type",
                style="magenta",
                justify="center",
            ),
            ColumnSpec(
                renderer="description",  # Use attribute name
                header="Description",
                overflow="fold",
            ),
        )
    )
)

app = App()

@app.default
def main(
    input_path: Annotated[str, Parameter(group=custom_group, help="Input file path")],
    output_path: Annotated[str, Parameter(group=custom_group, help="Output file path")],
    count: Annotated[int, Parameter(group=custom_group, help="Number of iterations")] = 1,
):
    """Demo custom column layout."""
    print(f"Processing {input_path} -> {output_path} ({count} times)")

if __name__ == "__main__":
    app()

Output:

For even more flexibility, you can create columns dynamically based on runtime conditions:

from cyclopts import App, Parameter
from cyclopts.help import DefaultFormatter, ColumnSpec
from typing import Annotated

def dynamic_columns(console, options, entries):
    """Build columns based on console width and entries."""
    columns = []

    # Only show required indicator if there are required params
    if any(e.required for e in entries):
        columns.append(ColumnSpec(
            renderer=lambda e: "*" if e.required else "",
            width=2,
            style="red",
        ))

    # Adjust name column width based on console size
    max_width = min(40, int(console.width * 0.3))
    columns.append(ColumnSpec(
        renderer=lambda e: " ".join(e.names + e.shorts),
        header="Option",
        max_width=max_width,
        style="cyan",
    ))

    # Always include description
    columns.append(ColumnSpec(
        renderer="description",
        header="Description",
        overflow="fold",
    ))

    return tuple(columns)

app = App(
    help_formatter=DefaultFormatter(
        column_specs=dynamic_columns
    )
)

@app.default
def main(
    input_file: str,
    output_file: str,
    verbose: bool = False,
):
    """Process files with dynamic columns."""
    print(f"Processing {input_file} -> {output_file}")

if __name__ == "__main__":
    app()

Output (adjusts based on terminal width):

For complete control, you can implement your own formatter by following the HelpFormatter <#cyclopts.help.protocols.HelpFormatter> protocol. The formatter methods receive the console and options first, followed by the content to render:

from cyclopts import App
from cyclopts.help import HelpPanel
from rich.console import Console, ConsoleOptions
from rich.table import Table
from rich.panel import Panel

class MyCustomFormatter:
    """A custom formatter with unique styling."""

    def __call__(self, console: Console, options: ConsoleOptions, panel: HelpPanel) -> None:
        """Render a help panel with custom styling."""
        if not panel.entries:
            return

        # Create a custom table
        table = Table(show_header=True, header_style="bold magenta")
        table.add_column("Option", style="cyan", no_wrap=True)
        table.add_column("Description", style="white")

        for entry in panel.entries:
            name = " ".join(entry.names + entry.shorts)
            # Extract plain text from description (handles InlineText, etc)
            desc = ""
            if entry.description:
                if hasattr(entry.description, 'plain'):
                    desc = entry.description.plain
                elif hasattr(entry.description, '__rich_console__'):
                    # Render to plain text without styles
                    with console.capture() as capture:
                        console.print(entry.description, end="")
                    desc = capture.get()
                else:
                    desc = str(entry.description)
            table.add_row(name, desc)

        # Wrap in a custom panel
        panel_title = panel.title or "Options"
        styled_panel = Panel(
            table,
            title=f"[bold blue]{panel_title}[/bold blue]",
            border_style="blue",
        )

        console.print(styled_panel)

    def render_usage(self, console: Console, options: ConsoleOptions, usage) -> None:
        """Render the usage line."""
        if usage:
            console.print(f"[bold green]Usage:[/bold green] {usage}")

    def render_description(self, console: Console, options: ConsoleOptions, description) -> None:
        """Render the description."""
        if description:
            console.print(f"\n[italic]{description}[/italic]\n")

# Use the custom formatter
app = App(help_formatter=MyCustomFormatter())

@app.default
def main(input_file: str, output_file: str, verbose: bool = False):
    """Process files with custom formatter."""
    print(f"Processing {input_file} -> {output_file}")

if __name__ == "__main__":
    app()

Output:

For complete API documentation of help formatting components, see:

• cyclopts.help.DefaultFormatter <#cyclopts.help.DefaultFormatter> - Rich-based formatter with full customization
• cyclopts.help.PlainFormatter <#cyclopts.help.PlainFormatter> - Plain text formatter for accessibility
• cyclopts.help.PanelSpec <#cyclopts.help.PanelSpec> - Panel appearance specification
• cyclopts.help.TableSpec <#cyclopts.help.TableSpec> - Table styling specification
• cyclopts.help.ColumnSpec <#cyclopts.help.ColumnSpec> - Column definition and rendering
• cyclopts.help.protocols.HelpFormatter <#cyclopts.help.protocols.HelpFormatter> - Protocol for custom formatters

See also:

• Help <https://docs.python.org/3/library/argparse.html#help> - General help system documentation
• Groups <#groups> - Organizing parameters into groups

As an example, let's consider using the builtin dataclass <https://docs.python.org/3/library/dataclasses.html#dataclasses.dataclass> to make a CLI that manages a movie collection.

from cyclopts import App
from dataclasses import dataclass

app = App(name="movie-maintainer")

@dataclass
class Movie:
   title: str
   year: int

@app.command
def add(movie: Movie):
   print(f"Adding movie: {movie}")

app()

$ movie-maintainer add --help
Usage: movie-maintainer add [ARGS] [OPTIONS]

╭─ Parameters ────────────────────────────────────────────────╮
│ *  MOVIE.TITLE              [required]                      │
│      --movie.title                                          │
│ *  MOVIE.YEAR --movie.year  [required]                      │
╰─────────────────────────────────────────────────────────────╯

$ movie-maintainer add 'Mad Max: Fury Road' 2015
Adding movie: Movie(title='Mad Max: Fury Road', year=2015)

$ movie-maintainer add --movie.title 'Furiosa: A Mad Max Saga' --movie.year 2024
Adding movie: Movie(title='Furiosa: A Mad Max Saga', year=2024)

In most circumstances, Cyclopts will also parse a json-string for a dataclass-like parameter:

$ movie-maintainer add --movie='{"title": "Mad Max: Fury Road", "year": 2024}'
Adding movie: Movie(title='Mad Max: Fury Road', year=2024)

JSON dict parsing will be performed when:

1. The parameter is specified as a keyword option; e.g. --movie.
2. The referenced parameter type has various sub-arguments (is dataclass-like).
3. The referenced parameter is not union'd with a str.
4. The first character is a {.

This behavior can be configured via Parameter.json_dict <#cyclopts.Parameter.json_dict>.

from cyclopts import App
from dataclasses import dataclass

app = App(name="movie-manager")

@dataclass
class Movie:
   title: str
   year: int
   rating: float = 8.0

@app.command
def add(movie: Movie):
   print(f"Adding: {movie}")

app()

$ movie-manager add --movie '{"title": "Mad Max: Fury Road", "year": 2015, "rating": 8.1}'
Adding: Movie(title='Mad Max: Fury Road', year=2015, rating=8.1)

$ movie-manager add --movie '{"title": "Furiosa", "year": 2024}'
Adding: Movie(title='Furiosa', year=2024, rating=8.0)

Note that JSON parsing only works when using the keyword option format (--movie). The traditional positional argument format still works with individual fields:

$ movie-manager add --movie.title "Dune" --movie.year 2021 --movie.rating 8.5
Adding: Movie(title='Dune', year=2021, rating=8.5)

Cyclopts also supports JSON parsing for lists of dataclasses. This allows you to pass multiple structured objects via JSON:

from cyclopts import App
from dataclasses import dataclass

app = App(name="movie-collection")

@dataclass
class Movie:
   title: str
   year: int

@app.command
def add_batch(movies: list[Movie]):
   for movie in movies:
       print(f"Adding: {movie}")

app()

You can provide the list in several ways:

1. JSON Array - Multiple objects in a single argument:

   $ movie-collection add-batch --movies '[{"title": "Mad Max", "year": 2015}, {"title": "Furiosa", "year": 2024}]'
   Adding: Movie(title='Mad Max', year=2015)
   Adding: Movie(title='Furiosa', year=2024)

2. Individual JSON - Each object as a separate argument:

   $ movie-collection add-batch --movies '{"title": "Mad Max", "year": 2015}' --movies '{"title": "Furiosa", "year": 2024}'
   Adding: Movie(title='Mad Max', year=2015)
   Adding: Movie(title='Furiosa', year=2024)

3. Mixed - Combining arrays and individual objects:

   $ movie-collection add-batch --movies '{"title": "Mad Max", "year": 2015}' --movies '[{"title": "Furiosa", "year": 2024}, {"title": "Dune", "year": 2021}]'
   Adding: Movie(title='Mad Max', year=2015)
   Adding: Movie(title='Furiosa', year=2024)
   Adding: Movie(title='Dune', year=2021)

JSON list parsing is automatically enabled for list types containing dataclasses. The same rules apply as for dict parsing:

• The element type cannot be union'd with str
• JSON objects must start with { or be arrays starting with [

This behavior can be configured via Parameter.json_list <#cyclopts.Parameter.json_list>.

It is likely that the actual movie class/object is not important to the CLI user, and the parameter names like --movie.title are unnecessarily verbose. We can remove movie from the name by giving the Movie type annotation the special name "*".

from cyclopts import App, Parameter
from dataclasses import dataclass
from typing import Annotated

app = App(name="movie-maintainer")

@dataclass
class Movie:
   title: str
   year: int

@app.command
def add(movie: Annotated[Movie, Parameter(name="*")]):
   print(f"Adding movie: {movie}")

app()

$ movie-maintainer add --help
Usage: movie-maintainer add [ARGS] [OPTIONS]

╭─ Parameters ────────────────────────────────────────────────╮
│ *  TITLE --title  [required]                                │
│ *  YEAR --year    [required]                                │
╰─────────────────────────────────────────────────────────────╯

An alternative way of supplying the Parameter <#cyclopts.Parameter> configuration is via a decorator. This way can be cleaner and terser in many scenarios. The Parameter <#cyclopts.Parameter> configuration will also be inherited by subclasses.

from cyclopts import App, Parameter
from dataclasses import dataclass

app = App(name="movie-maintainer")

@Parameter(name="*")
@dataclass
class Movie:
   title: str
   year: int

@app.command
def add(movie: Movie):
   print(f"Adding movie: {movie}")

app()

A flattened dataclass provides a natural way of easily sharing a set of parameters between commands.

from cyclopts import App, Parameter
from dataclasses import dataclass

app = App(name="movie-maintainer")

@Parameter(name="*")
@dataclass
class Config:
   user: str
   server: str = "media.sqlite"

@dataclass
class Movie:
   title: str
   year: int

@app.command
def add(movie: Movie, *, config: Config):
   print(f"Config: {config}")
   print(f"Adding movie: {movie}")

@app.command
def remove(movie: Movie, *, config: Config):
   print(f"Config: {config}")
   print(f"Removing movie: {movie}")

app()

$ movie-maintainer remove --help
Usage: movie-maintainer remove [ARGS] [OPTIONS]

╭─ Parameters ────────────────────────────────────────────────╮
│ *  MOVIE.TITLE              [required]                      │
│      --movie.title                                          │
│ *  MOVIE.YEAR --movie.year  [required]                      │
│ *  --user                   [required]                      │
│    --server                 [default: media.sqlite]         │
╰─────────────────────────────────────────────────────────────╯

$ movie-maintainer remove 'Mad Max: Fury Road' 2015 --user Guido
Config: Config(user='Guido', server='media.sqlite')
Removing movie: Movie(title='Mad Max: Fury Road', year=2015)

Having the user specify --user every single call is a bit cumbersome, especially if they're always going to provide the same value. We can have Cyclopts fallback to a toml configuration file <#config-files>.

Consider the following toml data saved to config.toml:

# config.toml
user = "Guido"

We can update our app to fill in missing CLI parameters from this file:

from cyclopts import App, Parameter, config
from dataclasses import dataclass
from typing import Annotated

app = App(
   name="movie-maintainer",
   config=config.Toml("config.toml", use_commands_as_keys=False),
)

@Parameter(name="*")
@dataclass
class Config:
   user: str
   server: str = "media.sqlite"

@dataclass
class Movie:
   title: str
   year: int

@app.command
def add(movie: Movie, *, config: Config):
   print(f"Config: {config}")
   print(f"Adding movie: {movie}")

app()

$ movie-maintainer add 'Mad Max: Fury Road' 2015
Config: Config(user='Guido', server='media.sqlite')
Adding movie: Movie(title='Mad Max: Fury Road', year=2015)

A variable number of positional arguments consume all remaining positional arguments from the command-line. Individual elements are converted to the annotated type.

from cyclopts import App

app = App()

@app.command
def foo(name: str, *favorite_numbers: int):
    print(f"{name}'s favorite numbers are: {favorite_numbers}")

app()

$ my-script foo Brian
Brian's favorite numbers are: ()

$ my-script foo Brian 777
Brian's favorite numbers are: (777,)

$ my-script foo Brian 777 2
Brian's favorite numbers are: (777, 2)

A variable number of keyword arguments consume all remaining CLI tokens starting with --. Individual values are converted to the annotated type.

from cyclopts import App

app = App()

@app.command
def add(**country_to_capitols):
    for country, capitol in country_to_capitols.items():
        print(f"Adding {country} with capitol {capitol}.")

app()

$ my-script add --united-states="Washington, D.C." --canada=Ottawa
Adding united-states with capitol Washington, D.C..
Adding canada with capitol Ottawa.

In this example, we create a small CLI tool that counts the number of times a given character occurs in a file.

# character-counter.py
import cyclopts
from cyclopts import App
from pathlib import Path

app = App(
    name="character-counter",
    config=cyclopts.config.Toml(
        "pyproject.toml",  # Name of the TOML File
        root_keys=["tool", "character-counter"],  # The project's namespace in the TOML.
        # If "pyproject.toml" is not found in the current directory,
        # then iteratively search parenting directories until found.
        search_parents=True,
    ),
)

@app.command
def count(filename: Path, *, character="-"):
    print(filename.read_text().count(character))

if __name__ == "__main__":
    app()

Running this code without a pyproject.toml present:

$ python character-counter.py count README.md
70
$ python character-counter.py count README.md --character=t
380

We can have the new default character be t by adding the following to pyproject.toml:

[tool.character-counter.count]
character = "t"

Rerunning the app without a specified --character will result in using the toml-provided value:

$ python character-counter.py count README.md
380

Extending the above TOML Example, what if we want to allow the user to specify the toml configuration file? This can be accomplished via a Meta App <#meta-app>.

# character-counter.py
from pathlib import Path
from typing import Annotated

import cyclopts
from cyclopts import App, Parameter

app = App(name="character-counter")

@app.command
def count(filename: Path, *, character="-"):
    print(filename.read_text().count(character))

@app.meta.default
def meta(
    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
    config: Path = Path("pyproject.toml"),
):
    app.config = cyclopts.config.Toml(
        config,
        root_keys=["tool", "character-counter"],
        search_parents=True,
    )

    app(tokens)

if __name__ == "__main__":
    app.meta()

To automatically derive and read appropriate environment variables, use the cyclopts.config.Env <#cyclopts.config.Env> class. Continuing the above TOML example:

# character-counter.py
import cyclopts
from pathlib import Path

app = cyclopts.App(
    name="character-counter",
    config=cyclopts.config.Env(
        "CHAR_COUNTER_",  # Every environment variable will begin with this.
    ),
)

@app.command
def count(filename: Path, *, character="-"):
    print(filename.read_text().count(character))

app()

Env <#cyclopts.config.Env> assembles the environment variable name by joining the following components (in-order):

1. The provided prefix. In this case, it is "CHAR_COUNTER_".
2. The command and subcommand(s) that lead up to the function being executed.
3. The parameter's CLI name, with the leading -- stripped, and hyphens - replaced with underscores _.

Running this code without a specified --character results in counting the default - character.

$ python character-counter.py count README.md
70

By exporting a value to CHAR_COUNTER_COUNT_CHARACTER, that value will now be used as the default:

$ export CHAR_COUNTER_COUNT_CHARACTER=t
$ python character-counter.py count README.md
380
$ python character-counter.py count README.md --character=q
3

For configurations that come from sources other than files, use cyclopts.config.Dict <#cyclopts.config.Dict>.

# character-counter.py
import json
import cyclopts
from pathlib import Path

def fetch_config():
    """Simulate fetching configuration from an API."""
    return {"count": {"character": "e"}}

config_data = fetch_config_from_api()

app = cyclopts.App(
    name="character-counter",
    config=cyclopts.config.Dict(
        fetch_config,
        # Optional: provide custom source identifier for better error messages
        source="api",
    ),
)

@app.command
def count(filename: Path, *, character="-"):
    print(filename.read_text().count(character))

if __name__ == "__main__":
    app()

You can combine multiple config sources in a single application by passing a sequence to App.config <#cyclopts.App.config>. Each configuration is applied sequentially.

In the following example, we combine a TOML file and environment variables, allowing environment variables to override TOML settings:

# character-counter.py
import cyclopts
from pathlib import Path

app = cyclopts.App(
    name="character-counter",
    config=[
        # Since Env comes before Toml, it has priority.
        cyclopts.config.Env("CHAR_COUNTER_"),
        cyclopts.config.Toml(
            "pyproject.toml",
            root_keys=["tool", "character-counter"],
            search_parents=True,
        ),
    ],
)

@app.command
def count(filename: Path, *, character="-"):
    print(filename.read_text().count(character))

if __name__ == "__main__":
    app()

With this setup, the configuration is resolved in the following order:

1. CLI arguments (if provided) override everything else
2. Environment variables (prefixed with CHAR_COUNTER_) can override TOML values
3. TOML file (pyproject.toml) provides the base configuration
4. Python default the default value - in the python code.

For example, with pyproject.toml containing:

[tool.character-counter.count]
character = "t"

You can override it via environment variable:

$ CHAR_COUNTER_COUNT_CHARACTER=a python character-counter.py count README.md

Or via CLI argument:

$ python character-counter.py count README.md --character=x

• Quick Start

• Directive Usage

  • Basic Syntax
  • Module Path Formats

• Directive Options

  • :heading-level: - Heading Level
  • :max-heading-level: - Maximum Heading Level
  • :no-recursive: - Exclude Subcommands
  • :include-hidden: - Show Hidden Commands
  • :flatten-commands: - Generate Flat Command Hierarchy
  • :code-block-title: - Render Titles as Inline Code
  • :commands: - Filter Specific Commands
  • :exclude-commands: - Exclude Specific Commands
  • :skip-preamble: - Skip Description and Usage
  • Automatic Reference Labels

• Complete Example

  • CLI Application (myapp/cli.py):
  • Sphinx Configuration (docs/conf.py):
  • Documentation File (docs/cli.rst):

• Advanced Usage

  • Using Distinct Command Headings
  • Selective Command Documentation
• Output Formats
• See Also

1. Add the extension to your Sphinx configuration (docs/conf.py):

   extensions = [
       'cyclopts.sphinx_ext',  # Add this line
       # ... your other extensions
   ]

2. Use the directive in your RST files:

   .. cyclopts:: mypackage.cli:app

The cyclopts directive accepts a module path to your Cyclopts App object:

.. cyclopts:: mypackage.cli:app

The directive accepts two module path formats:

1. Explicit format (module.path:app_name):

   .. cyclopts:: mypackage.cli:app
   .. cyclopts:: myapp.commands:main_app
   .. cyclopts:: src.cli:cli

   This explicitly specifies which App object to document.

2. Automatic discovery (module.path):

   .. cyclopts:: mypackage.cli
   .. cyclopts:: myapp.main

   The extension will search the module for an App instance, looking for common names like app, cli, or main.

The directive supports several options to customize the generated documentation:

Set the starting heading level for the generated documentation (1-6, default: 2):

.. cyclopts:: mypackage.cli:app
   :heading-level: 3

This is useful when you need to adjust the heading hierarchy. The default of 2 works well for most cases where the directive is placed under a page title.

Set the maximum heading level to use (1-6, default: 6):

.. cyclopts:: mypackage.cli:app
   :max-heading-level: 4

Headings deeper than this level will be capped at this value. This is useful for deeply nested command hierarchies where you want to prevent headings from becoming too small.

Disable recursive documentation of subcommands (by default, subcommands are included):

.. cyclopts:: mypackage.cli:app
   :no-recursive:

When this flag is present, only the top-level commands are documented.

Include commands marked with show=False in the documentation:

.. cyclopts:: mypackage.cli:app
   :include-hidden: true

By default, hidden commands are not included in the generated documentation.

Generate all commands at the same heading level instead of nested hierarchy:

.. cyclopts:: mypackage.cli:app
   :flatten-commands:

This creates distinct, equally-weighted headings for each command and subcommand, making them easier to reference and navigate in the documentation. Without this option, subcommands are nested with incrementing heading levels.

Render command titles with inline code formatting instead of plain text:

.. cyclopts:: mypackage.cli:app
   :code-block-title:

When this flag is present, command titles are rendered with monospace formatting, which can be useful for certain documentation themes or to make command names stand out visually.

Document only specific commands from your CLI application:

.. cyclopts:: mypackage.cli:app
   :commands: init, build, deploy

This will only document the specified commands. You can also use nested command paths with dot notation:

.. cyclopts:: mypackage.cli:app
   :commands: db.migrate, db.backup, api

• db.migrate - Documents only the migrate subcommand under db
• db.backup - Documents only the backup subcommand under db
• api - Documents the api command and all its subcommands

You can use either underscore or dash notation in command names - they will be normalized automatically.

Exclude specific commands from the documentation:

.. cyclopts:: mypackage.cli:app
   :exclude-commands: debug, internal-test

This is useful for hiding internal or debug commands from user-facing documentation. Like :commands:, this also supports nested command paths with dot notation.

Skip the description and usage sections for the target command when filtering to a single command:

.. cyclopts:: mypackage.cli:app
   :commands: deploy
   :skip-preamble:

When you filter to a single command using :commands: and provide your own section heading in the RST, you may not want the directive to generate the command's description and usage block. Adding :skip-preamble: suppresses these sections while still generating the command's parameters and subcommands.

This is useful when you want to write your own introduction for a command section:

Deployment
==========

Deploy your application to production with these commands.

.. cyclopts:: mypackage.cli:app
   :commands: deploy
   :skip-preamble:

Without :skip-preamble:, the output would include both your introduction and the command's docstring description, which can be redundant.

The Sphinx directive automatically generates RST reference labels for all commands, enabling cross-referencing throughout your documentation. The anchor format is cyclopts-{app-name}-{command-path}, which prevents naming conflicts when documenting multiple CLIs.

For example: - Root application: cyclopts-myapp - Subcommand: cyclopts-myapp-deploy - Nested subcommand: cyclopts-myapp-deploy-production

You can reference these commands elsewhere in your documentation using :ref:`cyclopts-myapp-deploy`.

Here's a complete example showing a CLI application and its Sphinx documentation:

from pathlib import Path
from typing import Optional
from cyclopts import App

app = App(
    name="myapp",
    help="My awesome CLI application",
    version="1.0.0"
)

@app.command
def init(path: Path = Path("."), template: str = "default"):
    """Initialize a new project.

    Parameters
    ----------
    path : Path
        Directory where the project will be created
    template : str
        Project template to use
    """
    print(f"Initializing project at {path}")

@app.command
def build(source: Path, output: Optional[Path] = None, *, minify: bool = False):
    """Build the project.

    Parameters
    ----------
    source : Path
        Source directory
    output : Path, optional
        Output directory (defaults to source/dist)
    minify : bool
        Minify the output files
    """
    output = output or source / "dist"
    print(f"Building from {source} to {output}")

if __name__ == "__main__":
    app()

import sys
from pathlib import Path

# Add your package to the path
sys.path.insert(0, str(Path(__file__).parent.parent))

# Extensions
extensions = [
    'cyclopts.sphinx_ext',
    'sphinx.ext.autodoc',  # For API docs
    'sphinx.ext.napoleon',  # For NumPy-style docstrings
]

# Project info
project = 'MyApp'
author = 'Your Name'
version = '1.0.0'

# HTML theme
html_theme = 'sphinx_rtd_theme'