Charles Proxy automation

Charles Proxy is fantastic a cross-platform HTTP/HTTPS debugging proxy server application, probably the most user friendly of its genre. Its initial setup is painless and it can be configured trough a nice user interface.

I've recently started to use it a lot more than what I was used to at my daily job, so today I've spent some time checking in what way the Charles usage can be automated trough a command-line interface.

Being cross-platform, Charles is compatible with macOS, Linux and Windows. The instructions shown in this post are based on macOS, so if you're planning to follow it on another OS they might need some minor adjustments.

Below I'm just copy-pasting this Gist.

Charles supports a few command line options out of the box, documented here.
Unfortunately they seem to operate only as parameters for new Charles sessions, so you won't be able to run commands on a running instance of Charles.

Start a specific Charles session

A Charles session contains all of your recorded information. It is represented by the Session window; by default a new session is automatically created when you start Charles.
Sessions can be saved from File → Save Session (⌘+S).
Once saved, if you want you can start Charles from the saved session by running:

/Applications/Charles.app/Contents/MacOS/Charles YOUR_SAVED_SESSION_PATH

/Applications/Charles.app/Contents/MacOS/Charles YOUR_SAVED_SESSION_PATH

Start Charles with a specific configuration

This part is not well documented, so I had to dig a bit in the settings to understand how it works.
By default Charles stores its configuration in /Users/YOUR_USER/Library/Preferences/com.xk72.Charles.config, a readable xml file that contains all the Charles settings.
If needed, you can copy this file to another location, tweak the settings your interested into and start Charles directly from it:

/Applications/Charles.app/Contents/MacOS/Charles -config YOUR_CONFIG_PATH

/Applications/Charles.app/Contents/MacOS/Charles -config YOUR_CONFIG_PATH

Please notice that you can manually edit the configuration file only if Charles it not running.

Start Charles with throttling enabled

Easy peasy:

/Applications/Charles.app/Contents/MacOS/Charles -throttling

/Applications/Charles.app/Contents/MacOS/Charles -throttling

Start Charles in headless mode

You can run Charles in headless mode, so that no UI will be presented, but it will still proxy content.

/Applications/Charles.app/Contents/MacOS/Charles -headless

/Applications/Charles.app/Contents/MacOS/Charles -headless

How can you control Charles in headless mode? You can use its Web Interface.

After publishing this post I got in touch with @charlesproxy on Twitter to start a discussion about what we can do to allow editing settings (e.g.: adding new rewrite rules) trough the CLI:

Hmm. Good question. No, but perhaps we could add a reload settings command to the control API?

— Charles Proxy (@charlesproxy) September 6, 2019