CLI · smoke tests · automation

Smokey keeps your smoke tests honest.

A tiny Bash runner that executes numbered .d suites, provides explicit env sharing, and contains Bash edge cases such as exit traps. No YAML, no daemons — just boring, predictable smoke tests that work on any CI runner, developer laptop, container, Raspberry Pi, or VM.

View on GitHub Read the guide Downloads

$ smokey
>> running tests.d/000-setup/run.sh
>> running tests.d/010-api-health.sh
!! api-health failed (timeout)
--- smokey summary ---
tests: 1/2 · failures:
  failed        tests.d/010-api-health.sh

Why Smokey

Modern smoke automation with proven Bash instead of YAML gymnastics.

Deterministic order

Smokey executes files alphabetically (000, 010, …, 999). You always know what ran before what — no hidden scheduler.

Liberty-first structure

Smokey imposes almost no repo structure beyond numbered entries, so you can keep your project layout instead of bending it around an opinionated framework.

Setup & teardown built in

You write the setup and teardown scripts yourself; Smokey makes sure they run automatically at the right points before and after the suite.

Isolated

Every invocation gets a random SMOKEY_STATE_DIR, and cross-step env vars only persist when you save them explicitly through built-in helper commands.

Portable shell

All you need is Bash. Smokey wraps that power in guard rails against unwanted exits, leaky traps, env-var drift, and shared-state surprises.

Workflow

Set up a `tests.d` directory

Lay out the suite

Create a tests.d/ directory in your project root and fill it with numbered scripts.

tests.d/
  000-setup.sh
  010-check-binaries.sh
  020-check-network.sh
  999-cleanup.sh

Use 000-* for setup, regular numbered entries for the main checks, and 999-* for cleanup.

Run locally

$ cd myproject
$ smokey
>> running tests.d/000-setup/run.sh
>> running tests.d/010-api-health.sh
!! api-health failed (timeout)
--- smokey summary ---
tests: 1/2 · failures:
  failed        tests.d/010-api-health.sh

Change into your project directory and run smokey.

Use smokey --tests-dir tests.d when the suite lives somewhere else. Pass --fail-fast, --preserve, or --reuse-state when debugging flakes.

Ship confidence

Use Smokey’s exit code as a deployment guardrail. The summary prints only non-OK steps so logs stay readable for humans.

Feature deep dive

Hands-free environment cleanup — Smokey runs teardown both before and after your suite so stale clusters never break new runs.

Subshell isolation — nested suites inherit exports but never mutate the parent shell’s PATH, options, or variables.

Clear APIs — helper env vars (`SMOKEY_SKIP_CODE`, `SMOKEY_STATE_DIR`, etc.) give each script context without global config.

Observability baked in — the summary only lists failures and skip reasons, making CI logs skimmable.

Bring-your-own tools — run `go test`, `docker compose`, Ansible, curl… anything you can script is fair game.

Works with GitHub Actions, GitLab CI, Jenkins, or cron jobs with zero additional dependencies.

Friendly install story — grab the one-liner installer or a signed Debian package from the GitHub Releases tab.

CLI snippet

Install once, run everywhere.

# install for current user (latest stable tag)
curl -fsSL https://raw.githubusercontent.com/micwin/smokey/v0.2.0/install.sh | bash

# or install the Debian package from Releases
curl -LO https://github.com/micwin/smokey/releases/download/v0.2.0/smokey_0.2.0_amd64.deb
sudo dpkg -i smokey_0.2.0_amd64.deb

# run directly from a cloned repo
git clone git@github.com:micwin/smokey.git
cd smokey && smokey

# override tests directory only when needed
smokey --tests-dir ./infra/tests.d --fail-fast

Download .deb Download script All downloads

Trusted in ops & testing

Used to babysit container clusters, verify infra drift, and guard mono repos.

Platform teams Release managers QA engineers Site reliability folks Security auditors

Ready to automate your smoke checks?

Drop Smokey into your repo, describe the most important workflows, and keep shipping without guesswork.

Get Smokey Browse sample tests All downloads