CLI Command Parser

User Guide

  • Getting Started
    • Parameters
      • Types
      • Names
    • Entry Points
    • Help Text
  • Commands
    • Defining Commands
    • Command Methods & Attributes
    • Parse & Run
    • Asyncio Applications
    • Advanced
      • Inheritance
      • Overriding Command Methods
        • Overriding main
        • Supported _sunder_ Methods
        • Initialization Methods
  • Parameters
    • Options
      • Option
      • Flag
      • TriFlag
      • Counter
    • Positionals
      • Positional
      • SubCommand
      • Action
    • Others
      • PassThru
      • ActionFlag
  • Parameter Groups
    • Mutually Exclusive
    • Mutually Dependent
    • Combining Group Types
      • How it Works
        • Mutually Exclusive Outer Group
        • Mutually Dependent Outer Group
        • Examples
  • Subcommands
    • Automatic Registration
    • Nested Subcommands
    • Explicit Registration
    • Shared Common Parameters
  • Input Types
    • Paths & Files
      • Path
      • File
      • Serialized Files
    • Numeric Ranges
      • Range
      • NumRange
    • Choice Inputs
      • Choices
      • ChoiceMap
      • EnumChoices
    • Regex & Glob Patterns
      • Regex
      • Glob
    • Date & Time
      • Day & Month
        • Day
        • Month
      • Full Date / Time Parsing
        • DateTime
        • Date
        • Time
      • Other Date / Time Inputs
        • TimeDelta
    • Manual Input Validation
  • Configuration
    • Command Metadata
    • Configuration Options
      • Error Handling Options
      • Parameter Options
      • ActionFlag Options
      • Parsing Options
      • Usage & Help Text Options
      • Documentation Generation Options
  • Documentation
    • Help Text
      • Help Text Breakdown
      • Parameter List Formatting
      • Group Formatting
    • reStructuredText
      • Generating RST Documentation
  • Error Handling
    • Configuration
    • Defining Error Handlers
    • Advanced
  • Advanced Usage
    • Dynamic Parameter Defaults
    • Post-Run & Context
    • Accessing Raw Argument Values
      • Parsed Args as a Dictionary
      • Parameters with Overridden Names
    • Mixing Actions & ActionFlags
  • Testing Commands
    • Testing Parsing
    • Test Helpers

