Codeflash CLI Reference

This guide covers all Codeflash CLI commands with practical examples you can run directly in your terminal.

Prerequisites - Ensure Codeflash is installed in your Python environment and you have a configured pyproject.toml in your project.

Quick Start

Linux/macOS
Windows

# Activate virtual environment (if using one)
source .venv/bin/activate

# Verify installation
codeflash --version

# Activate virtual environment (if using one)
.venv\Scripts\activate

# Verify installation
codeflash --version

Common Workflows

1. First-Time Setup

Install Codeflash

pip install codeflash

Initialize Project

codeflash init

Verify Setup

codeflash --verify-setup

Run First Optimization

codeflash --file src/main.py --function my_function --no-pr

2. Optimize a Workflow

Trace Your Script

codeflash optimize my_script.py --arg1 value1

Review Optimizations

Check the generated PR or local changes for optimization suggestions.

3. CI/CD Integration

Set Up GitHub Actions

codeflash init-actions

Merge the Workflow PR

Review and merge the generated GitHub Actions workflow.

Automatic Optimization

Codeflash will now optimize code in every PR automatically!

Help & Version

# Display version
codeflash --version

# Main help
codeflash --help

# Subcommand help
codeflash optimize --help
codeflash init --help

Complete Flag Reference

Main Command Flags

Flag	Type	Description
`--file`	`PATH`	Optimize only this file
`--function`	`NAME`	Optimize only this function (requires `--file`)
`--all`	`[PATH]`	Optimize all functions. Optional path to start from
`--replay-test`	`PATH`	Path to replay test file(s)
`--benchmark`	flag	Enable benchmark mode
`--no-pr`	flag	Don’t create PR, update locally
`--no-gen-tests`	flag	Don’t generate tests
`--no-draft`	flag	Skip draft PRs
`--worktree`	flag	Use git worktree
`--staging-review`	flag	Upload to staging
`--verbose` / `-v`	flag	Verbose debug output
`--verify-setup`	flag	Run setup verification
`--version`	flag	Show version

Configuration Override Flags

Flag	Type	Description
`--config-file`	`PATH`	Path to pyproject.toml
`--module-root`	`PATH`	Python module root directory
`--tests-root`	`PATH`	Tests directory
`--benchmarks-root`	`PATH`	Benchmarks directory

Optimize Subcommand Flags

Flag	Type	Description
`--output`	`PATH`	Trace file output path (default: `codeflash.trace`)
`--timeout`	`INT`	Maximum trace time in seconds
`--max-function-count`	`INT`	Max times to trace a function (default: 100)
`--config-file-path`	`PATH`	Path to pyproject.toml
`--trace-only`	flag	Only trace, don’t optimize

Troubleshooting

'Functions outside module-root' Error

Problem: Function not found because file is outside module-root.Solution: Ensure your file is within the module-root directory specified in pyproject.toml.

# Check your module-root
grep "module-root" pyproject.toml

# Use the correct path (e.g., if module-root is "src")
codeflash --file src/myfile.py --function my_function --no-pr

'benchmarks-root must be specified' Error

Problem: Using --benchmark without specifying benchmarks directory.Solution: Either add benchmarks-root to pyproject.toml or use the flag:

codeflash --file src/app.py --benchmark --benchmarks-root tests/benchmarks --no-pr

Replay Test File Not Found

Problem: Replay test filename doesn’t match expected path.Solution: Replay tests include the module path in their name. Check the actual filename:

# Linux/macOS
ls tests/test_*replay*.py

# Windows
dir tests\test_*replay*.py

GitHub App Required

Problem: PR creation fails due to missing GitHub App.Solution: Install the Codeflash GitHub App or use --no-pr for local optimization:

# Local optimization
codeflash --file src/app.py --function main --no-pr

# Or install the GitHub App
# https://github.com/apps/codeflash-ai/installations/select_target

Core Commands

`codeflash init`

Initialize Codeflash for your Python project. This creates the configuration in pyproject.toml.

codeflash init

The init command will guide you through an interactive setup process, including API key configuration, module selection, and GitHub App installation.

`codeflash init-actions`

Set up GitHub Actions workflow for continuous optimization on every pull request.

codeflash init-actions

This command:

Creates a workflow file in .github/workflows/
Opens a PR with the workflow configuration
Requires the Codeflash GitHub App to be installed

`codeflash vscode-install`

