cliffy_schema.json

{
    "$defs": {
        "Command": {
            "description": "Defines a single command within the CLI. It specifies the command's execution logic,\nparameters, and configuration.",
            "properties": {
                "run": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/RunBlock"
                        },
                        {
                            "$ref": "#/$defs/RunBlockList"
                        }
                    ],
                    "default": "",
                    "title": "Run"
                },
                "help": {
                    "default": "",
                    "description": "A description of the command, displayed in the help output.",
                    "title": "Help",
                    "type": "string"
                },
                "params": {
                    "default": [],
                    "description": "A list of parameters for the command.\nThere are three ways to define a param: \n(generic) 1. A string as param definition. Gets appended to the command params signature.\n(implicit) 2. A mapping with the param name as the key and the type as the value. Custom types are accepted here. Same as the implicit v1 params syntax. \n(explicit) 3. A mapping with the following keys: `name` (required), `type` (required), `default` (None by default), `help` (Optional), `short` (Optional), `required` (False by default).",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/$defs/CommandParam"
                            },
                            {
                                "$ref": "#/$defs/SimpleCommandParam"
                            },
                            {
                                "$ref": "#/$defs/GenericCommandParam"
                            }
                        ]
                    },
                    "title": "Params",
                    "type": "array"
                },
                "template": {
                    "default": "",
                    "description": "A reference to a command template defined in the `command_templates` section of the manifest. This allows for reusable command definitions.",
                    "title": "Template",
                    "type": "string"
                },
                "pre_run": {
                    "$ref": "#/$defs/PreRunBlock",
                    "default": "",
                    "description": "Script to run before the command's run block. This can be used for setup tasks or preconditions."
                },
                "post_run": {
                    "$ref": "#/$defs/PostRunBlock",
                    "default": "",
                    "description": "Script to run after the command's run block. This can be used for cleanup tasks or post-processing."
                },
                "aliases": {
                    "default": [],
                    "description": "A list of aliases for the command. These aliases can be used to invoke the command with a different name.",
                    "items": {
                        "type": "string"
                    },
                    "title": "Aliases",
                    "type": "array"
                },
                "name": {
                    "default": "",
                    "description": "The name of the command. This is generally derived from the key in the `commands` section of the manifest, but can be explicitly set here.",
                    "title": "Name",
                    "type": "string"
                },
                "config": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/CommandConfig"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "default": null,
                    "description": "An optional `CommandConfig` object that provides additional configuration options for the command, such as context settings, help text customization, and visibility."
                }
            },
            "title": "Command",
            "type": "object"
        },
        "CommandConfig": {
            "description": "Configuration options for a Cliffy command.",
            "properties": {
                "context_settings": {
                    "default": {},
                    "description": "Arbitrary settings passed to Click's context. Useful for things\n        like overriding the default `max_content_width`.\n        See Click's documentation for more details:\n        https://click.palletsprojects.com/en/8.1.x/advanced/#context-settings",
                    "title": "Context Settings",
                    "type": "object"
                },
                "epilog": {
                    "default": "",
                    "description": "Text displayed after the help message.",
                    "title": "Epilog",
                    "type": "string"
                },
                "short_help": {
                    "default": "",
                    "description": "Short one-line help message displayed in help overviews.",
                    "title": "Short Help",
                    "type": "string"
                },
                "options_metavar": {
                    "default": "[OPTIONS]",
                    "description": "Placeholder text displayed for options in help messages.",
                    "title": "Options Metavar",
                    "type": "string"
                },
                "add_help_option": {
                    "default": true,
                    "description": "Whether to add the `--help` option automatically.",
                    "title": "Add Help Option",
                    "type": "boolean"
                },
                "no_args_is_help": {
                    "default": false,
                    "description": "If True, invoking the command without any arguments displays the help message.",
                    "title": "No Args Is Help",
                    "type": "boolean"
                },
                "hidden": {
                    "default": false,
                    "description": "If True, the command is hidden from help messages and command lists.",
                    "title": "Hidden",
                    "type": "boolean"
                },
                "deprecated": {
                    "default": false,
                    "description": "If True, the command is marked as deprecated in help messages.",
                    "title": "Deprecated",
                    "type": "boolean"
                },
                "rich_help_panel": {
                    "default": "",
                    "description": "Name of a Rich help panel to display after the default help. This is useful for\n        displaying more complex help information, such as tables or formatted text.\n        The content of the panel is defined using the `@rich_help` decorator.",
                    "title": "Rich Help Panel",
                    "type": "string"
                }
            },
            "title": "CommandConfig",
            "type": "object"
        },
        "CommandParam": {
            "description": "Defines the structure of a command parameter. It is used\nwithin the `params` field of a `Command` object.\n\nBy default, parameters are treated as positional arguments. To specify an option, prefix the name with `--` to indicate flag.",
            "properties": {
                "name": {
                    "description": "Parameter name. Prefix with `--` to indicate an option.",
                    "title": "Name",
                    "type": "string"
                },
                "type": {
                    "description": "Parameter type (e.g., 'str', 'int', 'bool', or a custom type defined in the manifest's 'types' section).",
                    "title": "Type",
                    "type": "string"
                },
                "default": {
                    "default": null,
                    "description": "Default parameter value.",
                    "title": "Default"
                },
                "help": {
                    "default": "",
                    "description": "Parameter description.",
                    "title": "Help",
                    "type": "string"
                },
                "short": {
                    "default": "",
                    "description": "Short option alias. i.e. '-v' for verbose.",
                    "title": "Short",
                    "type": "string"
                },
                "required": {
                    "default": false,
                    "description": "Whether the parameter is required.",
                    "title": "Required",
                    "type": "boolean"
                }
            },
            "required": [
                "name",
                "type"
            ],
            "title": "CommandParam",
            "type": "object"
        },
        "CommandTemplate": {
            "description": "Defines a reusable template for command definitions.  Templates allow you to define\ncommon parameters, pre-run/post-run scripts, and configuration options that can be\napplied to multiple commands.",
            "properties": {
                "params": {
                    "default": [],
                    "description": "A list of parameters for the command template.  These parameters will be applied to any command that uses this template.",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/$defs/CommandParam"
                            },
                            {
                                "$ref": "#/$defs/SimpleCommandParam"
                            },
                            {
                                "$ref": "#/$defs/GenericCommandParam"
                            }
                        ]
                    },
                    "title": "Params",
                    "type": "array"
                },
                "pre_run": {
                    "$ref": "#/$defs/PreRunBlock",
                    "default": "",
                    "description": "Script to run before the command's run and pre-run block. This script will be applied to any command that uses this template."
                },
                "post_run": {
                    "$ref": "#/$defs/PostRunBlock",
                    "default": "",
                    "description": "Script to run after the command's run and post-run block. This script will be applied to any command that uses this template."
                },
                "config": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/CommandConfig"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "default": null,
                    "description": "Additional configuration options for commands using this template. This allows customization of help text, context settings, and other Typer command parameters."
                }
            },
            "title": "CommandTemplate",
            "type": "object"
        },
        "GenericCommandParam": {
            "title": "Generic Command Param\nGets appended to the command params signature.",
            "type": "string"
        },
        "PostRunBlock": {
            "title": "Post-run Block",
            "type": "string"
        },
        "PreRunBlock": {
            "title": "Pre-run Block",
            "type": "string"
        },
        "RunBlock": {
            "description": "Command execution logic. Lines prefixed with '$' are treated as shell commands.",
            "title": "Command Run Block",
            "type": "string"
        },
        "RunBlockList": {
            "items": {
                "$ref": "#/$defs/RunBlock"
            },
            "title": "Run Block List\nList of Run Blocks executed in order.",
            "type": "array"
        },
        "SimpleCommandParam": {
            "additionalProperties": {
                "type": "string"
            },
            "maxProperties": 1,
            "minProperties": 1,
            "title": "Simple Command Param\nBuild params with key as the param name and value as the type and default vals, i.e. `verbose: bool = typer.Option(...)`",
            "type": "object"
        }
    },
    "additionalProperties": true,
    "properties": {
        "manifestVersion": {
            "default": "v3",
            "title": "Manifestversion",
            "type": "string"
        },
        "name": {
            "description": "The name of the CLI, used when invoking from command line.",
            "title": "Name",
            "type": "string"
        },
        "version": {
            "description": "CLI version",
            "title": "Version",
            "type": "string"
        },
        "help": {
            "default": "",
            "description": "Brief description of the CLI",
            "title": "Help",
            "type": "string"
        },
        "use_click": {
            "default": false,
            "description": "Generate CLI to Click instead of Typer",
            "title": "Use Click",
            "type": "boolean"
        },
        "requires": {
            "default": [],
            "description": "List of Python package dependencies for the CLI.Supports requirements specifier syntax.",
            "items": {
                "type": "string"
            },
            "title": "Requires",
            "type": "array"
        },
        "includes": {
            "default": [],
            "description": "List of external CLI manifests to include.Performs a deep merge of manifests sequentially in the order given to assemble a merged manifest. and finally, deep merges the merged manifest with this manifest.",
            "items": {
                "type": "string"
            },
            "title": "Includes",
            "type": "array"
        },
        "vars": {
            "additionalProperties": {
                "anyOf": [
                    {
                        "type": "string"
                    },
                    {
                        "additionalProperties": {
                            "type": "null"
                        },
                        "type": "object"
                    }
                ]
            },
            "description": "Mapping defining manifest variables that can be referenced in any other blocks. Environments variables can be used in this section with ${some_env_var} for dynamic parsing. Supports jinja2 formatted expressions as values. Interpolate defined vars in other blocks jinja2-styled {{ var_name }}.",
            "title": "Vars",
            "type": "object"
        },
        "imports": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                }
            ],
            "default": [],
            "description": "String block or list of strings containing any module imports. These can be used to import any python modules that the CLI depends on.",
            "title": "Imports"
        },
        "functions": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                }
            ],
            "default": [],
            "description": "String block or list of helper function definitions. These functions should be defined as strings that can be executed by the Python interpreter.",
            "title": "Functions"
        },
        "types": {
            "additionalProperties": {
                "type": "string"
            },
            "description": "A mapping containing any shared type definitions. These types can be referenced by name in the params section to provide type annotations for args and options defined in the params section.",
            "title": "Types",
            "type": "object"
        },
        "global_params": {
            "default": [],
            "description": "Parameters applied to all commands",
            "items": {
                "anyOf": [
                    {
                        "$ref": "#/$defs/CommandParam"
                    },
                    {
                        "$ref": "#/$defs/SimpleCommandParam"
                    },
                    {
                        "$ref": "#/$defs/GenericCommandParam"
                    }
                ]
            },
            "title": "Global Params",
            "type": "array"
        },
        "command_templates": {
            "additionalProperties": {
                "$ref": "#/$defs/CommandTemplate"
            },
            "description": "Reusable command templates",
            "title": "Command Templates",
            "type": "object"
        },
        "commands": {
            "additionalProperties": {
                "anyOf": [
                    {
                        "$ref": "#/$defs/Command"
                    },
                    {
                        "$ref": "#/$defs/RunBlock"
                    },
                    {
                        "$ref": "#/$defs/RunBlockList"
                    }
                ]
            },
            "description": "A mapping containing the command definitions for the CLI. Each command should have a unique key- which can be either a group command or nested subcommands. Nested subcommands are joined by '.' in between each level. Aliases for commands can be separated in the key by '|'. A special '(*)' wildcard can be used to spread the subcommand to all group-level commands",
            "title": "Commands",
            "type": "object"
        },
        "cli_options": {
            "description": "Additional CLI configuration options",
            "title": "Cli Options",
            "type": "object"
        },
        "tests": {
            "default": [],
            "description": "Test cases for commands",
            "items": {
                "anyOf": [
                    {
                        "type": "string"
                    },
                    {
                        "additionalProperties": {
                            "type": "string"
                        },
                        "type": "object"
                    }
                ]
            },
            "title": "Tests",
            "type": "array"
        }
    },
    "required": [
        "name",
        "version",
        "commands"
    ],
    "title": "CLIManifest",
    "type": "object"
}