Charles fastlane Plugin

This project is a fastlane plugin. To get started with fastlane-plugin-charles, add it to your project by running:

fastlane add_plugin charles

Run Charles Proxy from a fastlane lane, generating its .config file at runtime from a simplified YAML config (see example/charles.yml) that a team can commit and share, instead of hand-editing (and committing) Charles's own exported XML.

Currently macOS only (the default app_path points at the standard macOS Charles install).

registered_name and registered_key are intentionally kept out of charles.yml since they're per-developer secrets, not shared team config — set them via env vars (or a .env file fastlane will load) instead of committing them. They must be provided together.

ip_ranges works as a hybrid: the ip_ranges action option/env var is for ranges that only apply to one developer (e.g. their own machine), while ranges that genuinely apply to the whole team (a shared corporate subnet, or "all" as shorthand for 0.0.0.0/0) belong in charles.yml's access_control.ip_ranges instead — the two lists are merged at runtime. Each entry can be full CIDR notation (10.0.1.20/32) or a bare IP (10.0.1.20), which is treated as /32 (that single host).

See example/.env.example for a template covering these env vars — copy it to .env (which stays gitignored) rather than committing real values.

charles # Use default paths
charles(app_path: "/path/to/Charles.app/Contents/MacOS/Charles")
charles(config_path: "/path/to/charles.yml")
charles(app_path: "/custom/path/to/Charles", config_path: "/custom/path/to/charles.yml")
charles(debug: true)
charles(data_path: "/tmp/charles-data")
charles(headless: true)
charles(throttling: true)

Query the installed Charles Proxy version (runs --version and returns the parsed version string, e.g. "5.2"). Useful for preflight checks before launching the proxy:

charles_version
version = charles_version
UI.user_error!("Charles 5.x required") unless version.start_with?("5.")

Accepts the same app_path / FL_CHARLES_APP_PATH option as charles.

Check out the example Fastfile to see how to use this plugin. Try it by cloning the repo, running fastlane install_plugins and bundle exec fastlane test.

example/charles.yml shows the simplified schema this plugin generates a Charles .config file from at runtime.

charles.yml doesn't yet cover Charles's toolConfiguration tools (Breakpoints, Rewrite, Map Remote, Block List, etc.) — see docs/tool-configuration.md for the per-tool evaluation and why that's deferred to a future release.

The Charles binary also exposes a broader CLI (--headless, convert, filter, ssl, …) beyond the --config launch path this plugin uses today — see docs/charles-cli.md for a snapshot of that surface and an incremental support roadmap.

To run both the tests, and code style validation, run

bundle exec rake

To automatically fix many of the styling issues, use

bundle exec rubocop -a

For any other issues and feedback about this plugin, please submit it to this repository. See CONTRIBUTING.md if you'd like to open a PR, CHANGELOG.md for release history, CODE_OF_CONDUCT.md for community guidelines, and SECURITY.md to report a vulnerability.

If you have trouble using plugins, check out the Plugins Troubleshooting guide.

For more information about how the fastlane plugin system works, check out the Plugins documentation.

fastlane is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out fastlane.tools.