Install the Codeflash extension for VS Code, Cursor, or Windsurf.

codeflash vscode-install

`codeflash --verify-setup`

Verify your Codeflash installation by running a sample optimization.

codeflash --verify-setup

This command creates a temporary file, runs a sample optimization, and cleans up afterward. It takes about 3 minutes to complete.

Function Optimization

Optimize a Single Function

Target a specific function in a file for optimization.

codeflash --file <path/to/file.py> --function <function_name>

Complete Examples

Linux/macOS
Windows

# Basic optimization (creates PR)
codeflash --file src/utils.py --function calculate_metrics

# Local optimization only (no PR)
codeflash --file src/utils.py --function calculate_metrics --no-pr

# With verbose output
codeflash --file src/utils.py --function calculate_metrics --no-pr --verbose

# Basic optimization (creates PR)
codeflash --file src\utils.py --function calculate_metrics

# Local optimization only (no PR)
codeflash --file src\utils.py --function calculate_metrics --no-pr

# With verbose output
codeflash --file src\utils.py --function calculate_metrics --no-pr --verbose

Important: The file must be within your configured module-root directory. Files outside module-root will be ignored with “Functions outside module-root” message.

Optimize All Functions

Optimize all functions in your entire codebase or a specific directory.

# Optimize entire codebase
codeflash --all

# Optimize specific directory
codeflash --all src/core/

Complete Examples

Linux/macOS
Windows

# Optimize all (creates PRs)
codeflash --all

# Optimize all locally (no PRs)
codeflash --all --no-pr

# Optimize specific directory
codeflash --all src/algorithms/ --no-pr

# Skip draft PRs in CI
codeflash --all --no-draft

# Optimize all (creates PRs)
codeflash --all

# Optimize all locally (no PRs)
codeflash --all --no-pr

# Optimize specific directory
codeflash --all src\algorithms\ --no-pr

# Skip draft PRs in CI
codeflash --all --no-draft

Trace & Optimize Workflows

`codeflash optimize`

Trace a Python script’s execution and optimize functions based on real-world usage.

codeflash optimize <script.py> [script_args]

Complete Examples

Linux/macOS
Windows

# Basic trace and optimize
codeflash optimize app.py

# With script arguments
codeflash optimize process.py --input data.csv --output results.json

# Custom trace output file
codeflash optimize app.py --output custom_trace.trace

# With timeout (30 seconds)
codeflash optimize long_running_script.py --timeout 30

# Limit function trace count
codeflash optimize app.py --max-function-count 50

# Specify config file
codeflash optimize app.py --config-file-path pyproject.toml

# Local only (no PR)
codeflash optimize app.py --no-pr

# Basic trace and optimize
codeflash optimize app.py

# With script arguments
codeflash optimize process.py --input data.csv --output results.json

# Custom trace output file
codeflash optimize app.py --output custom_trace.trace

# With timeout (30 seconds)
codeflash optimize long_running_script.py --timeout 30

# Limit function trace count
codeflash optimize app.py --max-function-count 50

# Specify config file
codeflash optimize app.py --config-file-path pyproject.toml

# Local only (no PR)
codeflash optimize app.py --no-pr

Trace with pytest

Optimize functions called during pytest test execution.

Linux/macOS
Windows

# Trace pytest tests
codeflash optimize -m pytest tests/

# Trace specific test file
codeflash optimize -m pytest tests/test_core.py

# With pytest arguments
codeflash optimize -m pytest tests/ -v --tb=short

# Trace pytest tests
codeflash optimize -m pytest tests\

# Trace specific test file
codeflash optimize -m pytest tests\test_core.py

# With pytest arguments
codeflash optimize -m pytest tests\ -v --tb=short

Trace Only (Generate Replay Tests)

Create trace files and replay tests without running optimization.

Linux/macOS
Windows

# Trace only - generates replay test
codeflash optimize app.py --output trace_file.trace --trace-only

# Then optimize using the replay test
codeflash --replay-test tests/test_app_py__replay_test_0.py --no-pr

# Trace only - generates replay test
codeflash optimize app.py --output trace_file.trace --trace-only

# Then optimize using the replay test
codeflash --replay-test tests\test_app_py__replay_test_0.py --no-pr

Replay test naming: Files are named based on the traced script path. For src/app.py, the replay test will be named like test_srcapp_py__replay_test_0.py.

Benchmark Mode

Optimize code based on performance benchmarks using pytest-benchmark format.

