Skip to content
Code Search

CLI Replace

The code-search replace command enables bulk search and replace operations across multiple repositories with automatic merge/pull request creation.

How It Works

Section titled “How It Works”

The replace command uses a two-phase flow:

  1. Preview Phase: Searches for matches and displays what will be changed
  2. Execute Phase: Uses the matches from preview to perform replacements and create MRs

This design ensures:

  • You always see what will change before committing
  • The execute phase is fast since it doesn’t need to re-search
  • Exact consistency between preview and execution
  • All changes go through merge request review

Basic Usage

Section titled “Basic Usage”
Terminal window
# Preview changes (default mode)
code-search replace "oldFunction" "newFunction"


# Execute changes (creates MR)
code-search replace "oldFunction" "newFunction" --execute


# With custom branch and MR title
code-search replace "oldFunction" "newFunction" --execute \
  --branch "refactor/rename-function" \
  --mr-title "Rename oldFunction to newFunction"

Command Syntax

Section titled “Command Syntax”
Terminal window
code-search replace <old> <new> [flags]

Command Options

Section titled “Command Options”

Execution Control

Section titled “Execution Control”
OptionShortDescription
--preview-pPreview changes without applying (default: true)
--executeExecute the replacements (creates MR)

Filters

Section titled “Filters”
OptionShortDescription
--repos-RFilter to specific repositories (comma-separated)
--files-fFilter by file patterns (comma-separated)
--case-sensitiveEnable case-sensitive matching

Pattern Options

Section titled “Pattern Options”
OptionShortDescription
--regex-rTreat search pattern as regex

MR/PR Options

Section titled “MR/PR Options”
OptionShortDescription
--branch-bBranch name for changes
--mr-titleMR/PR title
--mr-descriptionMR/PR description

Authentication

Section titled “Authentication”
OptionShortDescription
--tokensPer-connection tokens for push access (see below)

Examples

Section titled “Examples”

Simple Replace

Section titled “Simple Replace”
Terminal window
# Preview renaming a function
code-search replace "getUserById" "findUserById" --repos myorg/api


# Execute the rename (creates MR)
code-search replace "getUserById" "findUserById" --repos myorg/api --execute

Regex Replace

Section titled “Regex Replace”
Terminal window
# Update version numbers
code-search replace 'v(\d+)\.(\d+)\.(\d+)' 'v$1.$2.999' --regex


# Rename function with pattern
code-search replace 'get(\w+)ById' 'find$1ById' --regex

With Custom MR Options

Section titled “With Custom MR Options”
Terminal window
code-search replace "v1.0.0" "v2.0.0" \
  --repos "myorg/api" \
  --files "version.go" \
  --execute \
  --branch "release/v2.0.0" \
  --mr-title "Bump version to v2.0.0"

Common Use Cases

Section titled “Common Use Cases”

Version Bumps

Section titled “Version Bumps”
Terminal window
code-search replace "1.2.3" "1.3.0" \
  --files "package.json" \
  --repos "myorg/api" \
  --execute

Dependency Updates

Section titled “Dependency Updates”
Terminal window
code-search replace '"lodash": "4.17.20"' '"lodash": "4.17.21"' \
  --files "package.json" \
  --repos "myorg/frontend" \
  --execute

API Migration

Section titled “API Migration”
Terminal window
code-search replace "api/v1" "api/v2" \
  --repos "myorg/backend" \
  --execute \
  --branch "api-v2-migration"

Replace Jobs

Section titled “Replace Jobs”

When you execute a replace with --execute, the operation is queued as a background job. The CLI sends the matches from the preview to the server, so the job doesn’t need to re-search.

Job Flow

Section titled “Job Flow”
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ CLI Preview │────▶│ Show Matches│────▶│ Confirm (y) │────▶│ Queue Job   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                   │
                                                                   ▼
                                                           ┌─────────────┐
                                                           │ Worker runs │
                                                           │ creates MR  │
                                                           └─────────────┘
Terminal window
# The execute command returns a job ID
code-search replace "old" "new" --execute
# Preview:
#   myorg/repo/file.go:10: oldValue
#   myorg/repo/file.go:25: oldValue
#
# Found 2 matches. Execute replacement (MR will be created)? [y/N]: y
# ✅ Replace job queued
#    Job ID: abc123
#    Status: pending

Next Steps

Section titled “Next Steps”