# Complete Guide to Croc CLI Options for Configuration

> Explore comprehensive croc CLI options for configuration. Discover global flags and subcommand specific settings to customize your secure file transfers.

- Repository: [Zack/croc](https://github.com/schollz/croc)
- Tags: api-reference
- Published: 2026-07-26

---

**Croc exposes configuration through 24 global flags and command-specific options for `send`, `relay`, and `serve` subcommands, all defined in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) and mapped to the `croc.Options` struct.**

The `schollz/croc` secure file transfer tool uses the `github.com/schollz/cli/v2` framework to expose granular control over encryption, networking, and transfer behavior. Understanding the available **croc CLI options for configuration** allows you to customize relay addresses, disable compression, configure proxy settings, and persist preferences across sessions. All flags are initialized in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) and applied to the transfer engine via the `croc.New()` function at line 665.

## Global Configuration Flags

Global flags in croc affect every subcommand. In [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go), these are defined starting at line 31 and include network, security, and usability toggles.

### Network and Connectivity Options

- **`--relay`** (String): Specifies the relay host address (default: `croc.schollz.com`). Source: [`L50`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L50)
- **`--relay6`** (String): IPv6 relay host address (default: `croc6.schollz.com`). Source: [`L51`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L51)
- **`--pass`** (String): Password for the relay (default: empty). Source: [`L53`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L53)
- **`--ip`** (String): Explicitly set the sender’s IP (e.g., `10.0.0.1:9009`). Source: [`L49`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L49)
- **`--local`**: Restrict transfers to the local network only. Source: [`L39`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L39)
- **`--multicast`** (String): Multicast address for local discovery (default: `239.255.255.250`). Source: [`L47`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L47)
- **`--socks5`** (String): SOCKS5 proxy URL (falls back to `SOCKS5_PROXY` environment variable). Source: [`L54`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L54)
- **`--connect`** (String): HTTP proxy URL (falls back to `HTTP_PROXY` environment variable). Source: [`L55`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L55)
- **`--throttleUpload`** (String): Limit upload bandwidth (e.g., `500k`). Source: [`L56`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L56)
- **`--internal-dns`**: Use the built-in DNS stub resolver instead of the host OS resolver. Source: [`L31`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L31)

### Security and Encryption Options

- **`--curve`** (String): Encryption curve selection (`p256`, `p384`, etc.). Defaults to available curves from `pake.AvailableCurves()`. Source: [`L48`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L48)
- **`--classic`**: Toggle legacy "classic" mode (insecure, secret visible in process list). Source: [`L32`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L32)
- **`--no-compress`**: Disable on-the-fly compression. Source: [`L37`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L37)

### File Handling and Output Options

- **`--out`** (String): Destination folder for received files (default: current directory). Source: [`L52`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L52)
- **`--overwrite`**: Overwrite existing files without prompting. Source: [`L41`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L41)
- **`--rename`**: Rename incoming files that already exist instead of prompting. Source: [`L42`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L42)
- **`--stdout`**: Pipe received file data to STDOUT instead of writing to disk. Source: [`L36`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L36)
- **`--ignore-stdin`**: Do not treat piped STDIN as a file to send. Source: [`L40`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L40)

### Usability and Interface Options

- **`--remember`**: Save supplied options to a local config file for automatic reuse. Source: [`L33`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L33)
- **`--debug`**: Enable verbose debug logging. Source: [`L34`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L34)
- **`--yes`**: Automatically answer yes to all prompts. Source: [`L35`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L35)
- **`--ask`**: Force both sender and receiver to be prompted for confirmation. Source: [`L38`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L38)
- **`--quiet`**: Suppress all non-error output. Source: [`L44`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L44)
- **`--disable-clipboard`**: Prevent croc from copying the command or secret to the clipboard. Source: [`L45`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L45)
- **`--extended-clipboard`**: Copy the full command (including secret as an environment variable) to the clipboard. Source: [`L46`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L46)
- **`--testing`**: Internal flag used by the test suite. Source: [`L43`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L43)

## Command-Specific Configuration Options

### Send Command Options

The `send` subcommand includes additional flags for file preparation and transfer optimization, defined in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) starting at line 71.

- **`--zip`**: Zip a folder before sending. Source: [`L71`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L71)
- **`--code`, `-c`** (String): Manual code phrase (minimum 6 characters). Source: [`L73`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L73)
- **`--hash`** (String): Hash algorithm selection (`xxhash`, `imohash`, `md5`, `highway`). Default: `xxhash`. Source: [`L74`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L74)
- **`--text`, `-t`** (String): Send a literal text string instead of a file. Source: [`L75`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L75)
- **`--no-local`**: Disable the local relay and force use of the remote relay. Source: [`L76`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L76)
- **`--no-multi`**: Disable multiplexing and use a single TCP connection. Source: [`L77`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L77)
- **`--git`**: Respect `.gitignore` and exclude ignored files from the transfer. Source: [`L78`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L78)
- **`--port`** (Int): Base port for the relay (default: `9009`). Source: [`L79`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L79)
- **`--transfers`** (Int): Number of parallel ports to use (default: `4`). Source: [`L80`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L80)
- **`--qrcode`, `-qr`**: Display the web-receive URL as a QR code. Source: [`L81`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L81)
- **`--exclude`** (String): Comma-separated substrings; files containing any match are excluded. Source: [`L82`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L82)
- **`--exclude-file`** (String): Exact relative paths (comma-separated) to exclude. Source: [`L83`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L83)