codeflash --file <file.py> --benchmark --benchmarks-root <path>

Complete Examples

Linux/macOS
Windows

# With benchmarks-root flag
codeflash --file src/core.py --benchmark --benchmarks-root tests/benchmarks --no-pr

# If benchmarks-root is in pyproject.toml
codeflash --file src/core.py --benchmark --no-pr

# With benchmarks-root flag
codeflash --file src\core.py --benchmark --benchmarks-root tests\benchmarks --no-pr

# If benchmarks-root is in pyproject.toml
codeflash --file src\core.py --benchmark --no-pr

The --benchmarks-root directory must exist and be configured either via pyproject.toml or the command-line flag.

Configuration Flags

Override configuration settings from the command line.

Flag	Description
`--config-file`	Path to `pyproject.toml` with Codeflash config
`--module-root`	Path to Python module to optimize
`--tests-root`	Path to test directory
`--benchmarks-root`	Path to benchmarks directory

Complete Examples

Linux/macOS
Windows

# Override config file location
codeflash --file src/app.py --function main --config-file configs/pyproject.toml --no-pr

# Override module root
codeflash --file src/app.py --function main --module-root src --no-pr

# Override tests root
codeflash --file src/app.py --function main --tests-root tests/unit --no-pr

# Combine multiple overrides
codeflash --file src/app.py --function main \
  --module-root src \
  --tests-root tests \
  --no-pr

# Override config file location
codeflash --file src\app.py --function main --config-file configs\pyproject.toml --no-pr

# Override module root
codeflash --file src\app.py --function main --module-root src --no-pr

# Override tests root
codeflash --file src\app.py --function main --tests-root tests\unit --no-pr

Behavior Flags

Flag	Description
`--no-pr`	Run locally without creating a pull request
`--no-gen-tests`	Use only existing tests, skip test generation
`--no-draft`	Skip optimization for draft PRs (CI mode)
`--worktree`	Use git worktree for isolated optimization
`--staging-review`	Upload optimizations to staging for review
`--verbose` / `-v`	Enable verbose debug logging

Complete Examples

# Local optimization only
codeflash --file src/app.py --function main --no-pr

# Use only existing tests
codeflash --file src/app.py --function main --no-gen-tests --no-pr

# Enable verbose logging
codeflash --file src/app.py --function main --verbose --no-pr

# Use worktree for isolation
codeflash --file src/app.py --function main --worktree --no-pr

# Upload to staging
codeflash --all --staging-review --no-pr

Next Steps

Optimize a Function

Learn how to optimize individual functions

Trace & Optimize

Optimize entire workflows with tracing

GitHub Actions

Set up continuous optimization

Configuration

Advanced configuration options

🚀 Quickstart

🏠 Overview

📖 CLI Reference

🛠 IDE Extensions

⚡ Optimizing with Codeflash

✨ Continuous Optimization

🧠 Core Concepts

⚙️ Configuration & Best Practices

​Codeflash CLI Reference

​Quick Start

​Common Workflows

​1. First-Time Setup

​2. Optimize a Workflow

​3. CI/CD Integration

​Help & Version

​Complete Flag Reference

​Main Command Flags

​Configuration Override Flags

​Optimize Subcommand Flags

​Troubleshooting

​Core Commands

​codeflash init

​codeflash init-actions

​codeflash vscode-install

​codeflash --verify-setup

​Function Optimization

​Optimize a Single Function

​Optimize All Functions

​Trace & Optimize Workflows

​codeflash optimize

​Trace with pytest

​Trace Only (Generate Replay Tests)

​Benchmark Mode

​Configuration Flags

​Behavior Flags

​Next Steps

Optimize a Function

Trace & Optimize

GitHub Actions

Configuration

Codeflash CLI Reference

Quick Start

Common Workflows

1. First-Time Setup

2. Optimize a Workflow

3. CI/CD Integration

Help & Version

Complete Flag Reference

Main Command Flags

Configuration Override Flags

Optimize Subcommand Flags

Troubleshooting

Core Commands

`codeflash init`

`codeflash init-actions`

`codeflash vscode-install`

`codeflash --verify-setup`

Function Optimization

Optimize a Single Function

Optimize All Functions

Trace & Optimize Workflows

`codeflash optimize`

Trace with pytest

Trace Only (Generate Replay Tests)

Benchmark Mode

Configuration Flags

Behavior Flags

Next Steps