Skip to main content
The Hyrex CLI provides commands for initializing projects, running workers, and managing your Hyrex deployment.

​
Installation

The CLI is included when you install the Hyrex Python SDK: 
pip install hyrex

​
Commands

​
hyrex init

Initialize a new Hyrex project with interactive setup. 
hyrex init
This command guides you through setting up a new Hyrex project, creating necessary configuration files and project structure.

​
hyrex init-db

Initialize the Hyrex database tables in your PostgreSQL database. 
hyrex init-db [OPTIONS]
Note: This command is run automatically when you start a worker, so you typically don’t need to run it manually. It’s only needed if you want to initialize the database tables before running any workers. Options:
  • --database-string TEXT - PostgreSQL connection string. If not provided, uses the HYREX_DATABASE_URL environment variable.
Example: 
# Using command-line option
hyrex init-db --database-string "postgresql://user:pass@localhost/mydb"

# Using environment variable
export HYREX_DATABASE_URL="postgresql://user:pass@localhost/mydb"
hyrex init-db

​
hyrex run-worker

Run a Hyrex worker to process tasks from queues. 
hyrex run-worker APP_MODULE_PATH [OPTIONS]
Arguments:
  • APP_MODULE_PATH - Python module path to your Hyrex app (e.g., hyrex_app:app)
Options:
  • --queue-pattern TEXT - Queue pattern for task filtering (default: *, accepts wildcards)
  • --num-processes INTEGER - Number of parallel executor processes (default: 8)
  • --log-level TEXT - Logging level (default: INFO, options: DEBUG, INFO, WARNING, ERROR)
Examples: 
# Basic worker
hyrex run-worker hyrex_app:app

# Worker for specific queues
hyrex run-worker hyrex_app:app --queue-pattern "email-*"

# Worker with custom settings
hyrex run-worker hyrex_app:app --num-processes 16 --log-level DEBUG

​
hyrex studio

Launch Hyrex Studio, a web-based UI for monitoring and managing your Hyrex deployment. 
hyrex studio [OPTIONS]
Options:
  • --port INTEGER - Port to run the studio server (default: 1337)
  • --verbose - Enable verbose logging
Examples: 
# Start studio on default port
hyrex studio

# Start studio on custom port
hyrex studio --port 8080

# Start studio with verbose logging
hyrex studio --verbose

​
Environment Variables

The Hyrex CLI respects the following environment variables:

​
For Hyrex FOSS (Self-hosted)

  • HYREX_DATABASE_URL - PostgreSQL connection string for your Hyrex database

​
For Hyrex Cloud (Managed)

  • HYREX_API_KEY - API key for Hyrex Cloud service

​
Configuration Priority

The CLI follows this priority order for configuration:
  1. Command-line options (highest priority)
  2. Environment variables
  3. Configuration files (if present)
  4. Default values (lowest priority)

​
Common Workflows

​
Setting up a new project

# Initialize project
hyrex init

# Set database URL
export HYREX_DATABASE_URL="postgresql://localhost/hyrex"

# Start a worker (automatically initializes database if needed)
hyrex run-worker hyrex_app:app

# Launch monitoring UI
hyrex studio

​
Running workers for different task types

# Email processing worker
hyrex run-worker hyrex_app:app --queue-pattern "email-*" --num-processes 4

# Data processing worker with more processes
hyrex run-worker hyrex_app:app --queue-pattern "data-*" --num-processes 16

# Critical tasks worker with debug logging
hyrex run-worker hyrex_app:app --queue-pattern "critical-*" --log-level DEBUG