### Relay Command Options

When running a custom relay with `croc relay`, these flags control the listening interface and port allocation (lines 96-99).

- **`--host`** (String): Hostname or IP address for the custom relay. Source: [`L96`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L96)
- **`--ports`** (String): Comma-separated list of ports (e.g., `9009,9010`). Source: [`L97`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L97)
- **`--port`** (Int): Base port fallback if `--ports` is not specified (default: `9009`). Source: [`L98`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L98)
- **`--transfers`** (Int): Number of ports to open for transfers (default: `5`). Source: [`L99`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L99)

### Serve Command Options

The `serve` subcommand starts an embedded web client with these configuration flags (lines 110-112).

- **`--bind`** (String): Local HTTP bind address (default: `127.0.0.1:9014`). Source: [`L110`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L110)
- **`--relay`** (String): Upstream relay host for the embedded web client. Source: [`L111`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L111)
- **`--ports`** (String): Allowed upstream relay ports (comma-separated). Source: [`L112`](https://github.com/schollz/croc/blob/main/src/cli/cli.go#L112)

## How Configuration Options Are Applied

According to the `schollz/croc` source code, CLI flags are parsed into the `croc.Options` struct defined in [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go). At line 665 of [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go), this struct is instantiated and passed to `croc.New()` to initialize the transfer engine.

When using the **`--remember`** flag, the application invokes the `saveConfig` function at line 267 of [`cli.go`](https://github.com/schollz/croc/blob/main/cli.go), which serializes the current options to a JSON file (typically `~/.config/croc/send.json`). This allows subsequent invocations to automatically reuse saved settings without re-specifying flags.

## Practical Configuration Examples

### Save Custom Relay Settings Permanently

```bash
croc send --relay myrelay.example.com --no-compress --remember file.txt

```

The `--remember` flag writes the configuration to `~/.config/croc/send.json`, automatically applying these options to future `send` commands.

### Send Files with Custom Code Phrase

```bash
export CROC_SECRET=my-secret-code
croc send --zip my_folder/

```

When `--code` is omitted, croc reads the secret from the `CROC_SECRET` environment variable. Add `--classic` if you prefer the legacy behavior with visible process names.

### Run a Private Relay with Multiple Ports

```bash
croc relay --host 0.0.0.0 --ports 9009,9010,9011,9012

```

The relay listens on all specified ports. The first port (`9009`) handles the control channel, while the remaining ports manage data transfers.

### Serve Web Client on Custom Interface

```bash
croc serve --bind 0.0.0.0:8080 --relay myrelay.example.com --ports 9009,9010

```

This configuration exposes the web UI on port 8080 and forwards traffic to the specified upstream relay.

### Disable Clipboard on Headless Servers

```bash
croc receive --disable-clipboard

```

Prevents croc from attempting to access the system clipboard, which is useful for SSH sessions or headless environments.

## Summary

- **Global flags** (24 options) control networking (`--relay`, `--socks5`), security (`--curve`, `--classic`), and file handling (`--overwrite`, `--out`) for all commands, defined in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) lines 31-56.
- **Send-specific flags** include compression control (`--zip`), transfer optimization (`--transfers`, `--no-multi`), and filtering (`--exclude`, `--git`).
- **Relay flags** (`--host`, `--ports`) configure custom relay listeners, while **serve flags** (`--bind`) configure the embedded web client.
- The **`--remember`** flag persists options to JSON via the `saveConfig` function at line 267.
- All flags map to the `croc.Options` struct consumed by `croc.New()` at line 665.

## Frequently Asked Questions

### How do I permanently save croc configuration options?

Use the **`--remember`** flag when sending files. This triggers the `saveConfig` function in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) (line 267) to write current settings to `~/.config/croc/send.json`. Future invocations automatically load these values, though command-line flags always override saved preferences.

### What is the difference between `--ports` and `--port` in relay mode?

The **`--ports`** flag accepts a comma-separated list of specific ports (e.g., `9009,9010`), while **`--port`** sets a single base port used as a fallback when `--ports` is omitted. In `croc relay`, the first port in the list (or the base port) handles control signals, and subsequent ports handle data streams.

### Can I use environment variables instead of CLI flags for proxy settings?

Yes. The **`--socks5`** and **`--connect`** flags automatically fall back to the `SOCKS5_PROXY` and `HTTP_PROXY` environment variables respectively, as implemented in [`src/cli/cli.go`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) lines 54-55. You can also set `CROC_SECRET` to provide a code phrase without using the `--code` flag.

### How do I disable all interactive prompts in automated scripts?

Combine the **`--yes`** flag to auto-accept transfers with **`--overwrite`** or **`--rename`** to handle file conflicts automatically. For headless environments, add **`--disable-clipboard`** to prevent clipboard access errors and **`--quiet`** to suppress output.