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

> Limit croc upload speed using the --throttleUpload flag. Easily control bandwidth for file transfers with simple commands.

- Repository: [Zack/croc](https://github.com/schollz/croc)
- Tags: how-to-guide
- Published: 2026-07-23

---

**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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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:

```bash
croc send --throttleUpload 500k myfile.txt

```

Limit to 2 MB/s:

```bash
croc send --throttleUpload 2M anotherfile.bin

```

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

```bash
croc send --throttleUpload 1G hugefile.iso

```

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

```bash
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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) to the `Options` struct in [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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.