API Documentation

  • API Documentation
    • Annotations Module
      • get_descriptor_value_type()
      • get_annotation_value_type()
    • Command_Parameters Module
      • CommandParameters
        • CommandParameters.action
        • CommandParameters.sub_command
        • CommandParameters.action_flags
        • CommandParameters.split_action_flags
        • CommandParameters.options
        • CommandParameters.combo_option_map
        • CommandParameters.groups
        • CommandParameters.positionals
        • CommandParameters.option_map
        • CommandParameters.command
        • CommandParameters.command_parent
        • CommandParameters.parent
        • CommandParameters.pass_thru
        • CommandParameters.has_nested_pass_thru
        • CommandParameters.all_positionals
        • CommandParameters.get_positionals_to_parse()
        • CommandParameters.formatter
        • CommandParameters.short_option_to_param_value_pairs()
        • CommandParameters.iter_params()
        • CommandParameters.required_check_params()
    • Commands Module
      • Command
        • Command.ctx
        • Command.parse_and_run()
        • Command.parse()
        • Command.__call__()
        • Command._pre_init_actions_()
        • Command._init_command_()
        • Command._before_main_()
        • Command.main()
        • Command._after_main_()
      • AsyncCommand
        • AsyncCommand.parse_and_run()
        • AsyncCommand.parse_and_await()
        • AsyncCommand.__call__()
        • AsyncCommand._pre_init_actions_()
        • AsyncCommand._before_main_()
        • AsyncCommand.main()
        • AsyncCommand._after_main_()
      • main()
    • Config Module
      • ShowDefaults
        • ShowDefaults.NEVER
        • ShowDefaults.MISSING
        • ShowDefaults.TRUTHY
        • ShowDefaults.NON_EMPTY
        • ShowDefaults.ANY
      • OptionNameMode
        • OptionNameMode.UNDERSCORE
        • OptionNameMode.DASH
        • OptionNameMode.BOTH
        • OptionNameMode.BOTH_UNDERSCORE
        • OptionNameMode.BOTH_DASH
        • OptionNameMode.NONE
      • SubcommandAliasHelpMode
        • SubcommandAliasHelpMode.REPEAT
        • SubcommandAliasHelpMode.COMBINE
        • SubcommandAliasHelpMode.ALIAS
      • AmbiguousComboMode
        • AmbiguousComboMode.IGNORE
        • AmbiguousComboMode.PERMISSIVE
        • AmbiguousComboMode.STRICT
      • AllowLeadingDash
        • AllowLeadingDash.NUMERIC
        • AllowLeadingDash.ALWAYS
        • AllowLeadingDash.NEVER
      • ConfigItem
        • ConfigItem.default
        • ConfigItem.type
        • ConfigItem.name
      • DynamicConfigItem
      • config_item()
      • CommandConfig
        • CommandConfig.FIELDS
        • CommandConfig.error_handler
        • CommandConfig.always_run_after_main
        • CommandConfig.allow_annotation_type
        • CommandConfig.multiple_action_flags
        • CommandConfig.action_after_action_flags
        • CommandConfig.ignore_unknown
        • CommandConfig.allow_missing
        • CommandConfig.allow_backtrack
        • CommandConfig.option_name_mode
        • CommandConfig.reject_ambiguous_pos_combos
        • CommandConfig.ambiguous_short_combos
        • CommandConfig.add_help
        • CommandConfig.use_type_metavar
        • CommandConfig.show_defaults
        • CommandConfig.show_env_vars
        • CommandConfig.cmd_alias_mode
        • CommandConfig.sort_choices
        • CommandConfig.choice_delim
        • CommandConfig.show_group_tree
        • CommandConfig.group_tree_spacers
        • CommandConfig.show_group_type
        • CommandConfig.command_formatter
        • CommandConfig.param_formatter
        • CommandConfig.extended_epilog
        • CommandConfig.usage_column_width
        • CommandConfig.strict_usage_column_width
        • CommandConfig.wrap_usage_str
        • CommandConfig.show_docstring
        • CommandConfig.show_inherited_descriptions
        • CommandConfig.sub_cmd_doc_depth
        • CommandConfig.as_dict()
    • Context Module
      • Context
        • Context.prog
        • Context.config
        • Context.allow_argv_prog
        • Context.for_prog()
        • Context.terminal_width
        • Context.get_parsed()
        • Context.params
        • Context.get_error_handler()
        • Context.has_parsed_value()
        • Context.get_parsed_value()
        • Context.set_parsed_value()
        • Context.pop_parsed_value()
        • Context.roll_back_parsed_values()
        • Context.record_action()
        • Context.num_provided()
        • Context.get_missing()
        • Context.missing_options_with_env_var()
        • Context.action_flag_count
        • Context.all_action_flags
        • Context.categorized_action_flags
        • Context.iter_action_flags()
      • ActionPhase
        • ActionPhase.PRE_INIT
        • ActionPhase.BEFORE_MAIN
        • ActionPhase.AFTER_MAIN
      • ContextProxy
        • ContextProxy.has_parsed_value()
        • ContextProxy.get_parsed_value()
        • ContextProxy.set_parsed_value()
        • ContextProxy.record_action()
        • ContextProxy.num_provided()
        • ContextProxy.terminal_width
        • ContextProxy.config
      • get_current_context()
      • get_or_create_context()
      • get_context()
      • get_parsed()
      • get_raw_arg()
    • Conversion Package
      • Argparse_Ast Module
        • Script
        • visit_func
        • AddVisitedChild
        • AstCallable
        • ParserArg
        • ArgCollection
        • ArgGroup
        • MutuallyExclusiveGroup
        • SubparsersAction
        • AstArgumentParser
        • SubParser
      • Argparse_Utils Module
        • ArgumentParser
        • SubParsersAction
      • Cli Module
        • ParserConverter
        • Convert
        • Pprint
      • Command_Builder Module
        • convert_script()
        • Converter
        • ConverterGroup
        • ScriptConverter
        • CollectionConverter
        • ParserConverter
        • GroupConverter
        • ParamConverter
        • ParamConverterGroup
        • BaseArgs
        • CommandArgs
        • ParamBaseArgs
        • PassThruArgs
        • ParamArgs
        • OptionArgs
        • FlagArgs
        • literal_eval_or_none()
        • ConversionError
      • Utils Module
        • get_name_repr()
        • iter_module_parents()
        • collection_contents()
      • Visitor Module
        • scoped()
        • ScopedVisit
        • ScriptVisitor
        • TrackedRef
        • imp_names()
    • Core Module
      • CommandMeta
        • CommandMeta.config()
        • CommandMeta.parent()
        • CommandMeta.params()
        • CommandMeta.meta()
      • get_parent()
      • get_config()
      • get_metadata()
      • get_params()
      • get_top_level_commands()
    • Documentation Module
      • render_script_rst()
      • render_command_rst()
      • load_commands()
      • filtered_commands()
      • top_level_commands()
      • import_module()
      • RstWriter
        • RstWriter.document_script()
        • RstWriter.document_scripts()
        • RstWriter.document_module()
        • RstWriter.document_package()
        • RstWriter.write_index()
        • RstWriter.write_rst()
    • Error_Handling Module
      • ErrorHandler
        • ErrorHandler.exc_handler_map
        • ErrorHandler.register()
        • ErrorHandler.unregister()
        • ErrorHandler.__call__()
        • ErrorHandler.cls_handler()
        • ErrorHandler.iter_handlers()
        • ErrorHandler.copy()
      • NullErrorHandler
      • Handler
        • Handler.exc_cls
        • Handler.handler
      • error_handler
      • handle_kb_interrupt()
      • no_exit_handler
      • extended_error_handler
    • Exceptions Module
      • CommandParserException
        • CommandParserException.code
        • CommandParserException.show()
        • CommandParserException.exit()
      • ParserExit
      • CommandDefinitionError
      • ParameterDefinitionError
      • AmbiguousShortForm
      • AmbiguousParseTree
      • UsageError
        • UsageError.message
      • ParamUsageError
      • MultiParamUsageError
      • AmbiguousCombo
      • ParamConflict
      • ParamsMissing
      • BadArgument
      • InvalidChoice
      • MissingArgument
        • MissingArgument.message
      • TooManyArguments
      • NoSuchOption
      • NoActiveContext
      • Backtrack
      • NextCommand
    • Formatting Package
      • Commands Module
        • CommandHelpFormatter
        • get_formatter()
        • get_usage_sub_cmds()
      • Params Module
        • ParamHelpFormatter
        • PositionalHelpFormatter
        • OptionHelpFormatter
        • TriFlagHelpFormatter
        • ChoiceMapHelpFormatter
        • ChoiceGroup
        • PassThruHelpFormatter
        • GroupHelpFormatter
      • Restructured_Text Module
        • rst_bar()
        • rst_header()
        • spaced_rst_header()
        • rst_directive()
        • rst_toc_tree()
        • rst_list_table()
        • RstTable
        • Cell
        • Row
      • Utils Module
        • format_help_entry()
        • PartWrapper
        • line_iter()
    • Inputs Package
      • Base Module
        • InputType
      • Choices Module
        • Choices
        • ChoiceMap
        • EnumChoices
      • Exceptions Module
        • InputValidationError
        • InvalidChoiceError
      • Files Module
        • FileInput
        • Path
        • File
        • Serialized
        • Json
        • Pickle
      • Numeric Module
        • NumericInput
        • Range
        • NumRange
      • Patterns Module
        • PatternInput
        • RegexMode
        • Regex
        • Glob
      • Time Module
        • different_locale
        • DTInput
        • DTFormatMode
        • CalendarUnitInput
        • Day
        • Month
        • TimeDelta
        • DateTimeInput
        • DateTime
        • Date
        • Time
        • dt_repr()
        • normalize_dt()
      • Utils Module
        • InputParam
        • StatMode
        • FileWrapper
        • allows_write()
        • fix_windows_path()
        • range_str()
        • RangeMixin
    • Metadata Module
      • MetadataBase
        • MetadataBase.inheritable
        • MetadataBase.get_parent()
        • MetadataBase.get_value()
        • MetadataBase.name
      • Metadata
        • Metadata.default
        • Metadata.get_value()
      • DynamicMetadata
        • DynamicMetadata.func
        • DynamicMetadata.get_value()
      • dynamic_metadata()
      • ProgramMetadata
        • ProgramMetadata.parent
        • ProgramMetadata.distribution
        • ProgramMetadata.path
        • ProgramMetadata.package
        • ProgramMetadata.module
        • ProgramMetadata.cmd_module
        • ProgramMetadata.command
        • ProgramMetadata.usage
        • ProgramMetadata.description
        • ProgramMetadata.epilog
        • ProgramMetadata.doc_str
        • ProgramMetadata.pkg_doc_str
        • ProgramMetadata.for_command()
        • ProgramMetadata.prog
        • ProgramMetadata.get_prog()
        • ProgramMetadata.doc_name
        • ProgramMetadata.version
        • ProgramMetadata.email
        • ProgramMetadata.url
        • ProgramMetadata.docs_url
        • ProgramMetadata.format_epilog()
        • ProgramMetadata.get_doc_str()
        • ProgramMetadata.get_description()
      • ProgFinder
        • ProgFinder.mod_obj_prog_map
        • ProgFinder.normalize()
      • DistributionFinder
        • DistributionFinder.dist_for_pkg()
        • DistributionFinder.dist_for_obj()
        • DistributionFinder.get_urls()
    • Nargs Module
      • Nargs
        • Nargs.range
        • Nargs.min
        • Nargs.max
        • Nargs.allowed
        • Nargs.variable
        • Nargs.satisfied()
        • Nargs.max_reached()
        • Nargs.has_upper_bound
        • Nargs.upper_bound
      • nargs_min_and_max_sums()
    • Parameters Package
      • Actions Module
        • ParamAction
        • ValueMixin
        • ConstMixin
        • Store
        • Append
        • BasicConstAction
        • StoreConst
        • AppendConst
        • Count
        • Concatenate
        • StoreAll
      • Base Module
        • ParamBase
        • Parameter
        • BasePositional
        • BaseOption
        • AllowLeadingDashProperty
        • DefaultCallback
      • Choice_Map Module
        • Choice
        • ChoiceMap
        • SubCommand
        • Action
      • Groups Module
        • ParamGroup
      • Option_Strings Module
        • OptionStrings
        • TriFlagOptionStrings
      • Options Module
        • Option
        • Flag
        • TriFlag
        • ActionFlag
        • action_flag
        • before_main()
        • after_main()
        • help_action()
        • Counter
      • Pass_Thru Module
        • PassThru
      • Positionals Module
        • Positional
    • Parse_Tree Module
      • AnyWord
        • AnyWord.nargs
        • AnyWord.n
        • AnyWord.remaining
      • PosNode
        • PosNode.links
        • PosNode.param
        • PosNode.parent
        • PosNode.target
        • PosNode.word
        • PosNode.link_params()
        • PosNode.nargs_min_and_max()
        • PosNode.any_word
        • PosNode.any_node
        • PosNode.has_any()
        • PosNode.raw_path
        • PosNode.path_repr()
        • PosNode.build_tree()
        • PosNode.update_node()
        • PosNode.print_tree()
      • process_params()
      • process_param()
    • Parser Module
      • CommandParser
        • CommandParser.arg_deque
        • CommandParser.deferred
        • CommandParser.ctx
        • CommandParser.params
        • CommandParser.positionals
        • CommandParser.config
        • CommandParser.parse_args_and_get_next_cmd()
        • CommandParser.get_next_cmd()
        • CommandParser.handle_pass_thru()
        • CommandParser.handle_remainder()
        • CommandParser.handle_positional()
        • CommandParser.handle_long()
        • CommandParser.handle_short()
        • CommandParser.consume_values()
      • parse_args_and_get_next_cmd()
      • get_opt_prefix()
    • Testing Module
      • AssertRaisesWithStringContext
        • AssertRaisesWithStringContext.test_case
        • AssertRaisesWithStringContext.expected_exc
        • AssertRaisesWithStringContext.expected_text
        • AssertRaisesWithStringContext.msg
      • ParserTest
        • ParserTest.assert_dict_equal()
        • ParserTest.assert_raises_contains_str()
        • ParserTest.assert_parse_results()
        • ParserTest.assert_parse_results_cases()
        • ParserTest.assert_env_parse_results()
        • ParserTest.assert_env_parse_results_cases()
        • ParserTest.assert_parse_fails()
        • ParserTest.assert_parse_fails_cases()
        • ParserTest.assert_argv_parse_fails_cases()
        • ParserTest.assert_call_fails()
        • ParserTest.assert_call_fails_cases()
        • ParserTest.assert_strings_equal()
        • ParserTest.assert_str_starts_with_line()
        • ParserTest.assert_str_contains()
        • ParserTest.env_vars()
      • format_diff()
      • format_dict_diff()
      • RedirectStreams
        • RedirectStreams.stdout
        • RedirectStreams.stderr
      • get_usage_text()
      • get_help_text()
      • get_rst_text()
      • sealed_mock()
      • load_command()
      • TemporaryDir
    • Typing Module
    • Utils Module
      • camel_to_snake_case()
      • short_repr()
      • MissingMixin
      • FixedFlagMeta
      • FixedFlag
      • Terminal
        • Terminal.width
      • str_to_bool()
      • positive_int()
      • maybe_await()

