Fiddler CLI

The Fiddler CLI lets you control Fiddler Everywhere from a terminal through the bundled fiddler-cli command. Use it to automate repetitive tasks or to drive Fiddler Everywhere from scripts on your machine. With fiddler-cli, you can:

• Start and stop traffic capturing.
• Show, hide, and query the status of the Fiddler Everywhere application.
• Clear live sessions or export them to a SAZ file.
• Pause matching requests and responses with breakpoints, and resume them.
• Apply temporary URL replacements and host overrides.
• Run custom commands that you implement in a C# script.

All commands use the following syntax:

fiddler-cli [--hidden] <command> [arguments]

The command names follow the Fiddler Classic shorthand syntax—for example, bpu, bpafter, urlreplace, and go. For the full list of commands, see the Fiddler CLI Command Reference.

To start using the Fiddler CLI, complete the following steps:

1. Enable the Fiddler CLI in the Fiddler Everywhere settings. The CLI is disabled by default.
2. Set up the CLI path for your operating system, so that your terminal can find the fiddler-cli command.
3. Run a command.

Prerequisites

To use the Fiddler CLI, you need:

• Fiddler Everywhere installed on Windows, macOS, or Linux (AppImage). The CLI is bundled with the application and is self-contained, so you don't need to install a separate .NET runtime.
• A Fiddler Everywhere Pro or Enterprise subscription tier.
• A signed-in Fiddler account with a valid license for most commands. For details, see Restrictions.

Enabling the Fiddler CLI

The Fiddler CLI is disabled by default. To enable it:

1. In Fiddler Everywhere, open Settings > Connections.
2. Select the Enable Fiddler CLI checkbox.
3. Click Save.

The option controls only whether Fiddler Everywhere accepts commands from fiddler-cli. It doesn't install the command and doesn't change your PATH. Fiddler Everywhere never modifies the PATH environment variable for you—you set it up yourself, as described in the next section.

When the option is disabled, running any fiddler-cli command prints Fiddler CLI is currently disabled. and returns exit code 1. The CLI does not start Fiddler Everywhere.

The checkbox is unavailable when your subscription tier doesn't include the Fiddler CLI or when your administrator has disabled the CLI through the DisableCLI policy.

Setting Up the CLI Path

Fiddler Everywhere doesn't register the fiddler-cli command on your PATH during installation. To run the command, use one of the following approaches:

• Run the executable by its full path—Works immediately and requires no configuration.
• Add the executable's folder to the PATH environment variable—Lets you run fiddler-cli from any terminal and any folder.

Copying the CLI Path

Fiddler Everywhere shows the location of the CLI in the settings. On Windows and macOS, the field is named CLI Directory and contains the folder of the executable. On Linux, the field is named CLI Executable and contains the full path to the executable.

1. Open Settings > Connections.
2. Find the CLI Directory (Windows and macOS) or CLI Executable (Linux) field below the Enable Fiddler CLI checkbox.
3. Click the copy button next to the field. Fiddler Everywhere confirms with the CLI Path Copied! message.

The copied value is the folder that contains fiddler-cli on Windows and macOS, and the full path to the executable on Linux. The location depends on your operating system and installation:

Always use the path shown in the CLI Directory field of your installation. The folder differs between per-user and per-machine installations on Windows and if you install the app in a custom location.

Windows

Open PowerShell or Command Prompt and use one of the following options.

The examples use the LOCALAPPDATA environment variable (%LOCALAPPDATA% in Command Prompt and $env:LOCALAPPDATA in PowerShell), which points to C:\Users\<user>\AppData\Local and matches the default per-user installation folder. Don't use %APPDATA%—it points to the Roaming folder, which is a different location. If you installed Fiddler Everywhere per machine or in a custom folder, replace the variable-based part of the path with the folder from the CLI Directory field.

Option 1: Run the executable by its full path

Paste the copied folder, append \fiddler-cli.exe, and add the command. In PowerShell, put the path in quotes and prefix it with the call operator (&) because it contains spaces:

# Windows PowerShell
& "$env:LOCALAPPDATA\Programs\Fiddler Everywhere\resources\app.asar.unpacked\out\cli\fiddler-cli.exe" help

:: Command Prompt
"%LOCALAPPDATA%\Programs\Fiddler Everywhere\resources\app.asar.unpacked\out\cli\fiddler-cli.exe" help

Option 2: Add the folder to PATH for the current terminal session only

The change is lost when you close the terminal:

# Windows PowerShell
$env:Path += ";$env:LOCALAPPDATA\Programs\Fiddler Everywhere\resources\app.asar.unpacked\out\cli"
fiddler-cli help

:: Command Prompt
set "PATH=%PATH%;%LOCALAPPDATA%\Programs\Fiddler Everywhere\resources\app.asar.unpacked\out\cli"
fiddler-cli help

