> ## Documentation Index
> Fetch the complete documentation index at: https://hyrex.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Command-line interface for Hyrex Python SDK

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:

```bash theme={null}
pip install hyrex
```

## Commands

### `hyrex init`

Initialize a new Hyrex project with interactive setup.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
hyrex studio [OPTIONS]
```

**Options:**

* `--port INTEGER` - Port to run the studio server (default: `1337`)
* `--verbose` - Enable verbose logging

**Examples:**

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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
```