Complete Guide to Croc CLI Options for Configuration

Croc exposes configuration through 24 global flags and command-specific options for send, relay, and serve subcommands, all defined in 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 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, 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
• --relay6 (String): IPv6 relay host address (default: croc6.schollz.com). Source: L51
• --pass (String): Password for the relay (default: empty). Source: L53
• --ip (String): Explicitly set the sender’s IP (e.g., 10.0.0.1:9009). Source: L49
• --local: Restrict transfers to the local network only. Source: L39
• --multicast (String): Multicast address for local discovery (default: 239.255.255.250). Source: L47
• --socks5 (String): SOCKS5 proxy URL (falls back to SOCKS5_PROXY environment variable). Source: L54
• --connect (String): HTTP proxy URL (falls back to HTTP_PROXY environment variable). Source: L55
• --throttleUpload (String): Limit upload bandwidth (e.g., 500k). Source: L56
• --internal-dns: Use the built-in DNS stub resolver instead of the host OS resolver. Source: L31

Security and Encryption Options

• --curve (String): Encryption curve selection (p256, p384, etc.). Defaults to available curves from pake.AvailableCurves(). Source: L48
• --classic: Toggle legacy "classic" mode (insecure, secret visible in process list). Source: L32
• --no-compress: Disable on-the-fly compression. Source: L37

File Handling and Output Options

• --out (String): Destination folder for received files (default: current directory). Source: L52
• --overwrite: Overwrite existing files without prompting. Source: L41
• --rename: Rename incoming files that already exist instead of prompting. Source: L42
• --stdout: Pipe received file data to STDOUT instead of writing to disk. Source: L36
• --ignore-stdin: Do not treat piped STDIN as a file to send. Source: L40

Usability and Interface Options

• --remember: Save supplied options to a local config file for automatic reuse. Source: L33
• --debug: Enable verbose debug logging. Source: L34
• --yes: Automatically answer yes to all prompts. Source: L35
• --ask: Force both sender and receiver to be prompted for confirmation. Source: L38
• --quiet: Suppress all non-error output. Source: L44
• --disable-clipboard: Prevent croc from copying the command or secret to the clipboard. Source: L45
• --extended-clipboard: Copy the full command (including secret as an environment variable) to the clipboard. Source: L46
• --testing: Internal flag used by the test suite. Source: 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 starting at line 71.

• --zip: Zip a folder before sending. Source: L71
• --code, -c (String): Manual code phrase (minimum 6 characters). Source: L73
• --hash (String): Hash algorithm selection (xxhash, imohash, md5, highway). Default: xxhash. Source: L74
• --text, -t (String): Send a literal text string instead of a file. Source: L75
• --no-local: Disable the local relay and force use of the remote relay. Source: L76
• --no-multi: Disable multiplexing and use a single TCP connection. Source: L77
• --git: Respect .gitignore and exclude ignored files from the transfer. Source: L78
• --port (Int): Base port for the relay (default: 9009). Source: L79
• --transfers (Int): Number of parallel ports to use (default: 4). Source: L80
• --qrcode, -qr: Display the web-receive URL as a QR code. Source: L81
• --exclude (String): Comma-separated substrings; files containing any match are excluded. Source: L82
• --exclude-file (String): Exact relative paths (comma-separated) to exclude. Source: 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
• --ports (String): Comma-separated list of ports (e.g., 9009,9010). Source: L97
• --port (Int): Base port fallback if --ports is not specified (default: 9009). Source: L98
• --transfers (Int): Number of ports to open for transfers (default: 5). Source: 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
• --relay (String): Upstream relay host for the embedded web client. Source: L111
• --ports (String): Allowed upstream relay ports (comma-separated). Source: 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. At line 665 of 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, 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

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

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

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

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

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 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 (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 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.

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