Option 3: Add the folder to the user PATH permanently

Use the Windows settings:

1. Press the Windows key, type environment variables, and select Edit environment variables for your account.
2. In the User variables list, select Path and click Edit.
3. Click New and paste the folder that contains fiddler-cli.exe. Don't include fiddler-cli.exe in the value.
4. Click OK in all dialogs.
5. Open a new terminal window. Terminals that were already open don't see the change.

Alternatively, run the following command in PowerShell. Replace the folder with the one for your installation:

# Windows PowerShell
$cliFolder = "$env:LOCALAPPDATA\Programs\Fiddler Everywhere\resources\app.asar.unpacked\out\cli"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if (($userPath -split ";") -notcontains $cliFolder) {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$cliFolder", "User")
}

Open a new terminal window and verify the setup:

where.exe fiddler-cli
fiddler-cli help

Avoid the setx PATH ... command. It truncates values longer than 1024 characters and can damage your existing PATH.

macOS

Open Terminal and use one of the following options.

Option 1: Run the executable by its full path

Paste the copied folder, append /fiddler-cli, and add the command. Wrap the path in quotes because it contains a space:

"/Applications/Fiddler Everywhere.app/Contents/Resources/app.asar.unpacked/out/cli/fiddler-cli" help

Option 2: Create a symbolic link in /usr/local/bin

The /usr/local/bin folder is usually already part of your PATH, so a symbolic link makes the command available in every terminal:

sudo mkdir -p /usr/local/bin
sudo ln -sf "/Applications/Fiddler Everywhere.app/Contents/Resources/app.asar.unpacked/out/cli/fiddler-cli" /usr/local/bin/fiddler-cli

Enter your administrator password when prompted. Open a new terminal window and verify the setup:

which fiddler-cli
fiddler-cli help

Option 3: Add the folder to PATH in your shell profile

Add the folder that contains fiddler-cli to your shell profile. Current macOS versions use zsh by default, so the profile is ~/.zshrc. If you use bash, use ~/.bash_profile instead.

echo 'export PATH="$PATH:/Applications/Fiddler Everywhere.app/Contents/Resources/app.asar.unpacked/out/cli"' >> ~/.zshrc
source ~/.zshrc

Verify the setup:

which fiddler-cli
fiddler-cli help

If you moved the application out of the /Applications folder, replace the folder in the commands with the one from the CLI Directory field.

Linux

Fiddler Everywhere for Linux is distributed as an AppImage. An AppImage is mounted to a temporary folder while the application is running, so the CLI Executable path is temporary—it is valid only while Fiddler Everywhere is running and typically changes with each start.

Because of that, use the full path of the running instance instead of adding a folder to the PATH permanently:

1. Start Fiddler Everywhere.

2. Open Settings > Connections and click the copy button next to the CLI Executable field.

3. In a terminal, run the command with the copied path:

   sh

   "<copied path>" help

   For example, with the path pasted between quotes:

   sh

   "/tmp/.mount_Fiddle1a2b3c/resources/app.asar.unpacked/out/cli/fiddler-cli" status

To use the shorter fiddler-cli command during the current Fiddler Everywhere session, create a temporary symbolic link or an alias to the copied path:

# Symbolic link in ~/.local/bin (make sure the folder is part of your PATH)
mkdir -p ~/.local/bin
ln -sf "<copied path>" ~/.local/bin/fiddler-cli

# Or, an alias for the current terminal session only
alias fiddler-cli='"<copied path>"'

Repeat these steps after you restart Fiddler Everywhere, because the copied path changes. If ~/.local/bin is not part of your PATH, add it to your shell profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

On Linux, start Fiddler Everywhere before you run fiddler-cli commands. The CLI executable is not available while the AppImage is not running, so the CLI cannot start the application for you.

Running Commands

When you run a fiddler-cli command, the CLI looks for a running Fiddler Everywhere instance for the current user:

• If Fiddler Everywhere is running, the CLI sends the command to it and prints the result.
• If Fiddler Everywhere is not running (Windows and macOS), the CLI starts it, waits until the application is ready, and then runs the command. This applies to every command, including help and invalid commands.

The CLI waits up to 30 seconds for Fiddler Everywhere to start and become ready. If the application is still starting (for example, while it restores your sign-in state), the CLI retries the command automatically during that time.

Starting Fiddler Everywhere in the Background

Add the --hidden option to start Fiddler Everywhere without showing the splash screen and the main window. This is useful for automation scenarios where you don't need the UI.

fiddler-cli --hidden start

The --hidden option affects only the application startup. If Fiddler Everywhere is already running, the option has no effect. To show the window later, run fiddler-cli show.

Getting Help

