Skip to main content

​
Flags Reference

Complete reference for all Codeflash CLI flags and command-line options.

​
Main Command Flags

FlagTypeDescription
--filePATHOptimize only this file
--functionNAMEOptimize only this function (requires --file)
--all[PATH]Optimize all functions. Optional path to start from
--replay-testPATHPath to replay test file(s)
--benchmarkflagEnable benchmark mode
--no-prflagDon’t create PR, update locally
--no-gen-testsflagDon’t generate tests
--no-draftflagSkip draft PRs
--worktreeflagUse git worktree
--staging-reviewflagUpload to staging
--verbose / -vflagVerbose debug output
--verify-setupflagRun setup verification
--versionflagShow version

​
Configuration Override Flags

Override settings from pyproject.toml via command line.
FlagTypeDescription
--config-filePATHPath to pyproject.toml
--module-rootPATHPython module root directory
--tests-rootPATHTests directory
--benchmarks-rootPATHBenchmarks directory
# 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

​
Optimize Subcommand Flags

Flags specific to the codeflash optimize command.
FlagTypeDescription
--outputPATHTrace file output path (default: codeflash.trace)
--timeoutINTMaximum trace time in seconds
--max-function-countINTMax times to trace a function (default: 100)
--config-file-pathPATHPath to pyproject.toml
--trace-onlyflagOnly trace, don’t optimize
The --output flag specifies where to save the trace file. If not specified, it defaults to codeflash.trace in the current directory.

​
Behavior Flags

Control how Codeflash behaves during optimization.
FlagDescription
--no-prRun locally without creating a pull request
--no-gen-testsUse only existing tests, skip test generation
--no-draftSkip optimization for draft PRs (CI mode)
--worktreeUse git worktree for isolated optimization
--staging-reviewUpload optimizations to staging for review
--verbose / -vEnable verbose debug logging
# 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

​
Flag Combinations

Common flag combinations for different use cases:

​
Local Development

# Optimize locally with verbose output
codeflash --file src/app.py --function main --no-pr --verbose

​
CI/CD Pipeline

# Skip draft PRs and use existing tests only
codeflash --all --no-draft --no-gen-tests

​
Debugging

# Trace only with custom output and timeout
codeflash optimize app.py --trace-only --output debug.trace --timeout 60

​
Custom Configuration

# Override multiple config settings
codeflash --file src/app.py --function main \
  --module-root src \
  --tests-root tests/unit \
  --benchmarks-root tests/benchmarks \
  --no-pr

​
Next Steps

Optimization Commands

Learn how to use optimization commands

Troubleshooting

Fix common issues