CLI Reference

CLI Reference

Complete reference for the Copybara command-line interface.

Basic Usage

java -jar copybara_deploy.jar <command> <config_file> [workflow] [source_ref] [flags]

Tip

Create an alias for convenience: bash alias copybara='java -jar /path/to/copybara_deploy.jar' Then use copybara instead of java -jar copybara_deploy.jar in all commands.

Commands

Copybara supports the following commands:

Command	Description
migrate	Execute a migration workflow (default)
validate	Validate configuration without running
info	Show migration state and pending changes
feedback	Run a feedback workflow
help	Show help for commands and flags
version	Show Copybara version
generator	Generate a config file interactively
onboard	Experimental assisted onboarding tool
regenerate	Regenerate patch files

migrate

The primary command for running synchronization workflows:

copybara migrate copy.bara.sky workflow_name [source_ref] [flags]

Arguments:

• config_file: Path to your .bara.sky configuration file
• workflow_name: Name of the workflow to run (defaults to default)
• source_ref: Optional reference to migrate from (usually auto-detected)

Example:

copybara migrate copy.bara.sky export --init-history

validate

Validate configuration syntax and structure without executing:

copybara validate copy.bara.sky [workflow_name]

Example:

copybara validate copy.bara.sky export

info

Show information about the migration state:

copybara info copy.bara.sky workflow_name

Shows the last migrated revision and pending changes.

feedback

Run a feedback workflow (for event-driven actions):

copybara feedback copy.bara.sky feedback_workflow_name

help

Show help for any command:

copybara help              # General help
copybara help migrate      # Help for migrate command

version

Show the installed Copybara version:

copybara version

generator

Interactively generate a configuration file:

copybara generator

Note

The generator command asks questions to help you create a basic configuration file. Useful for getting started quickly.

---

Common Flags

Migration Control

—init-history

Process all history from the beginning. Required for first-time sync:

copybara migrate copy.bara.sky export --init-history

Caution

Only use --init-history for the initial migration. Subsequent runs should not use this flag.

—last-rev

Start from a specific commit SHA:

copybara migrate copy.bara.sky export --last-rev abc123def456

Useful for:

• Resetting state after issues
• Skipping problematic commits
• Starting from a known good point

—force

Force sync even if state tracking suggests changes were already migrated:

copybara migrate copy.bara.sky export --force

—ignore-noop

Don’t fail if there are no changes to migrate (exit code 0 instead of 2):

copybara migrate copy.bara.sky export --ignore-noop

Recommended for CI/CD where “no changes” is not an error.

—dry-run

Preview what would happen without making actual changes:

copybara migrate copy.bara.sky export --dry-run

Some destinations may still create draft PRs in dry-run mode.

—squash

Override workflow mode to SQUASH for this run:

copybara migrate copy.bara.sky export --squash

Useful for one-off squashed exports from ITERATIVE workflows.

---

Local Testing

These flags help you test workflows locally without pushing to real destinations.

—folder-dir

Write output to a local directory instead of the configured destination:

copybara migrate copy.bara.sky export --folder-dir /tmp/output

Tip

This is the most useful flag for debugging transformations. Inspect the output directory to verify files are transformed correctly.

Note: The directory will be cleared before writing. All existing files are deleted.

—to-folder

Force any workflow to use folder.destination() without modifying the config:

copybara migrate copy.bara.sky export --to-folder

Combined with --folder-dir:

copybara migrate copy.bara.sky export --to-folder --folder-dir /tmp/preview

This is perfect for testing what a real workflow would produce.

---

Git Overrides

Override Git-related settings from the command line.

—git-destination-url

Override the destination repository URL:

copybara migrate copy.bara.sky export \
  --git-destination-url https://github.com/other/repo

—git-destination-push

Override the destination branch to push to:

copybara migrate copy.bara.sky export \
  --git-destination-push feature-branch

—git-destination-fetch

Override the destination branch to fetch from:

copybara migrate copy.bara.sky export \
  --git-destination-fetch main

—default-author

Override the default commit author:

copybara migrate copy.bara.sky export \
  --default-author "Bot <bot@example.com>"

---

GitHub/Gerrit Flags

—gerrit-change-id

Reuse a specific Gerrit change ID:

copybara migrate copy.bara.sky export \
  --gerrit-change-id I1234567890abcdef

—gerrit-topic

Set the Gerrit topic for the change:

copybara migrate copy.bara.sky export \
  --gerrit-topic my-feature

—github-destination-pr-branch

Override the PR branch name:

copybara migrate copy.bara.sky export \
  --github-destination-pr-branch custom-branch-name

---

Advanced Flags

—read-config-from-change

Read the config from the change being migrated (for versioned configs):

copybara migrate copy.bara.sky export --read-config-from-change

—iterative-limit-changes

Limit the number of changes to process in ITERATIVE mode:

copybara migrate copy.bara.sky export --iterative-limit-changes 10

—same-version

Re-import the same version that was last imported:

copybara migrate copy.bara.sky export --same-version

Useful for verifying config refactors don’t change output.

Set the root path for resolving absolute config labels:

copybara migrate copy.bara.sky export \
  --config-root /path/to/configs

---

Output Control

—console-file-path

Write console output to a file:

copybara migrate copy.bara.sky export \
  --console-file-path copybara.log

-v, —verbose

Increase output verbosity:

copybara migrate copy.bara.sky export -v      # Verbose
copybara migrate copy.bara.sky export -v -v   # More verbose

—noansi

Disable ANSI color codes (useful for CI logs):

copybara migrate copy.bara.sky export --noansi

---

Performance Flags

—commands-timeout

Set timeout for individual commands (default: 15 minutes):

copybara migrate copy.bara.sky export --commands-timeout PT30M

Format uses ISO 8601 duration (PT = Period Time, M = Minutes, H = Hours).

—repo-timeout

Set timeout for repository operations (default: 15 minutes):

copybara migrate copy.bara.sky export --repo-timeout PT20M

—threads

Number of threads for parallel transformations (default: 10):

copybara migrate copy.bara.sky export --threads 20

---

Examples

First-Time Sync

copybara migrate copy.bara.sky export --init-history

Incremental Sync (CI/CD)

copybara migrate copy.bara.sky export --ignore-noop

Preview Changes Locally

copybara migrate copy.bara.sky export \
  --to-folder \
  --folder-dir /tmp/preview

Force Re-sync from Specific Commit

copybara migrate copy.bara.sky export \
  --last-rev abc123 \
  --force

Validate Configuration

copybara validate copy.bara.sky

Debug with Verbose Output

copybara migrate copy.bara.sky export \
  --to-folder \
  --folder-dir /tmp/debug \
  -v

---

Exit Codes

Code	Meaning
0	Success
1	Error (configuration, runtime, or authentication)
2	No changes to migrate (use --ignore-noop to suppress)

---

Environment Variables

Variable	Description
COPYBARA_CONFIG	Default configuration file path
GIT_AUTHOR_NAME	Override Git author name
GIT_AUTHOR_EMAIL	Override Git author email
GIT_COMMITTER_NAME	Override Git committer name
GIT_COMMITTER_EMAIL	Override Git committer email

---

Next Steps

• Core module reference
• Git module reference
• Troubleshooting common issues