From e8bd5ad24b23dcf854cebbfc963834738564b8ee Mon Sep 17 00:00:00 2001 From: a-kenji Date: Mon, 27 May 2024 11:48:08 +0200 Subject: [PATCH] clan: add examples and description to most help Add examples and description to most toplevel help outputs. --- pkgs/clan-cli/clan_cli/__init__.py | 135 ++++++++++++++++++++++- pkgs/clan-cli/clan_cli/facts/__init__.py | 37 ++++++- 2 files changed, 166 insertions(+), 6 deletions(-) diff --git a/pkgs/clan-cli/clan_cli/__init__.py b/pkgs/clan-cli/clan_cli/__init__.py index 15d0c661..36ca8f03 100644 --- a/pkgs/clan-cli/clan_cli/__init__.py +++ b/pkgs/clan-cli/clan_cli/__init__.py @@ -53,6 +53,17 @@ class AppendOptionAction(argparse.Action): def create_parser(prog: str | None = None) -> argparse.ArgumentParser: parser = argparse.ArgumentParser(prog=prog, description="The clan cli tool.") + parser = argparse.ArgumentParser( + prog=prog, + description="cLAN tool", + epilog=( + """ +Online reference for the clan cli tool: https://docs.clan.lol/reference/cli/ +For more detailed information, visit: https://docs.clan.lol + """ + ), + formatter_class=argparse.RawTextHelpFormatter, + ) parser.add_argument( "--debug", @@ -90,28 +101,142 @@ def create_parser(prog: str | None = None) -> argparse.ArgumentParser: "backups", help="manage backups of clan machines", description="manage backups of clan machines", + epilog=( + """ +This subcommand provides an interface to backups that clan machines expose. + +Examples: + + $ clan backups list [MACHINE] + List backups for the machine [MACHINE] + + $ clan backups create [MACHINE] + Create a backup for the machine [MACHINE]. + + $ clan backups restore [MACHINE] [PROVIDER] [NAME] + The backup to restore for the machine [MACHINE] with the configured [PROVIDER] + with the name [NAME]. + +For more detailed information, visit: https://docs.clan.lol/getting-started/backups/ + """ + ), + formatter_class=argparse.RawTextHelpFormatter, ) backups.register_parser(parser_backups) parser_flake = subparsers.add_parser( - "flakes", help="create a clan flake inside the current directory" + "flakes", + help="create a clan flake inside the current directory", + epilog=( + """ +Examples: + $ clan flakes create [DIR] + Will create a new clan flake in the specified directory and create it if it + doesn't exist yet. The flake will be created from a default template. + +For more detailed information, visit: https://docs.clan.lol/getting-started + """ + ), + formatter_class=argparse.RawTextHelpFormatter, ) flakes.register_parser(parser_flake) - parser_config = subparsers.add_parser("config", help="set nixos configuration") + parser_config = subparsers.add_parser( + "config", + help="set nixos configuration", + epilog=( + """ + """ + ), + formatter_class=argparse.RawTextHelpFormatter, + ) config.register_parser(parser_config) parser_ssh = subparsers.add_parser("ssh", help="ssh to a remote machine") ssh_cli.register_parser(parser_ssh) - parser_secrets = subparsers.add_parser("secrets", help="manage secrets") + parser_secrets = subparsers.add_parser( + "secrets", + help="manage secrets", + epilog=( + """ +This subcommand provides an interface to secret facts. + +Examples: + + $ clan secrets list [regex] + Will list secrets for all managed machines. + It accepts an optional regex, allowing easy filtering of returned secrets. + + $ clan secrets get [SECRET] + Will display the content of the specified secret. + +For more detailed information, visit: https://docs.clan.lol/getting-started/secrets/ + """ + ), + formatter_class=argparse.RawTextHelpFormatter, + ) secrets.register_parser(parser_secrets) - parser_facts = subparsers.add_parser("facts", help="manage facts") + parser_facts = subparsers.add_parser( + "facts", + help="manage facts", + epilog=( + """ + +This subcommand provides an interface to facts of clan machines. +Facts are artifacts that a service can generate. +There are public and secret facts. +Public facts can be referenced by other machines directly. +Public facts can include: ip addresses, public keys. +Secret facts can include: passwords, private keys. + +A service is an included clan-module that implements facts generation functionality. +For example the zerotier module will generate private and public facts. +In this case the public fact will be the resulting zerotier-ip of the machine. +The secret fact will be the zerotier-identity-secret, which is used by zerotier +to prove the machine has control of the zerotier-ip. + +Examples: + + $ clan facts generate + Will generate facts for all machines. + + $ clan facts generate --service [SERVICE] --regenerate + Will regenerate facts, if they are already generated for a specific service. + This is especially useful for resetting certain passwords while leaving the rest + of the facts for a machine in place. + +For more detailed information, visit: https://docs.clan.lol/getting-started/secrets/ + """ + ), + formatter_class=argparse.RawTextHelpFormatter, + ) facts.register_parser(parser_facts) parser_machine = subparsers.add_parser( - "machines", help="manage machines and their configuration" + "machines", + help="manage machines and their configuration", + epilog=( + """ +This subcommand provides an interface to machines managed by clan. + +Examples: + + $ clan machines list + List all the machines managed by clan. + + $ clan machines update [MACHINES] + Will update the specified machine [MACHINE], if [MACHINE] is omitted, the command + will attempt to update every configured machine. + + $ clan machines install [MACHINES] [TARGET_HOST] + Will install the specified machine [MACHINE], to the specified [TARGET_HOST]. + +For more detailed information, visit: https://docs.clan.lol/getting-started/deploy + """ + ), + formatter_class=argparse.RawTextHelpFormatter, ) machines.register_parser(parser_machine) diff --git a/pkgs/clan-cli/clan_cli/facts/__init__.py b/pkgs/clan-cli/clan_cli/facts/__init__.py index 49abd97f..7aee8dee 100644 --- a/pkgs/clan-cli/clan_cli/facts/__init__.py +++ b/pkgs/clan-cli/clan_cli/facts/__init__.py @@ -23,7 +23,42 @@ def register_parser(parser: argparse.ArgumentParser) -> None: register_list_parser(list_parser) parser_generate = subparser.add_parser( - "generate", help="generate secrets for machines if they don't exist yet" + "generate", + help="generate public and secret facts for machines", + epilog=( + """ +This subcommand allows control of the generation of facts. +Often this function will be invoked automatically on deploying machines, +but there are situations the user may want to have more granular control, +especially for the regeneration of certain services. + +A service is an included clan-module that implements facts generation functionality. +For example the zerotier module will generate private and public facts. +In this case the public fact will be the resulting zerotier-ip of the machine. +The secret fact will be the zerotier-identity-secret, which is used by zerotier +to prove the machine has control of the zerotier-ip. + + +Examples: + + $ clan facts generate + Will generate facts for all machines. + + $ clan facts generate [MACHINE] + Will generate facts for the specified machine. + + $ clan facts generate [MACHINE] --service [SERVICE] + Will generate facts for the specified machine for the specified service. + + $ clan facts generate --service [SERVICE] --regenerate + Will regenerate facts, if they are already generated for a specific service. + This is especially useful for resetting certain passwords while leaving the rest + of the facts for a machine in place. + +For more detailed information, visit: https://docs.clan.lol/getting-started/secrets/ + """ + ), + formatter_class=argparse.RawTextHelpFormatter, ) register_generate_parser(parser_generate)