Skip to content

Submodule cli

derivepassphrase.cli

Command-line interface for derivepassphrase.

ClickEchoStderrHandler

Bases: Handler

A logging.Handler for click applications.

Outputs log messages to sys.stderr via click.echo.

emit

emit(record: LogRecord) -> None

Emit a log record.

Format the log record, then emit it via click.echo to sys.stderr.

CLIofPackageFormatter

CLIofPackageFormatter(
    *,
    prog_name: str = PROG_NAME,
    package_name: str | None = None
)

Bases: Formatter

A logging.LogRecord formatter for the CLI of a Python package.

Assuming a package PKG and loggers within the same hierarchy PKG, format all log records from that hierarchy for proper user feedback on the console. Intended for use with click and when PKG provides a command-line tool PKG and when logs from that package should show up as output of the command-line tool.

Essentially, this prepends certain short strings to the log message lines to make them readable as standard error output.

Because this log output is intended to be displayed on standard error as high-level diagnostic output, you are strongly discouraged from changing the output format to include more tokens besides the log message. Use a dedicated log file handler instead, without this formatter.

format

format(record: LogRecord) -> str

Format a log record suitably for standard error console output.

Prepend the formatted string "PROG_NAME: LABEL" to each line of the message, where PROG_NAME is the program name, and LABEL depends on the record’s level and on the logger name as follows:

  • For records at level logging.DEBUG, LABEL is "Debug: ".
  • For records at level logging.INFO, LABEL is the empty string.
  • For records at level logging.WARNING, LABEL is "Deprecation warning: " if the logger is named PKG.deprecation (where PKG is the package name), else "Warning: ".
  • For records at level logging.ERROR and logging.CRITICAL "Error: ", LABEL is the empty string.

The level indication strings at level WARNING or above are highlighted. Use click.echo to output them and remove color output if necessary.

Parameters:

Name Type Description Default
record LogRecord

A log record.

required

Returns:

Type Description
str

A formatted log record.

Raises:

Type Description
AssertionError

The log level is not supported.

StandardCLILogging

Set up CLI logging handlers upon instantiation.

ensure_standard_logging classmethod

ensure_standard_logging() -> StandardLoggingContextManager

Return a context manager to ensure standard logging is set up.

ensure_standard_warnings_logging classmethod

ensure_standard_warnings_logging() -> (
    StandardWarningsLoggingContextManager
)

Return a context manager to ensure warnings logging is set up.

StandardLoggingContextManager

StandardLoggingContextManager(
    handler: Handler, root_logger: str | None = None
)

A reentrant context manager setting up standard CLI logging.

Ensures that the given handler (defaulting to the CLI logging handler) is added to the named logger (defaulting to the root logger), and if it had to be added, then that it will be removed upon exiting the context.

Reentrant, but not thread safe, because it temporarily modifies global state.

StandardWarningsLoggingContextManager

StandardWarningsLoggingContextManager(handler: Handler)

Bases: StandardLoggingContextManager

A reentrant context manager setting up standard warnings logging.

Ensures that warnings are being diverted to the logging system, and that the given handler (defaulting to the CLI logging handler) is added to the warnings logger. If the handler had to be added, then it will be removed upon exiting the context.

Reentrant, but not thread safe, because it temporarily modifies global state.

OptionGroupOption

OptionGroupOption(*args: Any, **kwargs: Any)

Bases: Option

A click.Option with an associated group name and group epilog.

Used by CommandWithHelpGroups to print help sections. Each subclass contains its own group name and epilog.

Attributes:

Name Type Description
option_group_name object

The name of the option group. Used as a heading on the help text for options in this section.

epilog object

An epilog to print after listing the options in this section.

option_group_name class-attribute instance-attribute

option_group_name: object = ''

epilog class-attribute instance-attribute

epilog: object = ''

CommandWithHelpGroups

Bases: Command

A click.Command with support for some help text customizations.

Supports help/option groups, group epilogs, and help text objects (objects that stringify to help texts). The latter is primarily used to implement translations.

Inspired by a comment on pallets/click#373 for help/option group support, and further modified to include group epilogs and help text objects.

collect_usage_pieces

collect_usage_pieces(ctx: Context) -> list[str]

Return the pieces for the usage string.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are marked with respective comments. They too are released under the same license above. The original code did not contain any “noqa” or “pragma” comments.

Parameters:

Name Type Description Default
ctx Context

The click context.

required

get_help_option

get_help_option(ctx: Context) -> Option | None

Return a standard help option object.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are marked with respective comments. They too are released under the same license above. The original code did not contain any “noqa” or “pragma” comments.

Parameters:

Name Type Description Default
ctx Context

