How to Throttle Upload Speed in croc Using the --throttleUpload Flag

Use the --throttleUpload flag (short form --throttle) followed by a numeric value and optional unit suffix (k, m, or g) to limit upload bandwidth when sending files with croc.

The schollz/croc file transfer tool includes built-in upload throttling to help you manage bandwidth consumption during transfers. By parsing a human-readable rate string, croc automatically configures a token bucket rate limiter that restricts how fast data leaves your machine. This feature is particularly useful when sharing large files over constrained networks or when you need to reserve bandwidth for other applications.

How the --throttleUpload Flag Works

Flag Declaration in src/cli/cli.go

In src/cli/cli.go at line 140, the --throttleUpload flag is registered as a global CLI option that accepts a string value. The flag definition allows users to specify rates like "500k" or "2M". When you execute a send command, the CLI builds an Options struct around line 370 and populates the ThrottleUpload field with the raw string value.

Options Propagation to the Client

The Options struct defined in src/croc/croc.go at line 96 contains the ThrottleUpload field that stores the user-provided rate string. This struct is passed to croc.New() during client initialization, making the throttle configuration available throughout the transfer session. The system only activates throttling when c.Options.IsSender is true, ensuring the limit applies exclusively to upload operations.

Rate Limiter Implementation in src/croc/croc.go

Between lines 57 and 80 of src/croc/croc.go, croc parses the throttle string and configures the rate limiter. If the flag value contains more than one character, the code extracts the numeric portion and applies the appropriate multiplier: k multiplies by 1024, m by 1024², and g by 1024³. The final bytes-per-second value feeds into rate.Every(time.Second / uploadLimit) from the golang.org/x/time/rate package, creating a limiter stored in c.limiter.

During transmission at approximately line 2913, the code calls c.limiter.ReserveN before each write operation. If the requested bytes exceed the available tokens, the reservation blocks until the rate limiter permits the transfer, effectively pacing the upload to your specified ceiling.

Usage Examples

Limit upload speed to 500 KB/s:

croc send --throttleUpload 500k myfile.txt

Limit to 2 MB/s:

croc send --throttleUpload 2M anotherfile.bin

Limit to 1 GB/s for high-speed network testing:

croc send --throttleUpload 1G hugefile.iso

Specify exact bytes per second (1 MiB/s):

croc send --throttleUpload 1048576 file.dat

Technical Implementation Details

The throttling mechanism relies on Go's standard token bucket algorithm. When parsing the flag value, croc differentiates between the numeric component and the alphabetic unit suffix. An input like "2M" becomes 2,097,152 bytes per second (2 × 1024 × 1024). The rate.Limiter then calculates a token replenishment interval based on this value.

This implementation appears in the test suite at src/croc/croc_test.go, which validates throttling behavior using configurations like ThrottleUpload: "512K". By reserving tokens before each network write, croc ensures the actual bytes sent per second never exceeds the configured limit, regardless of network conditions or buffer sizes.

Summary

• The --throttleUpload flag (or --throttle) in croc limits sender bandwidth using standard unit suffixes (k, m, g).
• Configuration flows from src/cli/cli.go to the Options struct in src/croc/croc.go, then into a rate.Limiter instance.
• The limiter applies only to send operations and uses token bucket pacing to enforce the specified bytes-per-second ceiling.
• Valid inputs include "500k", "2M", "1G", or raw byte counts like "1048576".

Frequently Asked Questions

What units does croc accept for the --throttleUpload flag?

croc accepts k or K for kilobytes (×1024), m or M for megabytes (×1024²), and g or G for gigabytes (×1024³). You can also omit the unit to specify exact bytes per second. For example, --throttleUpload 500k limits uploads to 512,000 bytes per second.

Does the throttle flag work when receiving files?

No. According to the source code in src/croc/croc.go, the rate limiter is only initialized when c.Options.IsSender evaluates to true. The --throttleUpload flag specifically governs outbound traffic; receiving files operates at full available bandwidth unless other network constraints apply.

What happens if I enter an invalid throttle value?

If the flag string contains a single character or fails to parse, croc treats the limit as zero or falls back to unlimited behavior. The parsing logic at lines 57-80 of src/croc/croc.go requires the string length to exceed one character to trigger multiplier parsing, providing graceful degradation for malformed inputs.

Can I use --throttle instead of --throttleUpload?

Yes. The flag has a short form --throttle that functions identically to --throttleUpload. Both flags update the same internal ThrottleUpload field in the Options struct, so you can use whichever syntax you find more intuitive.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}