Shellnium

March 28, 2026 · View on GitHub

Shellnium

Shellnium is the Selenium WebDriver for Bash. You can automate browser actions simply from your terminal. All you need is Bash or Zsh.

#!/usr/bin/env bash
source ./selenium.sh

main() {
    # Open the URL
    navigate_to 'https://google.com'

    # Get the search box
    local searchBox=$(find_element 'name' 'q')

    # Send keys and press Enter
    send_keys $searchBox "panda${KEY_ENTER}"
}

main

Documentation

https://shellnium-site.vercel.app

If you learn by watching videos, check out this screencast by @gotbletu to explore shellnium features.

Installation

git clone https://github.com/Rasukarusan/shellnium.git
cd shellnium

Requirements

bash (4.0+) or zsh
curl
jq
unzip
Google Chrome / Chromium

ChromeDriver is automatically downloaded and managed by Shellnium. You don't need to install it manually.

Install dependencies

macOS:

brew install jq

Ubuntu / Debian:

sudo apt-get install -y jq unzip

Arch Linux:

sudo pacman -S jq unzip

Quick Start

# Just run it — ChromeDriver is set up automatically!
bash demo.sh

Development

For local development and agent-driven verification, use the standardized make targets:

# Run the standard Docker-first verification pipeline
make ci

make ci runs local syntax checks, then runs ShellCheck and Bats inside Docker. You do not need local shellcheck or bats installations.

If you want to run demos locally, install the optional runtime dependencies:

make bootstrap

Available targets:

make syntax - bash syntax checks for tracked scripts
make lint - ShellCheck on library, example, and helper scripts
make test - Bats unit and syntax tests
make smoke - headless browser smoke example
make docker-test - lint and test in Docker
make docker-smoke - smoke test in Docker
make ci-local - local lint and test for users who already have the tools installed

If you are using an AI coding agent, start with the instructions in AGENTS.md.

Docker

Run Shellnium instantly without installing Chrome or ChromeDriver locally:

# Run the demo
docker run --rm --shm-size=2g ghcr.io/rasukarusan/shellnium demo.sh

# Run your own script
docker run --rm --shm-size=2g -v ./my_script.sh:/app/my_script.sh ghcr.io/rasukarusan/shellnium my_script.sh

# Using docker compose
docker compose run --rm shellnium

Or build locally:

docker build -t shellnium .
docker run --rm --shm-size=2g shellnium demo.sh

You can also run ShellCheck and unit tests inside the container:

# Run the container-based verification flow
make docker-test

You can pass Chrome options like --headless:

bash demo.sh --headless --lang=es

ChromeDriver is automatically downloaded to ~/.cache/shellnium/ and started on port 9515. When your script finishes, ChromeDriver is stopped automatically.

Configuration

Environment Variable	Default	Description
`SHELLNIUM_HEADLESS`	(unset)	Set to `true` or `1` to enable headless mode (no visible browser window)
`SHELLNIUM_DRIVER_URL`	`http://localhost:9515`	Custom ChromeDriver URL (disables auto-setup)
`SHELLNIUM_PORT`	`9515`	Port for auto-started ChromeDriver
`SHELLNIUM_CACHE_DIR`	`~/.cache/shellnium`	Cache directory for downloaded ChromeDriver
`SHELLNIUM_DEBUG`	(unset)	Set to `true` to enable verbose debug logging

Debug Mode

Enable debug mode to see all HTTP requests and responses sent to ChromeDriver, as well as any WebDriver error messages:

SHELLNIUM_DEBUG=true bash demo.sh

Debug output is written to stderr so it won't interfere with your script's normal output. WebDriver errors (e.g., element not found, stale element reference) are always surfaced to stderr regardless of debug mode.

Headless Mode

Headless mode runs Chrome without a visible browser window, which is essential for CI/CD pipelines and server-side automation.

# Enable headless mode via environment variable
SHELLNIUM_HEADLESS=true bash demo.sh

# Or export it for the entire session
export SHELLNIUM_HEADLESS=true
bash demo.sh

You can also pass --headless directly as a Chrome option (e.g., bash demo.sh --headless), but the environment variable is recommended for CI/CD environments.