The click context.

required

get_short_help_str

get_short_help_str(limit: int = 45) -> str

Return the short help string for a command.

If only a long help string is given, shorten it.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are marked with respective comments. They too are released under the same license above. The original code did not contain any “noqa” or “pragma” comments.

Parameters:

Name Type Description Default
limit int

The maximum width of the short help string.

45

format_help_text

format_help_text(
    ctx: Context, formatter: HelpFormatter
) -> None

Format the help text prologue, if any.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are marked with respective comments. They too are released under the same license above. The original code did not contain any “noqa” or “pragma” comments.

Parameters:

Name Type Description Default
ctx Context

The click context.

required
formatter HelpFormatter

The formatter for the --help listing.

required

format_options

format_options(
    ctx: Context, formatter: HelpFormatter
) -> None

Format options on the help listing, grouped into sections.

This is a callback for click.Command.get_help that implements the --help listing, by calling appropriate methods of the formatter. We list all options (like the base implementation), but grouped into sections according to the concrete click.Option subclass being used. If the option is an instance of some subclass of OptionGroupOption, then the section heading and the epilog are taken from the option_group_name and epilog attributes; otherwise, the section heading is “Options” (or “Other options” if there are other option groups) and the epilog is empty.

We unconditionally call format_commands, and rely on it to act as a no-op if we aren’t actually a click.MultiCommand.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are released under the same license above.

Parameters:

Name Type Description Default
ctx Context

The click context.

required
formatter HelpFormatter

The formatter for the --help listing.

required

format_commands

format_commands(
    ctx: Context, formatter: HelpFormatter
) -> None

Format the subcommands, if any.

If called on a command object that isn’t derived from click.MultiCommand, then do nothing.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are marked with respective comments. They too are released under the same license above. The original code did not contain any “noqa” or “pragma” comments.

Parameters:

Name Type Description Default
ctx Context

The click context.

required
formatter HelpFormatter

The formatter for the --help listing.

required

format_epilog

format_epilog(
    ctx: Context, formatter: HelpFormatter
) -> None

Format the epilog, if any.

Based on code from click 8.1. Subject to the following license (3-clause BSD license):

Copyright 2024 Pallets

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

 1. Redistributions of source code must retain the above
    copyright notice, this list of conditions and the
    following disclaimer.

 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the
    following disclaimer in the documentation and/or other
    materials provided with the distribution.

 3. Neither the name of the copyright holder nor the names
    of its contributors may be used to endorse or promote
    products derived from this software without specific
    prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Modifications are marked with respective comments. They too are released under the same license above.

Parameters:

Name Type Description Default
ctx Context

The click context.

required
formatter HelpFormatter

The formatter for the --help listing.

required

LoggingOption

LoggingOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Logging options for the CLI.

ZshComplete

Bases: ZshComplete

Zsh completion class that supports colons.

click’s Zsh completion class (at least v8.1.7 and v8.1.8) uses completion helper functions (provided by Zsh) that parse each completion item into value-description pairs, separated by a colon. Correspondingly, any internal colons in the completion item’s value need to be escaped. click doesn’t do this. So, this subclass overrides those parts, and adds the missing escaping.

format_completion

format_completion(item: CompletionItem) -> str

Return a suitable serialization of the CompletionItem.

This serialization ensures colons in the item value are properly escaped.

PassphraseGenerationOption

PassphraseGenerationOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Passphrase generation options for the CLI.

ConfigurationOption

ConfigurationOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Configuration options for the CLI.

StorageManagementOption

StorageManagementOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Storage management options for the CLI.

CompatibilityOption

CompatibilityOption(*args: Any, **kwargs: Any)

Bases: OptionGroupOption

Compatibility and incompatibility options for the CLI.

adjust_logging_level

adjust_logging_level(
    ctx: Context,
    /,
    param: Parameter | None = None,
    value: int | None = None,
) -> None

Change the logs that are emitted to standard error.

This modifies the StandardCLILogging settings such that log records at the respective level are emitted, based on the param and the value.

color_forcing_callback

color_forcing_callback(
    ctx: Context, param: Parameter, value: Any
) -> None

Force the click context to honor NO_COLOR and FORCE_COLOR.

standard_logging_options

standard_logging_options(
    f: Callable[P, R]
) -> Callable[P, R]

Decorate the function with standard logging click options.

Adds the three click options -v/--verbose, -q/--quiet and --debug, which calls back into the adjust_logging_level function (with different argument values).

Parameters:

Name Type Description Default
f Callable[P, R]

A callable to decorate.

required

Returns:

Type Description
Callable[P, R]

The decorated callable.

derivepassphrase

derivepassphrase(ctx: Context) -> None

