README.md

Shell driver

jumpstarter-driver-shell provides functionality for shell command execution.

Installation

:substitutions:
$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-shell

Configuration

The shell driver supports two configuration formats for methods:

Format 1: Simple String e.g. for self-descriptive short commands

export:
  shell:
    type: jumpstarter_driver_shell.driver.Shell
    config:
      methods:
        ls: "ls"
        echo_hello: "echo 'Hello World'"

Format 2: Unified Format with Descriptions

export:
  shell:
    type: jumpstarter_driver_shell.driver.Shell
    config:
      methods:
        ls:
          command: "ls -la"
          description: "List directory contents with details"
        deploy:
          command: "ansible-playbook deploy.yml"
          description: "Deploy application using Ansible"
        # Multi-line commands work too
        setup:
          command: |
            echo 'Setting up environment'
            export PATH=$PATH:/usr/local/bin
            ./setup.sh
          description: "Set up the development environment"
        # Description-only (uses default "echo Hello" command)
        placeholder:
          description: "Placeholder method for testing"
        # Custom timeout for long-running operations
        long_backup:
          command: "tar -czf backup.tar.gz /data && rsync backup.tar.gz remote:/backups/"
          description: "Create and sync backup (may take a while)"
          timeout: 1800  # 30 minutes instead of default 5 minutes
        # You can mix both formats
        simple_echo: "echo 'simple'"
      # optional parameters
      cwd: "/tmp"
      log_level: "INFO"
      shell:
        - "/bin/bash"
        - "-c"

Configuration Parameters

Parameter	Description	Type	Required	Default
methods	Dictionary of methods. Values can be: - String: just the command - Dict: {command: "...", description: "...", timeout: ...}	dict[str, str | dict]	Yes	-
cwd	Working directory for shell commands	str	No	None
log_level	Logging level	str	No	"INFO"
shell	Shell command to execute scripts	list[str]	No	["bash", "-c"]
timeout	Command timeout in seconds	int	No	300

Method Configuration Options:

For the dict format, each method supports:

• command: The shell command to execute (optional, defaults to "echo Hello")
• description: CLI help text (optional, defaults to "Execute the {method_name} shell method")
• timeout: Command-specific timeout in seconds (optional, defaults to global timeout value)

Note: You can mix both formats in the same configuration - use string format for simple commands and dict format when you want custom descriptions or timeouts.

API Reference

Assuming the exporter driver is configured as in the example above, the client methods will be generated dynamically, and they will be available as follows:

.. autoclass:: jumpstarter_driver_shell.client.ShellClient
    :members:

.. function:: ls()
   :noindex:

   :returns: A tuple(stdout, stderr, return_code)

.. function:: method2()
    :noindex:

    :returns: A tuple(stdout, stderr, return_code)

.. function:: method3(arg1, arg2)
    :noindex:

    :returns: A tuple(stdout, stderr, return_code)

.. function:: env_var(arg1, arg2, ENV_VAR="value")
    :noindex:

    :returns: A tuple(stdout, stderr, return_code)

CLI Usage

The shell driver also provides a CLI when using jmp shell. All configured methods become available as CLI commands, except for methods starting with _ which are considered private and hidden from the end user.

CLI Help Output

With unified format (custom descriptions):

$ jmp shell --exporter shell-exporter
$ j shell
Usage: j shell [OPTIONS] COMMAND [ARGS]...

  Shell command executor

Commands:
  deploy  Deploy application using Ansible
  ls      List directory contents with details
  setup   Set up the development environment

With simple string format (default descriptions):

$ j shell
Usage: j shell [OPTIONS] COMMAND [ARGS]...

  Shell command executor

Commands:
  deploy  Execute the deploy shell method
  ls      Execute the ls shell method
  setup   Execute the setup shell method

Mixed format example:

methods:
  deploy:
    command: "ansible-playbook deploy.yml"
    description: "Deploy using Ansible"
  restart: "systemctl restart myapp"  # Simple format

Results in:

Commands:
  deploy   Deploy using Ansible
  restart  Execute the restart shell method

CLI Command Usage

Each configured method becomes a CLI command with the following options:

$ j shell ls --help
Usage: j shell ls [OPTIONS] [ARGS]...

  Execute the ls shell method

Options:
  -e, --env TEXT  Environment variables in KEY=VALUE format
  --help          Show this message and exit.

Examples

# Execute simple commands
$ j shell ls
file1.txt  file2.txt  directory/

# Pass arguments to shell methods
$ j shell method3 "first arg" "second arg"
Hello World first arg
Hello World second arg

# Set environment variables
$ j shell env_var arg1 arg2 --env ENV_VAR=myvalue
arg1,arg2,myvalue