Skip to content →

Rewrite Tool

The Rewrite tool enables you to create rules that modify requests and responses as they pass through Charles. Rules such as adding or changing a header or search and replace some text in the response body.

Rewrite Sets

Rewrite sets can be individually activated and deactivated. Each set contains a list of locations and rules. The locations choose the requests and responses on which the rules will operate.

Rewrite Rules

Each rule describes a single rewrite operation. The rule may affect the headers, the body, or parts of the request URL; it may operate on the request and or the response; it may then define search and replace or just replace style rewriting.

Type

The type specifies the type of rewriting operation to perform. There are four different categories of rewrite rule types; header rules, URL rules, query parameter rules, and body rules. The header and query parameter rules affect the header fields and query string parameters respectively; adding, modifying or removing headers and parameters. The URL and body rules perform find and replace on the different parts of the URL and on the body.

Where

Choose where to apply the rewrite rule; on the request, response or both.

Match

The match fields contain the text to match in the request or response to decide whether to fire this rule. You can optionally leave the name or value blank, or both, to match any value. If you leave both the name and value fields blank you will match all requests / responses.

Regex support may be enabled, providing Perl-style regular expressions for your match. If you include groups in your regular expression they may be used in the match fields.

The name field is an exact match field unless regex is enabled, in which case it supports partial matches. The name field is case-insensitive for both regex and normal matching. The name field may be disabled if you are creating a rewrite rule type that doesn't require it.

The value field is a partial match unless you turn on Match whole value in which case it is an exact match. The value field is case-insensitive for both regex and normal matching for header and query parameter rules, and case-sensitive for URL and body rules.

New / Replace

The new/replace fields contain the text to add or replace in the request or response when this rule is fired. Leave either the name or value blank to leave them the same as the matched name or value.

If regex support is enabled for the match you may reference match groups using $1, $2 and so on.

The behaviour of the name and value fields depends upon the match. If there is a corresponding match then the field acts as a replacement for the matched text, otherwise if the match is blank then the fields replaces the whole name or value.

The value field supports Replace First or Replace All modes. The name field always operates in replace-first mode if the name match is a regex, otherwise it is an exact match and replaces the whole name.

The name and or value fields may be disabled if you are creating a rewrite rule type that doesn't require them.

Recommendations

Rewrite rules can be difficult to debug if they are not working as you expect. It is often best to build up a rule slowly with frequent testing.

Location Matching

Each location match may contain protocol, host, port and path patterns to match specific URLs. Locations may include wildcards. More help for creating location matches may be found when you add a new location to this tool.

Debugging

The Rewrite tool can be difficult to debug when your rewrite operation isn't working as expected. If you have trouble try including a very basic rule such as one that adds an obvious header, so you can see whether your rules are matching the request at all. Also turn on Debug in Error Log to get some debugging information printed in the Error Log accessed from the Window menu in Charles.