GitHub Actions Example

name: Browser Automation
on: [push]

jobs:
  automate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: sudo apt-get install -y jq unzip google-chrome-stable
      - name: Run automation script
        env:
          SHELLNIUM_HEADLESS: true
        run: bash demo.sh

Examples

The examples/ directory contains practical scripts demonstrating common use cases:

Script	Description
scraping.sh	Extract data from web pages (scrapes Hacker News top stories)
form_fill.sh	Auto-fill and submit HTML forms
login.sh	Automate login flow with cookie saving
screenshot_batch.sh	Take screenshots of multiple URLs in batch
ci_smoke_test.sh	CI/CD smoke test suite with pass/fail reporting
multi_tab.sh	Open, switch between, and manage multiple browser tabs

Run any example:

# With browser window
bash examples/scraping.sh

# Headless mode
bash examples/scraping.sh --headless

Methods

Shellnium provides the following methods. See document or core.sh for details.

Session

is_ready
new_session
delete_session
get_all_cookies / get_named_cookie / add_cookie / delete_cookie / delete_all_cookies

Navigate

navigate_to / get_current_url / get_title
back / forward / refresh

Timeouts

get_timeouts / set_timeouts
set_timeout_script / set_timeout_pageLoad / set_timeout_implicit

Element Retrieval

find_element / find_elements
find_element_from_element / find_elements_from_element
get_active_element

Element State

get_attribute / get_property / get_css_value
get_text / get_tag_name / get_rect
is_element_enabled / is_element_displayed

Element Interaction

send_keys / click / element_clear

Key Constants

Use these constants with send_keys to send special keys:

send_keys $element "hello${KEY_ENTER}"    # Type "hello" then press Enter
send_keys $element "${KEY_TAB}"           # Press Tab

Constant	Key
`KEY_BACKSPACE`	Backspace
`KEY_TAB`	Tab
`KEY_RETURN`	Return
`KEY_ENTER`	Enter
`KEY_SHIFT`	Shift
`KEY_CONTROL`	Control
`KEY_ALT`	Alt
`KEY_ESCAPE`	Escape
`KEY_SPACE`	Space
`KEY_ARROW_LEFT` / `KEY_ARROW_UP` / `KEY_ARROW_RIGHT` / `KEY_ARROW_DOWN`	Arrow keys

Document

get_source / exec_script
screenshot / element_screenshot

Context

get_window_handle / get_window_handles
new_window / delete_window / switch_to_window
switch_to_frame / switch_to_parent_frame
get_window_rect / set_window_rect
maximize_window / minimize_window / fullscreen_window

Wait / Retry

wait_for_element — Wait until an element is found (configurable timeout and polling interval)
wait_for_clickable — Wait until an element is displayed and enabled
wait_for_text — Wait until specific text appears in the page source
wait_for_url — Wait until the current URL matches a pattern
retry — Retry any command up to N times with interval

Alerts

get_alert_text / send_alert_text
accept_alert / dismiss_alert

Actions

Perform low-level mouse and keyboard actions using the W3C WebDriver Actions API.

perform_actions / release_actions — low-level actions API
Mouse: mouse_move_to / double_click / right_click / hover / drag_and_drop
Keyboard: key_press / key_down / key_up / send_key_combo

Key constants are available for keyboard actions (e.g., $KEY_CONTROL, $KEY_SHIFT, $KEY_ENTER, $KEY_TAB, $KEY_ESCAPE, $KEY_ARROW_DOWN, etc.).

bash demo2.sh

demo2.sh requires iTerm2 and macOS.

This script is headless and displays ChromeDriver's behavior as iTerm's background with AppleScript.

Reference

W3C WebDriver Specification

LICENSE

MIT

Shellnium

Shellnium

Documentation

Installation

Requirements

Install dependencies

Quick Start

Development

Docker

Configuration

Debug Mode

Headless Mode

GitHub Actions Example

Examples

Methods

Session

Navigate

Timeouts

Element Retrieval

Element State

Element Interaction

Key Constants

Document

Context

Wait / Retry

Alerts

Actions

Contributing

Article

Example

Reference

LICENSE