API Reference

This section provides detailed documentation for the RunLy Python API.

Core Classes

Command

class runly.Command(name: str, script: str, args: ~typing.List[str] = <factory>, description: str = '', dependencies: ~typing.Set[str] = <factory>)

Bases: object

Represents a command in a justfile.

name: str

script: str

args: List[str]

description: str = ''

dependencies: Set[str]

__post_init__()

Validate command after initialization.

__init__(name: str, script: str, args: ~typing.List[str] = <factory>, description: str = '', dependencies: ~typing.Set[str] = <factory>) → None

CommandSet

class runly.CommandSet(commands: ~typing.List[~runly.commands.Command], variables: ~typing.Dict[str, str] = <factory>, default_command: str | None = None)

Bases: object

A set of commands parsed from a justfile.

commands: List[Command]

variables: Dict[str, str]

default_command: str | None = None

__post_init__()

Validate command set after initialization.

get_command(name: str) → Command | None

Get a command by name.

get_commands_with_dependencies() → Dict[str, Set[str]]

Get a dictionary mapping command names to their dependencies.

__init__(commands: ~typing.List[~runly.commands.Command], variables: ~typing.Dict[str, str] = <factory>, default_command: str | None = None) → None

JustfileParser

class runly.JustfileParser(filepath: str)

Bases: object

Parser for justfile and YAML configuration files.

__init__(filepath: str)

Initialize the parser with a justfile path.

parse() → CommandSet

Parse the justfile and return a CommandSet.

CommandRunner

class runly.CommandRunner(command_set: CommandSet, dry_run: bool = False, quiet: bool = False, verbose: bool = False)

Bases: object

Runs commands from a CommandSet.

__init__(command_set: CommandSet, dry_run: bool = False, quiet: bool = False, verbose: bool = False)

Initialize the runner with a command set.

run(command_name: str, args: List[str] | None = None) → int

Run a command by name with optional arguments.

Exceptions

Base Exceptions

class runly.RunLyError(message: str, details: str | None = None)

Bases: Exception

Base exception for all RunLy errors.

__init__(message: str, details: str | None = None) → None

class runly.JustfileError(message: str, filepath: str | None = None, line_number: int | None = None, details: str | None = None)

Bases: RunLyError

Base exception for justfile-related errors.

__init__(message: str, filepath: str | None = None, line_number: int | None = None, details: str | None = None) → None

class runly.CommandError(message: str, command_name: str | None = None, details: str | None = None)

Bases: RunLyError

Base exception for command-related errors.

__init__(message: str, command_name: str | None = None, details: str | None = None) → None

class runly.DependencyError(message: str, command_name: str | None = None, details: str | None = None)

Bases: CommandError

Base exception for dependency-related errors.

Specific Exceptions

class runly.CommandNotFoundError(message: str, command_name: str | None = None, details: str | None = None)

Bases: CommandError

Exception raised when a command is not found.

class runly.CommandExecutionError(message: str, command_name: str | None = None, exit_code: int | None = None, stdout: str | None = None, stderr: str | None = None)

Bases: CommandError

Exception raised when command execution fails.

__init__(message: str, command_name: str | None = None, exit_code: int | None = None, stdout: str | None = None, stderr: str | None = None) → None

class runly.JustfileNotFoundError(message: str, filepath: str | None = None, line_number: int | None = None, details: str | None = None)

Bases: JustfileError

Exception raised when justfile cannot be found.

Utility Functions

Utility functions for RunLy.

runly.utils.expand_variables(text: str, variables: Dict[str, str]) → str

Expand variables in text using the provided variables dictionary.

Supports: - {{VAR}} syntax (Just/RunLy format) - ${VAR} or $VAR syntax - Environment variables using ${env:NAME} syntax

CLI Module

Command-line interface for RunLy.

runly.cli.find_justfile() → Path | None

Find the justfile in the current directory or parent directories.

runly.cli.display_commands_table(command_set) → None

Display available commands in a formatted table.

runly.cli.parse_arguments(args: List[str]) → Tuple[Namespace, List[str]]

Parse command line arguments.

runly.cli.main(argv: List[str] | None = None) → int

Main entry point for the CLI.