CLI Reference

Commands

horsies worker

Start a task worker.

horsies worker <module> [OPTIONS]

Arguments:

Argument	Description
module	Python file or dotted module path containing Horsies instance

Options:

Option	Default	Description
--processes N	1	Number of worker processes
--loglevel LEVEL	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL
--max-claim-batch N	0	Max claims per queue per pass (0 auto-fills available capacity)
--max-claim-per-worker N	0	Max total claimed tasks (0=auto)
--max-tasks-per-child N	100	Recycle each worker process after it runs N tasks (N >= 2, per-child and staggered). 0 disables recycling. Forces the spawn start method. See worker concurrency.
--max-memory-per-child-mb N	(off)	Recycle a child once its own RSS reaches N MB (per-child, CPython-only, forces spawn). Disabled by default. The worker refuses to start if N is at or below the warmed child baseline. See worker concurrency.

Examples:

# Basic worker (module:app format, recommended)
horsies worker myapp.instance:app

# With 8 processes
horsies worker myapp.instance:app --processes=8

# Debug logging
horsies worker myapp.instance:app --loglevel=DEBUG

# Production settings
horsies worker myapp.instance:app --processes=8 --loglevel=WARNING

# Recycle each child after 500 tasks (raise from the default 100 for
# high-throughput or connection-constrained deployments)
horsies worker myapp.instance:app --processes=8 --max-tasks-per-child=500

# Disable recycling (children live for the worker's lifetime, uses fork)
horsies worker myapp.instance:app --processes=8 --max-tasks-per-child=0

# Using file path (also supported)
horsies worker app/configs/instance.py:app

horsies scheduler

Start the scheduler service.

horsies scheduler <module> [OPTIONS]

Arguments:

Argument	Description
module	Python file or dotted module path containing Horsies instance

Options:

Option	Default	Description
--loglevel LEVEL	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL

Examples:

# Basic scheduler
horsies scheduler myapp.instance:app

# Debug logging
horsies scheduler myapp.instance:app --loglevel=DEBUG

horsies check

Validate configuration, task registration, workflow structure, and optionally broker connectivity without starting services. Runs the same validation that workers and schedulers perform at startup.

For details on validation phases, @app.workflow_builder, the guarantee model, and CI usage, see Startup Validation.

horsies check <module> [OPTIONS]

Arguments:

Argument	Description
module	Dotted module path or file path containing Horsies instance

Options:

Option	Default	Description
--loglevel LEVEL	WARNING	DEBUG, INFO, WARNING, ERROR, CRITICAL
--live	false	Also test broker connectivity (SELECT 1)

Examples:

# Validate tasks, config, and workflows
horsies check myapp.instance:app

# Include broker connectivity check
horsies check myapp.instance:app --live

horsies get-docs

Fetch the full documentation locally as markdown files. Useful for AI agents (Claude Code, Cursor, Copilot, etc.) that need to read docs without web requests.

horsies get-docs [OPTIONS]

Options:

Option	Default	Description
--output DIR	.horsies-docs	Output directory

Examples:

# Fetch docs to default location
horsies get-docs

# Custom output directory
horsies get-docs --output my-docs/

# Update existing docs (idempotent — overwrites cleanly)
horsies get-docs

Uses git sparse checkout when git is available, falls back to tarball download otherwise. No app instance or database connection required.

Agent Skills (Repository)

If you are using an AI coding agent from a source checkout, Horsies also ships guidance-oriented skill files in:

horsies/.agents/skills/

Available files:

• SKILL.md — quick orientation and routing
• tasks.md — task authoring, send/retry, serialization, error handling
• workflows.md — DAG construction, handles, failure semantics, validation
• configs.md — configuration, scheduling, CLI checks, environment variables

These files are documentation-focused (no bundled scripts) and are intended for on-demand loading by agents that support markdown skill files.

Module Formats

The recommended format is a dotted module path with an explicit variable name:

horsies worker myapp.instance:app

Where app is the variable name of your Horsies instance in the module.

File paths are also supported:

horsies worker app/configs/instance.py:app

Do not mix dotted module notation with a .py extension (e.g., myapp.instance.py). The CLI will reject this with a helpful error.

If the module contains exactly one Horsies instance, the :name suffix can be omitted — the CLI will auto-discover it. If multiple instances exist, the suffix is required.

Module Discovery

instance.py

from horsies import Horsies, AppConfig, PostgresConfig

app = Horsies(AppConfig(...))  # Auto-discovered

@app.task("my_task")
def my_task():
    ...

app.discover_tasks(["myapp.tasks"])

Requirements:

• Module must have exactly one Horsies instance (or use :name suffix)
• Instance can have any variable name

Process Signals

Both commands handle graceful shutdown:

Signal	Behavior
SIGTERM	Graceful shutdown
SIGINT (Ctrl+C)	Graceful shutdown

Workers wait for running tasks to complete before exiting.

Exit Codes

Code	Meaning
0	Clean shutdown
1	Error (check logs)

Environment Variables

DATABASE_URL=postgresql+psycopg://... horsies worker myapp.instance:app

Use in config:

import os

config = AppConfig(
    broker=PostgresConfig(database_url=os.environ["DATABASE_URL"]),
)

Deployment

Systemd

[Unit]
Description=Horsies Worker
After=postgresql.service

[Service]
Type=simple
User=app
WorkingDirectory=/app
ExecStart=/usr/bin/horsies worker myapp.instance:app --processes=8
Restart=always

[Install]
WantedBy=multi-user.target

Docker

FROM python:3.13

WORKDIR /app
COPY . .
RUN pip install horsies

CMD ["horsies", "worker", "myapp.instance:app", "--processes=8"]

Procfile

worker: horsies worker myapp.instance:app --processes=8
scheduler: horsies scheduler myapp.instance:app