CLI Interface

docetl.cli.run(yaml_file=typer.Argument(..., help='Path to the YAML file containing the pipeline configuration'), max_threads=typer.Option(None, help='Maximum number of threads to use for running operations'))

Run the configuration specified in the YAML file.

Parameters:

Name	Type	Description	Default
yaml_file	Path	Path to the YAML file containing the pipeline configuration.	Argument(..., help='Path to the YAML file containing the pipeline configuration')
max_threads	int | None	Maximum number of threads to use for running operations.	Option(None, help='Maximum number of threads to use for running operations')

Source code in docetl/cli.py

@app.command()
def run(
    yaml_file: Path = typer.Argument(
        ..., help="Path to the YAML file containing the pipeline configuration"
    ),
    max_threads: int | None = typer.Option(
        None, help="Maximum number of threads to use for running operations"
    ),
):
    """
    Run the configuration specified in the YAML file.

    Args:
        yaml_file (Path): Path to the YAML file containing the pipeline configuration.
        max_threads (int | None): Maximum number of threads to use for running operations.
    """
    # Get the current working directory (where the user called the command)
    cwd = os.getcwd()

    # Load .env file from the current working directory
    env_file = os.path.join(cwd, ".env")
    if os.path.exists(env_file):
        load_dotenv(env_file)

    runner = DSLRunner.from_yaml(str(yaml_file), max_threads=max_threads)
    runner.load_run_save()

docetl.cli.build(yaml_file=typer.Argument(..., help='Path to the YAML file containing the pipeline configuration'), max_threads=typer.Option(None, help='Maximum number of threads to use for running operations'))

Optimize a pipeline using MOAR (Multi-Objective Agentic Rewrites).

Requires an optimizer_config section in the YAML with at least

• evaluation_file: path to a Python file with a @docetl.register_eval function
• metric_key: key to extract from evaluation results

Models are auto-detected from API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, AZURE_API_KEY) unless available_models is set explicitly.

Parameters:

Name	Type	Description	Default
yaml_file	Path	Path to the YAML pipeline file.	Argument(..., help='Path to the YAML file containing the pipeline configuration')
max_threads	int | None	Maximum number of threads for operations.	Option(None, help='Maximum number of threads to use for running operations')

Source code in docetl/cli.py

@app.command()
def build(
    yaml_file: Path = typer.Argument(
        ..., help="Path to the YAML file containing the pipeline configuration"
    ),
    max_threads: int | None = typer.Option(
        None, help="Maximum number of threads to use for running operations"
    ),
):
    """
    Optimize a pipeline using MOAR (Multi-Objective Agentic Rewrites).

    Requires an optimizer_config section in the YAML with at least:
      - evaluation_file: path to a Python file with a @docetl.register_eval function
      - metric_key: key to extract from evaluation results

    Models are auto-detected from API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY,
    GEMINI_API_KEY, AZURE_API_KEY) unless available_models is set explicitly.

    Args:
        yaml_file (Path): Path to the YAML pipeline file.
        max_threads (int | None): Maximum number of threads for operations.
    """
    cwd = os.getcwd()

    env_file = os.path.join(cwd, ".env")
    if os.path.exists(env_file):
        load_dotenv(env_file)

    import yaml as yaml_lib

    with open(yaml_file, "r") as f:
        config = yaml_lib.safe_load(f)

    optimizer_config = config.get("optimizer_config", {})
    if not optimizer_config:
        example_yaml = """optimizer_config:
  evaluation_file: evaluate.py
  metric_key: score
  save_dir: ./moar_results       # optional, defaults to temp dir
  max_iterations: 20              # optional, defaults to 20
  # available_models:             # optional, auto-detected from API keys
  #   - gpt-4.1
  #   - anthropic/claude-sonnet-4-6"""

        error_panel = Panel(
            f"[bold red]Error:[/bold red] optimizer_config section is required in YAML.\n\n"
            f"[bold]Example:[/bold]\n"
            f"[dim]{example_yaml}[/dim]",
            title="[bold red]Missing optimizer_config[/bold red]",
            border_style="red",
        )
        console.print(error_panel)
        raise typer.Exit(1)

    required_fields = {
        "evaluation_file": "Path to evaluation function file",
        "metric_key": "Key to extract from evaluation results",
    }

    missing_fields = [
        field for field in required_fields if not optimizer_config.get(field)
    ]
    if missing_fields:
        fields_table = Table(
            show_header=True, header_style="bold cyan", box=None, padding=(0, 2)
        )
        fields_table.add_column("Field", style="yellow")
        fields_table.add_column("Description", style="dim")

        for field, desc in required_fields.items():
            style = "bold red" if field in missing_fields else "dim"
            fields_table.add_row(f"[{style}]{field}[/{style}]", desc)

        missing_list = ", ".join([f"[bold red]{f}[/bold red]" for f in missing_fields])

        from rich.console import Group

        error_group = Group(
            f"[bold red]Missing required fields:[/bold red] {missing_list}\n",
            "[bold]Required fields:[/bold]",
            fields_table,
        )

        error_panel = Panel(
            error_group,
            title="[bold red]Missing Required Fields[/bold red]",
            border_style="red",
        )
        console.print(error_panel)
        raise typer.Exit(1)

    from docetl.moar.optimizer import MOAROptimizer
    from docetl.utils_evaluation import load_custom_evaluate_func

    try:
        # Resolve dataset path for wrapping the eval function
        dataset_path = optimizer_config.get("dataset_path")
        if not dataset_path:
            ds = config.get("datasets", {})
            if ds:
                _, ds_cfg = next(iter(ds.items()))
                dataset_path = ds_cfg.get("path", "")

        eval_fn = load_custom_evaluate_func(
            optimizer_config["evaluation_file"],
            dataset_path or "",
        )

        opt = MOAROptimizer(
            pipeline=str(yaml_file),
            eval_fn=eval_fn,
            metric_key=optimizer_config["metric_key"],
            models=optimizer_config.get("available_models"),
            agent_model=optimizer_config.get("rewrite_agent_model")
            or optimizer_config.get("model"),
            max_iterations=optimizer_config.get("max_iterations", 20),
            save_dir=optimizer_config.get("save_dir"),
            exploration_weight=optimizer_config.get("exploration_weight", 1.414),
            dataset_path=optimizer_config.get("dataset_path"),
        )
        result = opt.optimize()

        typer.echo("\n✅ MOAR optimization completed successfully!")
        typer.echo(f"   Frontier: {len(result.frontier)} pipelines")
        best = result.best()
        if best:
            typer.echo(
                f"   Best accuracy: {best.accuracy:.4f} (cost: ${best.cost:.4f})"
            )
        cheapest = result.cheapest()
        if cheapest and cheapest is not best:
            typer.echo(
                f"   Cheapest: ${cheapest.cost:.4f} (accuracy: {cheapest.accuracy:.4f})"
            )
        if result.save_dir:
            typer.echo(f"\n   Optimized pipelines saved to: {result.save_dir}/")
            for p in result.frontier:
                tag = ""
                if best and p is best:
                    tag = " (best accuracy)"
                elif cheapest and p is cheapest:
                    tag = " (cheapest)"
                typer.echo(f"     - {Path(p.yaml_path).name}{tag}")
    except Exception as e:
        typer.echo(f"Error running MOAR optimization: {e}", err=True)
        raise typer.Exit(1)

docetl.cli.clear_cache()

Clear the LLM cache stored on disk.

Source code in docetl/cli.py

@app.command()
def clear_cache():
    """
    Clear the LLM cache stored on disk.
    """
    cc()