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

Submodules

argus_cli.arguments module

class argus_cli.arguments.PluginParserContainer(main_parser)[source]

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[source]

Adds a command to a plugin parser

add_parser(plugin: tuple) → None[source]

Adds a parser to the container

get_command(plugin: tuple, command_name: str)[source]

Gets a command from a plugin

argus_cli.arguments.get_command_arguments() → dict[source]

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[source]

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[source]

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[source]

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[source]

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.get_api_instance(arguments)[source]

Creates a instance of the API

Parameters:arguments – Arguments
Returns:ArgusAPI instance
argus_cli.cli.main()[source]

Used to launch the application

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[source]

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[source]

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>[source]

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[source]

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[source]

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