Argus CLI Documentation — Argus-Toolbelt 1.0 documentation

# Argus CLI Documentation

ArgusCLI is the part of the framework that end developers are going to interact with. It provides an instance of the Argus API and a framework for registering plugins and commands to the commandline tool.

## Settings file

Settings can either be in the same directory as the script running argus_cli with the name `settings.yaml`, or in a user’s home directory with the name `.argus_cli.yaml`, or specified via an environment variable called `ARGUS_CLI_SETTINGS`.

The application will first look for the environment variable, then the user specified settings, then the system specified settings.

All available options for the YAML-file are listed in the example below:

    api:
        # Defining the API URL. Do not add a trailing slash
        api_url: "<Base URL for the API>"

        # When using API keys
        api_key: "<Your API key>"

        # When using username based auth
        username = <username>
        password = <password>
        mode = <auth mode (ldap, token, etc)>

    cli:
        plugins:
            - <Plugin directory 1>
            - <Plugin directory 2>
            - <Plugin directory ...>

    # For more logging settings, see the logging howto in the python docs
    logging:
        version: 1
        disable_existing_loggers: false
        formatters:
            simple:
                format: "%(asctime)s %(levelname)s -- %(message)s"
            verbose:
                format: "%(asctime)s %(levelname)s -- %(name)s %(filename)s:%(lineno)s -- %(message)s"
        handlers:
            console:
                level: DEBUG
                class: logging.StreamHandler
                formatter: verbose
        loggers:
            argus_cli:
                level: DEBUG
                handlers: [console]
            argus_api:
                level: INFO

## Subpackages

- argus_cli.helpers package
  - Submodules
  - argus_cli.helpers.collections module
  - argus_cli.helpers.formatting module
  - argus_cli.helpers.log module
  - Module contents

## Submodules

## argus_cli.arguments module

class `argus_cli.arguments.` `PluginParserContainer`(main_parser)

  Bases: `object`

  A container that handles plugin parsers

  Each node in the dict has three objects.
    _subparsers: The _SubParserAction object (that you add parsers to) _parser: The actual parser. This is just used for testing Everything else: Commands and sub-plugins
  `add_command`(plugin: tuple, command_name: str) → argparse.ArgumentParser

    Adds a command to a plugin parser

  `add_parser`(plugin: tuple) → None

    Adds a parser to the container

  `get_command`(plugin: tuple, command_name: str)

    Gets a command from a plugin

  `get_plugin`(plugin: tuple)

    Gets a plugin parser

`argus_cli.arguments.` `get_command_arguments`() → dict

  Gets the command arguments.

  See get_plugin_arguments() for why we do it like this.

  Returns: | Command arguments

`argus_cli.arguments.` `get_plugin_arguments`() → tuple

  Only parse the plugin arguments.

  Plugin arguments are the <plugin> and <command> part of the CLI. If we do not do it like this help-messages for commands would be catched in here, and thus we wouldn’t get a proper help message for commands.

  Returns: | Plugin and command name

`argus_cli.arguments.` `register_command`(plugin_sequence: tuple, command_name: str) → None

  Registers a command towards a plugin.

  Parameters: | plugin_sequence (`tuple`) – The name of the plugin that the function belongs to command_name (`str`) – The name of the function

`argus_cli.arguments.` `register_command_metadata`(plugin_sequence: tuple, command_name: str, function: <built-in function callable>) → None

  Registers the function metadata to a parser

  Registering the metadata is done at a later point to not do unnecessary operations with _parse_function(). A single call to _parse_function() takes quite some time, so it’s better to do it JIT.

  Parameters: | plugin_sequence (`tuple`) – The name of the plugin command_name (`str`) – The name of the command function – The function to parse metadata from

`argus_cli.arguments.` `register_plugin`(plugin_sequence: tuple) → None

  Creates a parser for a plugin

  Parameters: | plugin_sequence (`tuple`) – The plugin sequence
  Raises: | KeyError – If the plugin already exists

## argus_cli.cli module

`argus_cli.cli.` `main`()

  Used to launch the application

`argus_cli.cli.` `run`()

  Parses command and runs the application

`argus_cli.cli.` `setup`()

  Does setup of the API and loads plugins

## argus_cli.plugin module

`argus_cli.plugin.` `api` = None

  The API that plugins will interact with

`argus_cli.plugin.` `get_plugin_modules`(locations: list) → list

  Loads plugins from default plugin location and user defined plugin location, and attempts to load them as python modules.

  Directories can be loaded, provided they are python packages, i.e containing an __init__.py file. If a plugin is defined as a Python package with an __init__.py file, this file must export all functions decorated with @register_command, since these will be registered on import, and only the __init__.py will be initially imported.

  NOTE: Renames plugins to common unix command naming scheme

  Parameters: | locations (list) – Folder with plunspgins
  Return type: | list
  Returns: | A list of python files with paths

`argus_cli.plugin.` `load_plugin_module`(plugin: dict) → bool

  Loads a plugin

  Parameters: | plugin (dict) – A dict with the module name and info
  Returns: | True if module was successfully loaded
  Return type: | bool

`argus_cli.plugin.` `register_command`(alias: str = None, extending: typing.Union[tuple, str] = None) → <built-in function callable>

  Decorator used to register commands to a plugin

  Parameters: | alias (`str`) – If the user wants a custom name on the plugin extending – A existing plugin to extend

`argus_cli.plugin.` `register_command_metadata`(plugin_name: tuple, command_name: str) → None

  Registers the commands metadata

  Wraps the function with the same name in arguments. This is because this module contains the actual function to parse.

  Parameters: | plugin_name (`tuple`) – The name of the plugin command_name (`str`) – The name of the function

`argus_cli.plugin.` `run_command`(plugin_name: tuple, command: str, arguments: dict = None) → None

  Runs the specified command

  Parameters: | plugin_name (`tuple`) – The plugin(module) to source the command from command (`str`) – The command to run arguments (`dict`) – Arguments to pass to the function
  Returns: | Anything the command returns

## argus_cli.settings module

Load default YAML settings file, then look for user defined settings and create a ChainMap.

## Module contents