Example Script Docs

  • Example Scripts
    • Action With Args
    • Advanced Subcommand
      • Subcommands
        • Subcommand: foo
        • Subcommand: run foo
        • Subcommand: run bar
        • Subcommand: baz
    • Basic Subcommand
      • Subcommands
        • Subcommand: foo
        • Subcommand: bar
    • Command Wrapper
    • Complex Example
      • Subcommands
        • Subcommand: hello
        • Subcommand: logs
        • Subcommand: update
        • Subcommand: update foo
        • Subcommand: update bar
        • Subcommand: update user
        • Subcommand: update group
    • Custom Inputs
    • Echo
    • Grouped Action Flags
    • Hello World
    • Rest Api Wrapper
      • Subcommands
        • Subcommand: show
        • Subcommand: sync
        • Subcommand: find
        • Subcommand: find foo
        • Subcommand: find bar
        • Subcommand: find baz
        • Subcommand: find bazs
    • Shared Logging Init
      • Subcommands
        • Subcommand: show
    • Simple Flags
CLI Command Parser
  • Overview: module code

All modules for which code is available

  • cli_command_parser.annotations
  • cli_command_parser.command_parameters
  • cli_command_parser.commands
  • cli_command_parser.config
  • cli_command_parser.context
  • cli_command_parser.conversion.argparse_ast
  • cli_command_parser.conversion.argparse_utils
  • cli_command_parser.conversion.cli
  • cli_command_parser.conversion.command_builder
  • cli_command_parser.conversion.utils
  • cli_command_parser.conversion.visitor
  • cli_command_parser.core
  • cli_command_parser.documentation
  • cli_command_parser.error_handling
  • cli_command_parser.exceptions
  • cli_command_parser.formatting.commands
  • cli_command_parser.formatting.params
  • cli_command_parser.formatting.restructured_text
  • cli_command_parser.formatting.utils
  • cli_command_parser.inputs.base
  • cli_command_parser.inputs.choices
  • cli_command_parser.inputs.exceptions
  • cli_command_parser.inputs.files
  • cli_command_parser.inputs.numeric
  • cli_command_parser.inputs.patterns
  • cli_command_parser.inputs.time
  • cli_command_parser.inputs.utils
  • cli_command_parser.metadata
  • cli_command_parser.nargs
  • cli_command_parser.parameters.actions
  • cli_command_parser.parameters.base
  • cli_command_parser.parameters.choice_map
  • cli_command_parser.parameters.groups
  • cli_command_parser.parameters.option_strings
  • cli_command_parser.parameters.options
  • cli_command_parser.parameters.pass_thru
  • cli_command_parser.parameters.positionals
  • cli_command_parser.parse_tree
  • cli_command_parser.parser
  • cli_command_parser.testing
  • cli_command_parser.utils

© Copyright 2025, Doug Skrypa.

Built with Sphinx using a theme provided by Read the Docs.