Advanced: Adjust the BitBoxApp Gap Limit Using Command-Line Parameters

Table of Contents

When to use the command-line method About temporary gap-limit overrides Recommended starting values Windows macOS Linux After launching with custom gap limits Frequently Asked Questions (FAQ) Is the command-line method safe? Why use this instead of the UI? Will I lose bitcoin if they were sent beyond the default gap? Does this change apply after restarting the app?

This article provides advanced instructions for adjusting the BitBoxApp gap limit using command-line parameters.
This is intended only for special cases or for users comfortable working with terminals.

For most users, we strongly recommend using the built-in graphical method:
See: How to Adjust the Gap Limit in the BitBoxApp (Recommended Method)

When to use the command-line method

Use this method only if:

You are on Linux and need to launch the BitBoxApp with custom parameters
You prefer a command-line startup instead of modifying the UI settings
You are troubleshooting a specific recovery scenario with many unused or externally generated addresses
You know that your previous wallet software used non-standard or very large address gaps

The command-line method temporarily starts the BitBoxApp with custom scanning limits.
It does not modify your wallet, keys, or transactions.

About temporary gap-limit overrides

Command-line overrides apply only for the session during which the app is launched.
When you close the BitBoxApp and reopen it normally, it reverts to the default gap limits.
This behavior ensures compatibility across wallet apps and prevents accidental misconfiguration.

Recommended starting values

Start with:

50 for receive addresses
50 for change addresses

If the balance remains incorrect after the rescan, restart the BitBoxApp and try:

Only increase as needed.

Windows

Open the Start Menu, type Command Prompt, and open it.
Navigate to the BitBoxApp installation folder by typing cd "C:\Program Files\BitBox" and pressing Enter.
Run one of the commands below to launch the app with the new limit:
1. To set only the receive address limit:
```
.\BitBox.exe --gap-limit-receive 50
```
2. To set only the change address limit:
```
.\BitBox.exe --gap-limit-change 50
```
3. To set both limits:
```
.\BitBox.exe --gap-limit-receive 50 --gap-limit-change 50
```

macOS

Open the Terminal app (you can find it in Applications > Utilities).

Run one of the commands below:

To set the receive address limit:

open -a BitBox --args --gap-limit-receive 50

To set the change address limit:

open -a BitBox --args --gap-limit-change 50

To set both limits:

open -a BitBox --args --gap-limit-receive 50 --gap-limit-change 50

Linux

The command depends on how you installed the BitBoxApp.

Package installation (.deb, .rpm):

If you installed BitBoxApp via a package manager, the command-line tool is usually BitBox and available in your system's PATH.

To set the receive address gap limit:

BitBox -gapLimitReceive 50

To set the change address gap limit:

BitBox -gapLimitChange 50

To set both limits:

BitBox -gapLimitReceive 50 -gapLimitChange 50

If the BitBox command doesn't work, find its full path using which BitBox or whereis BitBox. It's often in /usr/bin or /usr/local/bin. For example, on Ubuntu/Debian:

$ which BitBox
/usr/bin/BitBox
$ /usr/bin/BitBox -gapLimitReceive 50

AppImage:

If you're using an AppImage:

First, make the AppImage file executable (if you haven't already):

chmod +x BitBox-[version]-x86_64.AppImage

(Replace BitBox-[version]-x86_64.AppImage with your actual file name)

To set the receive address gap limit:

./BitBox-[version]-x86_64.AppImage -gapLimitReceive 50

To set the change address gap limit:

./BitBox-[version]-x86_64.AppImage -gapLimitChange 50

To set both limits:

./BitBox-[version]-x86_64.AppImage -gapLimitReceive 50 -gapLimitChange 50

After launching with custom gap limits

Once the BitBoxApp starts:

It rescans account history using the overridden gap limit
Missing transactions and balances should appear if they were located beyond the default scan range
If the balance is still incorrect, close the app and relaunch with a higher number

No changes are permanent unless repeated at startup.

Frequently Asked Questions (FAQ)

Is the command-line method safe?

Yes. It only affects how the BitBoxApp scans for history.
It does not modify keys, addresses, or wallet structure.

Why use this instead of the UI?

Most users should use the UI-based method.
The command-line method is for:

Linux users
Automated troubleshooting
Non-standard wallet recoveries
Situations where BitBoxApp UI cannot be used or does not start normally

Will I lose bitcoin if they were sent beyond the default gap?

No. The funds remain on the blockchain.
You only need to increase the scan depth to discover them.

Does this change apply after restarting the app?

No. All command-line overrides are session-only.