Derive a strong passphrase, deterministically, from a master secret.

This is a click-powered command-line interface function, and not intended for programmatic use. See the derivepassphrase(1) manpage for full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

derivepassphrase_export

derivepassphrase_export(ctx: Context) -> None

Export a foreign configuration to standard output.

This is a click-powered command-line interface function, and not intended for programmatic use. See the derivepassphrase-export(1) manpage for full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

derivepassphrase_export_vault

derivepassphrase_export_vault(
    ctx: Context,
    /,
    *,
    path: str | bytes | PathLike[str],
    formats: Sequence[
        Literal["v0.2", "v0.3", "storeroom"]
    ] = (),
    key: str | bytes | None = None,
) -> None

Export a vault-native configuration to standard output.

This is a click-powered command-line interface function, and not intended for programmatic use. See the derivepassphrase-export-vault(1) manpage for full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

derivepassphrase_vault

derivepassphrase_vault(
    ctx: Context,
    /,
    *,
    service: str | None = None,
    use_phrase: bool = False,
    use_key: bool = False,
    length: int | None = None,
    repeat: int | None = None,
    lower: int | None = None,
    upper: int | None = None,
    number: int | None = None,
    space: int | None = None,
    dash: int | None = None,
    symbol: int | None = None,
    edit_notes: bool = False,
    store_config_only: bool = False,
    delete_service_settings: bool = False,
    delete_globals: bool = False,
    clear_all_settings: bool = False,
    export_settings: (
        TextIO | Path | PathLike[str] | None
    ) = None,
    import_settings: (
        TextIO | Path | PathLike[str] | None
    ) = None,
    overwrite_config: bool = False,
    unset_settings: Sequence[str] = (),
    export_as: Literal["json", "sh"] = "json",
) -> None

Derive a passphrase using the vault(1) derivation scheme.

This is a click-powered command-line interface function, and not intended for programmatic use. See the derivepassphrase-vault(1) manpage for full documentation of the interface. (See also click.testing.CliRunner for controlled, programmatic invocation.)

Parameters:

Name Type Description Default
ctx Context

The click context.

required

Other Parameters:

Name Type Description
service str | None

A service name. Required, unless operating on global settings or importing/exporting settings.

use_phrase bool

Command-line argument -p/--phrase. If given, query the user for a passphrase instead of an SSH key.

use_key bool

Command-line argument -k/--key. If given, query the user for an SSH key instead of a passphrase.

length int | None

Command-line argument -l/--length. Override the default length of the generated passphrase.

repeat int | None

Command-line argument -r/--repeat. Override the default repetition limit if positive, or disable the repetition limit if 0.

lower int | None

Command-line argument --lower. Require a given amount of ASCII lowercase characters if positive, else forbid ASCII lowercase characters if 0.

upper int | None

Command-line argument --upper. Same as lower, but for ASCII uppercase characters.

number int | None

Command-line argument --number. Same as lower, but for ASCII digits.

space int | None

Command-line argument --space. Same as lower, but for the space character.

dash int | None

Command-line argument --dash. Same as lower, but for the hyphen-minus and underscore characters.

symbol int | None

Command-line argument --symbol. Same as lower, but for all other ASCII printable characters (except backquote).

edit_notes bool

Command-line argument -n/--notes. If given, spawn an editor to edit notes for service.

store_config_only bool

Command-line argument -c/--config. If given, saves the other given settings (--key, …, --symbol) to the configuration file, either specifically for service or as global settings.

delete_service_settings bool

Command-line argument -x/--delete. If given, removes the settings for service from the configuration file.

delete_globals bool

Command-line argument --delete-globals. If given, removes the global settings from the configuration file.

clear_all_settings bool

Command-line argument -X/--clear. If given, removes all settings from the configuration file.

export_settings TextIO | Path | PathLike[str] | None

Command-line argument -e/--export. If a file object, then it must be open for writing and accept str inputs. Otherwise, a filename to open for writing. Using - for standard output is supported.

import_settings TextIO | Path | PathLike[str] | None

Command-line argument -i/--import. If a file object, it must be open for reading and yield str values. Otherwise, a filename to open for reading. Using - for standard input is supported.

overwrite_config bool

Command-line arguments --overwrite-existing (True) and --merge-existing (False). Controls whether config saving and config importing overwrite existing configurations, or merge them section-wise instead.

unset_settings Sequence[str]

Command-line argument --unset. If given together with --config, unsets the specified settings (in addition to any other changes requested).

export_as Literal['json', 'sh']

Command-line argument --export-as. If given together with --export, selects the format to export the current configuration as: JSON (“json”, default) or POSIX sh (“sh”).