shellflow 0.1.1

A minimal shell script orchestrator with SSH support

ShellFlow

ShellFlow is a minimal shell script orchestrator for mixed local and remote execution. You write one shell script, mark execution boundaries with comments, and ShellFlow runs each block in order while resolving remote targets from your SSH configuration.

What It Does

• Split a shell script into @LOCAL and @REMOTE execution blocks.
• Run each block fail-fast, in order.
• Reuse the shared prelude before the first marker for every block.
• Pass the previous block output forward as SHELLFLOW_LAST_OUTPUT.
• Resolve remote targets from ~/.ssh/config or a custom SSH config path.

Quick Start

uv tool install shellflow

shellflow run playbooks/hello.sh

Installation

User installation (from PyPI)

uv tool install shellflow
shellflow --version

Install Skill

npx skills add longcipher/shellflow

This installs the agent skill from this repository for writing and reviewing Shellflow playbooks.

To upgrade to the latest version:

uv tool upgrade shellflow

Development checkout

git clone https://github.com/longcipher/shellflow.git
cd shellflow
uv sync --all-groups # uv sync --refresh --reinstall --no-cache

Install as a local tool (from source)

uv tool install --force .
shellflow --version

Install into the active environment (from source)

uv pip install -e .
shellflow --version

Script Format

Shellflow recognizes two markers:

• # @LOCAL
• # @REMOTE <ssh-host>

<ssh-host> must match a Host entry in your SSH config. Shellflow then connects using that SSH host definition, which means the actual machine can be resolved through the configured HostName, User, Port, and IdentityFile values.

Example:

#!/bin/bash
set -euo pipefail

# @LOCAL
echo "runs locally"

# @REMOTE sui
uname -a

# @LOCAL
echo "remote output: $SHELLFLOW_LAST_OUTPUT"

SSH Configuration

Example ~/.ssh/config entry:

Host sui
    HostName 192.168.1.100
    User deploy
    Port 22
    IdentityFile ~/.ssh/id_ed25519

With that config, this block is valid:

# @REMOTE sui
hostname

This is intentional:

• Shellflow accepts configured SSH host names, not arbitrary free-form targets.
• Unknown remote targets fail early with a clear error before spawning ssh.
• You can override the default config path with --ssh-config.

Execution Model

Each block runs in a fresh shell.

• Shell options from the prelude are copied into every block.
• Shell state like cd, shell variables, aliases, and export commands does not persist across blocks.
• Explicit context values are passed forward through environment variables.

Example:

# @LOCAL
echo "build-123"

# @LOCAL
echo "last output = $SHELLFLOW_LAST_OUTPUT"

Lines before the first marker are treated as a shared prelude and prepended to every executable block:

#!/bin/bash
set -euo pipefail

# @LOCAL
echo "prelude is active"

# @REMOTE sui
echo "prelude is also active here"

CLI

shellflow run <script>
shellflow run <script> --verbose
shellflow run <script> --ssh-config ./ssh_config
shellflow --version

Examples:

shellflow run playbooks/hello.sh
shellflow run playbooks/hello.sh -v
shellflow run playbooks/hello.sh --ssh-config ~/.ssh/config.work

Development

Useful commands:

just sync
just test
just bdd
just test-all
just typecheck
just build
just publish

Direct verification commands:

uv run pytest -q
uv run behave features
uv run ruff check .
uv run ty check src tests
uv build

Release Process

Shellflow supports both local publishing and GitHub Actions release publishing.

Local publish

just publish

uv publish uses standard uv authentication mechanisms such as UV_PUBLISH_TOKEN, or PyPI trusted publishing when supported by the environment.

GitHub Actions publish on tag push

The repository includes:

• .github/workflows/ci.yml for lint, type-check, test, and build verification.
• .github/workflows/release.yml for publishing to PyPI when a tag like v0.1.0 is pushed.

Recommended release flow:

git tag v0.1.0
git push origin v0.1.0

To use trusted publishing with PyPI:

1. Create a pypi environment in GitHub repository settings.
2. Add this repository as a trusted publisher in the PyPI project settings.
3. Push a v* tag.

The release workflow then runs verification, builds distributions with uv build, and uploads them with uv publish.

Project Layout

shellflow/
├── src/shellflow.py
├── tests/
├── features/
├── playbooks/
├── pyproject.toml
├── Justfile
└── README.md

License

Apache-2.0