Installation Python 3.12+ Repo-native CLI

Install Ralph Workflow and get to a real run fast.

The shortest supported path is: install the CLI, initialize it inside a git repository, verify the environment, then start one unattended run you can inspect in your normal review flow.

See install commands Full getting started guide

pipx install ralph-workflow Reuses your existing agent CLIs View source

Fastest supported path

Install, verify, and start the first run.

pipx install ralph-workflow
cd /path/to/your/project
ralph --init
ralph --diagnose
$EDITOR PROMPT.md
ralph

This is the same install-to-first-run path documented in the product docs, compressed onto one page.

Before you install

Bring the basics you already use for real work.

Ralph Workflow runs inside a git repository and reuses the AI agent CLIs you already have on your machine. The docs call out three prerequisites before the first run.

Requirement 1

Python 3.12 or newer

Check it with python --version before you start the install.

Requirement 2

A git repository

Most teams try Ralph Workflow in an existing repository they already care about, but a scratch repo works too.

Requirement 3

One supported AI agent on your PATH

Usually that means claude, Codex CLI, or opencode. Ralph Workflow reuses those existing CLIs instead of asking you to re-enter credentials into a hosted product.

Install options

Choose the install path that matches how you work.

The docs and README support three clean paths: pipx, pip, or installing from source.

Recommended for first install

pipx

pipx install ralph-workflow
ralph --version

If you do not have pipx yet, the getting-started guide shows the bootstrap commands too.

Simple package install

pip

pip install ralph-workflow
ralph --help

This matches the public README and is fine if that is already how you manage Python CLI tools.

For contributors or source builds

From source

git clone https://codeberg.org/RalphWorkflow/Ralph-Workflow.git
cd Ralph-Workflow/ralph-workflow
pip install -e .
ralph --version

Use this path when you want the source tree locally or you plan to work on Ralph Workflow itself.

After install

From install to first unattended run in five commands.

Once the CLI is on your PATH, the onboarding flow is intentionally short: initialize the repo, verify the environment, write the task spec, then let the run start.

cd /path/to/your/project
ralph --init
ralph --diagnose
$EDITOR PROMPT.md
ralph

What each command does

ralph --init creates PROMPT.md and the local .agent/ support files.
ralph --diagnose catches missing agents or broken config before you burn time on a real run.
PROMPT.md becomes the task contract the workflow keeps returning to.
ralph starts the unattended run.

Next move

Use a real but low-stakes repo first, keep the task small and concrete, then decide whether the handoff quality is good enough for higher-stakes work.