To list the available commands, run any of the following:

fiddler-cli help
fiddler-cli --help
fiddler-cli -h
fiddler-cli

Quoting Arguments

Arguments are positional. Quote values that contain spaces or characters that your shell interprets, such as &, ?, or |:

# Windows PowerShell
fiddler-cli bpu "example.com/api?debug=true"

# macOS and Linux
fiddler-cli bpu 'example.com/api?debug=true'

Examples

The following examples show common tasks. For all commands, see the Fiddler CLI Command Reference.

Check the state of Fiddler Everywhere

fiddler-cli status

userSignedIn: True
proxyEnabled: False
scriptingEnabled: False

Start capturing, do your work, and stop capturing

fiddler-cli start
fiddler-cli stop

Start Fiddler Everywhere in the background and capture

fiddler-cli --hidden start

Pause requests to a specific URL, inspect them in Fiddler Everywhere, and resume

fiddler-cli bpu example.com/api
fiddler-cli go
fiddler-cli bpu

The last command clears the breakpoint.

Redirect a host to a local server temporarily

fiddler-cli overridehost example.com localhost:5000
fiddler-cli overridehost

The last command clears the host override.

Export the captured sessions to a SAZ file

# Windows PowerShell
fiddler-cli dump C:\captures

# macOS and Linux
fiddler-cli dump ~/captures

Use the exit code in a script

fiddler-cli start && echo "Capturing started"

If you didn't add the CLI folder to your PATH, replace fiddler-cli in the examples with the full path to the executable. See Setting Up the CLI Path.

Restrictions

The following restrictions apply to Fiddler CLI commands:

• Enabled setting—The Enable Fiddler CLI option must be turned on. It is off by default.
• Sign-in and license—All commands except help, status, show, and hide require a signed-in Fiddler account with a valid license. Otherwise, the CLI reports the sign_in_required or license_required error. When sign-in is required, the CLI output includes a link that opens the sign-in page.
• Subscription tier—The Fiddler CLI is available for the Pro and Enterprise subscription tiers. If your account's plan doesn't include the CLI, commands fail with the policy_blocked error.
• Enterprise policy—Administrators can disable the CLI through the DisableCLI managed app configuration key. When the policy is active, commands fail with the policy_blocked error.
• Custom commands—Commands implemented in a script run only when scripting is enabled and the script that handles them is active. For details, see Custom CLI Commands.

Output and Exit Codes

The CLI prints successful results to the standard output and errors to the standard error. Control characters in the output are escaped (for example, as \u{1b}), so command output cannot change the state of your terminal.

An error message can include the following additional lines:

• Suggested action:—Describes how to resolve the problem.
• You can follow the quick link:—A link that opens the relevant page, such as the sign-in page or the Scripting settings.
• errorCode:—A machine-readable error code.

For example:

Sign-in is required before this Fiddler CLI command can run.
Suggested action: Open Fiddler Everywhere, sign in, and run the command again.
You can follow the quick link: https://...
errorCode: sign_in_required

The CLI returns one of the following exit codes:

Use the exit code to check the result in scripts. For example:

# Windows PowerShell
fiddler-cli start
if ($LASTEXITCODE -ne 0) { Write-Error "Could not start capturing." }

# macOS and Linux
if ! fiddler-cli start; then
  echo "Could not start capturing." >&2
fi

Troubleshooting

The Command Is Not Found

If your terminal reports that it doesn't recognize the command, the folder of the CLI executable is not on your PATH:

• Windows PowerShell: fiddler-cli : The term 'fiddler-cli' is not recognized as the name of a cmdlet, function, script file, or operable program.
• Command Prompt: 'fiddler-cli' is not recognized as an internal or external command, operable program or batch file.
• macOS and Linux: fiddler-cli: command not found

To resolve the problem, set up the CLI path as described in Setting Up the CLI Path, and open a new terminal window after changing the PATH.

The CLI Is Disabled

The Fiddler CLI is currently disabled. message means that the Enable Fiddler CLI option is off. Enable it in Settings > Connections and click Save.

Error Codes

When a command fails, the CLI prints an error message and an errorCode value. The following table describes the error codes and how to resolve them.

The following message is related to the CLI configuration:

• Could not find Fiddler Everywhere at '...'. Start or reinstall Fiddler Everywhere.—The CLI cannot locate the application. Start Fiddler Everywhere manually, or reinstall it if the application files are missing.
• Could not find appPath in ~/.fiddler/cli-config.json. Start Fiddler Everywhere to refresh it.—(Linux only) The CLI configuration is missing or incomplete. Start Fiddler Everywhere manually once.

See Also

• Fiddler CLI Command Reference
• Custom CLI Commands
• Connections Settings
• Scripting Overview
• Managed App Configuration