Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

Shell driver¶

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

Installation¶

$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple 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:

class jumpstarter_driver_shell.client.ShellClient(*, uuid: uuid.UUID = <factory>, labels: dict[str, str] = <factory>, stub: Any, log_level: str = 'INFO', children: 'dict[str, DriverClient]' = <factory>, portal: 'BlockingPortal', stack: 'ExitStack', description: 'str | None' = None, methods_description: 'dict[str, str]' = <factory>)¶

cli()¶: Create CLI interface for dynamically configured shell methods

ls()

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

method2()

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

method3(arg1, arg2)

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

env_var(arg1, arg2, ENV_VAR='value')

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