PowerGREP can be fully controlled from the command line. This allows you to use PowerGREP from batch files or scripts and to add PowerGREP as an external tool to other applications. Check out the command line examples to give you an idea of the possibilities.
All parameters are optional. You can use as many or as few of them as you want. If a parameter requires a value as a second parameter then the second parameter must follow right after the first one. There must be a space between the parameter and the value. Values are indicated between angle brackets in the list below. Remember that if a value contains spaces then you must put double quotes around it (e.g.: "search text") to make sure the value is interpreted as a single parameter. For some parameters, the number of values is variable. Make sure to specify the correct number of values. If you want to leave a required value blank then specify two double quotes. /replacetext "" specifies a blank replacement text, for example.
You can specify any number of files of the command line, but only one file of each kind. You can specify one file selection file, one action file, one sequence file, one results file, one library file and one undo history file. The file will be loaded into the corresponding panel. In addition, you can specify one file of any other kind. That file will be opened in the built-in file editor.
File selections are saved in file selection files, action files and results files. If you specify two or all three of these files on the command line then PowerGREP uses the file selection from the file selection file, or from the action file if you didn’t specify a file selection file. Only when you don’t specify either a file selection file or an action file does PowerGREP read the file selection from the results file.
In similar vein, action definitions are saved in both action files and results files. If you specify both an action file and results file on the command line then PowerGREP reads the action definition from the action file.
If you specify both an action and a sequence file then both are loaded into their respective panels. But the parameters for previewing and executing will execute only the sequence.
If you specify both files to be opened and parameters that changes settings also stored in the file, then it matters whether you place those parameters before or after the file on the command line. If you place parameters after a file then the file is loaded as described above. The parameters then override the settings in the file. In most cases, this is what you want. Load all settings from a file and then use command line parameters to override certain settings.
If you place parameters that affect the file selection before a file selection file then those parameters are ignored. If you place parameters that affect the file selection before an action file or a results file then PowerGREP does not load the file selection from the action file or results file. Only the parameters are then used.
If you place parameters that affect the action before an action file then those parameters are ignored. If you place parameters that affect the action before a results file then PowerGREP does not load the action from results file. Only the parameters are then used. If you place action parameters after a file then the file is loaded as described above. The parameters then override the settings in the file.
Use the command line parameters below to change basic settings in the file selection and action definition. Not all settings you can make in PowerGREP’s user interface can be made via the command line. To control the additional settings, first save a file selection file and/or action file in the user interface. Then pass that file on the command line, before any of the options listed below.
1. /simple sets the action type to “simple search”.
2. /search sets the action type to “search”.
3. /collect sets the action type to “collect data”.
4. /count sets the action type to “count matches”.
5. /find sets the action type to “list files”. This action type was known as “find files” in PowerGREP 3, hence the name of the command line parameter.
6. /findname sets the action type to “file or folder name search”.
7. /collectname sets the action type to “file or folder name collect”.
8. /rename sets the action type to “rename files or folders”.
9. /replace sets the action type to “search and replace”.
10. /delete sets the action type to “search and delete”.
11. /merge sets the action type to “merge files”.
12. /split sets the action type to “split files”.
13. /searchtext <text> sets the search term(s) of the main part of the action to “text”. If you have more than one search term, use one /searchtext parameter in combination with /delimitsearch.
14. /replacetext <text> sets the replacement text or text to be collected to “text”.
15. /searchbytes <bytes> sets the search term of the main part of the action. The <bytes> value must be a string of hexadecimal bytes. Changes the search type to binary data.
16. /replacebytes <bytes> sets the replacement bytes or bytes to be collected. The <bytes> value must be a string of hexadecimal bytes. Changes the search type to binary data.
17. /searchtextfile <file path> <charset> loads the search term(s) for the main part of the action from a file. If the file contains more than one search term, use /delimitsearch to specify the delimiter. If the file also contains the replacement text, use /delimitreplace to specify the delimiter.
You can specify an additional value after the file name to indicate the character set or text encoding used by the file you’re reading the search terms from. You can use the same identifiers used by XML files and HTML files to specify character sets, such as utf-8, utf-16le, or windows-1252. You can omit this parameter if the file starts with a Unicode signature (BOM). The default is your computer’s default Windows code page.
18. /searchbytesfile <file path> loads the search term(s) for the main part of the action from a file. The file should contain the actual bytes you want to search for (unlike the /searchbytes parameter which expects the hexadecimal representation of the bytes). Changes the search type to binary data. If the file contains more than one search term, use /delimitsearch to specify the delimiter. If the file also contains the replacement bytes, use /delimitreplace to specify the delimiter.
19. /regex sets the search type to a regular expression.
20. /literal sets the search type to literal text.
21. /delimitprefix <delimiter> sets the search prefix label delimiter to “delimiter”. Also sets the search type to a delimited list.
22. /delimitsearch <delimiter> sets the search item delimiter to “delimiter”. Also sets the search type to a delimited list.
23. /delimitreplace <delimiter> sets the search pair delimiter to “delimiter”. Also sets the search type to a delimited list.
24. /optnonoverlap <0|1> Sets the option “non-overlapping search”. Only has an effect when the search type is a delimited list.
25. /optdotall <0|1> Sets the option “dot matches newlines”. Only has an effect when the search type is a regular expression.
26. /optwords <0|1> Sets the option “whole words only”. Does not have any effect when the search type is a regular expression.
27. /optcase <0|1> Sets the option “case sensitive”.
28. /optadaptive <0|1> Sets the option “adaptive case”.
29. /optinvert <0|1> Sets the option “invert results”. Only has an effect when the action type is “list files”, or when you load an action definition that sections files.
30. /context <none|section|line> Sets the “context type” to “no context”, “use sections as context”, or “use lines as context”. Context is only used to display results on the Results panel in PowerGREP or when saving results using the /save parameter.
31. /contextextra <context|lines> <before> <after> Tells PowerGREP how many blocks of context or how many lines of context to show before and after each match, in addition to the block of context that contains the match. E.g. /contextextra lines 2 3 shows 2 lines before and 3 lines after. If you omit the “context” or “lines” parameter after /contextextra, then “context” is implied when using sections as context, and “lines” is implied when using lines as context. Both the before and after numbers are required. This parameter is ignored when using /context none.
32. /target <type> <destination> <location> Sets the target options on the Action panel. This parameter must be followed by one value with of the target types listed below. If the target type is something other than “same”, “none”, or “replacement”, then that value needs to be followed by two more values.
The first value indicates how files are copied. When copying files, the original file will remain untouched. The available values depends on the action type. Values with spaces need to be kept together with double quotes.
| same | Do not copy files but change the file searched through. Do not specify any destination type or location. (search; collect data; search-and-replace; search-and-delete) |
| "copy modified" | Copy files in which matches have been found. (search; collect data; list files; rename files; search-and-replace; search-and-delete) |
| "copy all" | Copy all files searched through. (search-and-replace; search-and-delete) |
| none | Do not save results. Do not specify any destination type or location. (list files; simple search; search; collect data; list files) |
| single | Save results to single file. (search; collect data; list files; merge files) |
| clipboard | Copy the results to the clipboard. (search; collect data; list files; merge files) |
| editor | Store the results as an unsaved file on the Editor panel. (search; collect data; list files; merge files) |
| move | Move matching files (list files; rename files) |
| "copy recurse" | Copy the contents of matching folders (list folders; rename folders) |
| "move recurse" | Move the contents of matching folders (list folders; rename folders) |
| convert | Convert matched files to text. Do not specify any destination type or location. (list files) |
| "convert copy" | Convert copies of matched files to text. (list files) |
| delete | Delete matching files. Do not specify any destination type or location. (list files) |
| replacement | Use replacement text as target (merge files; split files) |
| placeholders | Use path placeholders. Do not specify any destination type or location. The second value must also be “placeholders” and the third value must be the path using path placeholders. (search; collect data; merge files) |
The second value indicates the destination type for copied files:
| "single folder" | Place all target files into a single folder. |
| "folder tree" | Place target files into a folder tree. |
| archive | Place target files into an archive. |
| "numbered archive" | Place target files into a numbered archive. |
| placeholders | Use path placeholders |
The third value indicates the actual location. It must specify the full path to a folder, a file, an archive or use path placeholders, depending on the destination type in the second parameter.
33. /backup <type> <destination> <location> Sets the backup options on the Action panel. This parameter must be followed by one value with of the backup types listed below. If the backup type is something other than “none” or “history”, then that value needs to be followed by two more values.
The first value indicates the type of backup to create. Values with spaces need to be kept together with double quotes.
| none | Do not create backup files. Do not specify any destination type or location. |
| "single bak" | Single backup appending .bak extension |
| "single tilde" | Single backup with .~* extension |
| "multi bak" | Multi backup appending .bak, .bak2, ... extensions |
| "multi name" | Multi backup prepending “Backup X of ...” |
| same | Backup with same file name as original file (destination cannot be the same folder) |
| placeholders | Use path placeholders. The second parameter must be specified but its value is ignored. The third parameter must specify the path using path placeholders. |
| history | Hidden __history folder. Do not specify any destination type or location. |
The second value indicates the destination type of the backup files:
| "same folder" | Same folder as original. Do not specify a location. |
| subfolder | Place all backup files into a specific subfolder of the folders holding the original files. Specify the name of a subfolder as the location. |
| "single folder" | Place all backup files into a single folder. Specify the full path to a folder as the location. |
| "folder tree" | Place backup files into a folder tree. Specify the full path to a folder as the location. |
| archive | Place backup files into an archive. Specify the full path to an archive file as the location. |
| "numbered archive" | Place backup files into a numbered archive. Specify the full path to an archive file as the location. |
The third value indicates the actual location, either a folder, archive file or a path using path placeholders.
34. /folder <folders> The value must be a comma-delimited or semicolon-delimited list of full paths to folders. Includes those folders, but not their subfolders, in the next action.
35. /folderrecurse <folders> The value must be a comma-delimited or semicolon-delimited list of full paths to folders. Includes those folders and their subfolders in the next action.
36. /folderexclude <folders> The value must be a comma-delimited or semicolon-delimited list of full paths to folders. Excludes those folders from the next action. Subfolders are also excluded, unless they’re explicitly included.
37. /file <files> The value must be a comma-delimited or semicolon-delimited list of full paths to files. Includes those files in the next action.
38. /fileexclude <files> The value must be a comma-delimited or semicolon-delimited list of full paths to files. Excludes those files from the next action.
39. /masks <include files> <exclude files> <include folders> <exclude folders> <0|1> Sets the file masks. The first two values are the inclusion and exclusion masks for files. The third and fourth value are the inclusion and exclusion masks for folders. The fifth value indicates whether the masks are traditional file masks (0) or regular expressions (1).
40. /configconvert <configuration name> Sets “file formats to convert to plain text” to the configuration with the given name. This configuration should have been previously defined in the File Selector section in the Preferences. Passing the empty string "" as the configuration name is the same as passing “(unused)”, which is not the same as passing “None”.
41. /configarchives <configuration name> Sets “archive formats to search inside” to the configuration with the given name. This configuration should have been previously defined in the File Selector section in the Preferences. Passing the empty string "" as the configuration name is the same as passing “(unused)”, which is not the same as passing “None”.
42. /configencoding <configuration name> Sets “text encodings to read files with” to the configuration with the given name. This configuration should have been previously defined in the File Selector section in the Preferences. Passing the empty string "" as the configuration name is the same as passing “(unused)”.
43. /confighide <configuration name> Sets “hide files and folders” to the configuration with the given name. This configuration should have been previously defined in the File Selector section in the Preferences. Passing the empty string "" as the configuration name is the same as passing “(unused)”.
44. /optbinary <0|1> Sets the option “search through binary files”.
45. /resultsoptions <display> <group> <totals> <sortfiles> <sortmatches> <replacements> Sets the options to be used on the Results panel for displaying the search results, or saving them into a text file with the /save parameter. You always need to specify six values, one for each of the six drop-down lists on the Results panel.
| none | Do not show files or matches |
| file | File names only |
| "file target" | Matches without context |
| match | Matches with section numbers |
| "match number" | Matches with context numbers |
| "match context" | Matches with context |
| "match context number" | Matches with context and context numbers |
| "align match context" | Aligned matches with context |
| "align match context number" | Aligned matches with context and context numbers |
| none | Do not group matches |
| file | Per file |
| "file void" | Per file, with or without matches |
| "file match" | Per file, then per unique match |
| "file match void" | Per file, per match, with or without matches |
| match | Per unique match |
| "match file" | Per unique match, listing files |
| none | Do not show totals |
| header | Show totals with the file header (or before the results if no header). |
| before | Show totals before the results |
| after | Show totals after the results |
| "before after" | Show totals before and after the results. |
| group | Show totals for grouped matches. |
| "header group" | Totals with the file header, and grouped matches. |
| "before group" | Totals before results, and grouped matches. |
| "after group" | Totals after results, and grouped matches. |
| "before after group" | Totals before and after the results, and grouped matches. |
| none | First searched to last searched |
| reverse | Last searched to first searched |
| "alnum inc" | Alphanumerically, A..Z, 0..9 |
| "alnum dec" | Alphanumerically, Z..A, 0..9 |
| "total inc" | By increasing totals |
| "total dec" | By decreasing totals |
| "new old" | Newest to oldest |
| "old new" | Oldest to newest |
| none | Show in original order |
| "alpha inc" | Alphabetically, A..Z |
| "alpha dec" | Alphabetically, Z..A |
| "alnum inc" | Alphanumerically, A..Z, 0..9 |
| "alnum dec" | Alphanumerically, Z..A, 0..9 |
| "total inc" | By increasing totals |
| "total dec" | By decreasing totals |
| match | Search match only |
| replace | Replacement only |
| inline | In-line match and replacement |
| separate | Separate match and replacement |
46. /save <filename> <charset> If the extension is .pgr or .pgsr, the results created by the /preview, /execute or /quick parameter will be saved into a PowerGREP results file or a PowerGREP sequence results file. If you specify any other extension, PowerGREP will export the results as a plain text file or HTML that can be read by other software. The /save parameter will be ignored if you did not specify /preview, /execute or /quick. The file will be overwritten without warning if it already exists.
If the extension is not .pgr or .pgsr, you can specify an additional value after the file name to determine the character set or text encoding to be used for the text file. You can use the same identifiers used by XML files and HTML files to specify character sets, such as utf-8, utf-16le, or windows-1252. If you omit this parameter, your computer’s default Windows code page is used.
47. /preview Preview the action. If you passed a PowerGREP sequence action file on the command line then this parameter previews the whole sequence.
48. /execute Execute the action. If you passed a PowerGREP sequence action file on the command line then this parameter executes the whole sequence.
49. /quick Quick execute the action. If you passed a PowerGREP sequence action file on the command line then this parameter quick executes the whole sequence.
50. /quit This parameter causes PowerGREP to terminate after successfully executing an action. This parameter is only used if you specify /preview and /save, or /execute, or /quick. This parameter is implied if you specify /silent. This parameter is ignored if you specify /reuse and a running instance was actually reused.
51. /reuse Tells PowerGREP to pass the command line parameters to a PowerGREP instance that is already running if that instance is not already executing an action. If there are multiple PowerGREP instances running that are not executing an action, one of those instances is chosen at random. If there are no idle PowerGREP instances then a new instance is started as if you had not specified /reuse. This parameter is ignored if you specify /silent.
If there are errors in your command line then the /reuse parameter only takes effect if it appears before the error on the command line. Specify /reuse as the first parameter if you want to make sure that errors in the command line are displayed by a running instance rather than by a new instance.
52. /silent Quick execute the action or sequence without showing PowerGREP at all. No indication is given that PowerGREP is running. If you want /save to save detailed results with individual search matches, pass /execute along with /silent to execute the action silently instead of quick executing the action silently.
If there are errors in your command line or in the files it references then a message box is displayed to indicate the error, even when using /silent. If the /silent parameter appears on the command before the invalid parameter, then the message box is all that is displayed. If the /silent parameter appears on the command line after the invalid parameter, then the /silent parameter is ignored and a new PowerGREP instance is started. Specify /silent as the first parameter to make sure no new PowerGREP instance is started.
53. /noundo Tells PowerGREP not to add the action to the undo history. This means you will not be able to undo the action or delete any backup files that it created. This parameter is ignored unless you use /silent. /noundo is implied for actions that do not create backup files (either because they don’t save any files or because you chose not to create backups). You should only use /noundo when using PowerGREP as part of an automated process and your automated process already deals with the backup files that PowerGREP creates.
54. /noundomanager Tells PowerGREP to add the action directly to the undo history, without using the undo manager. This parameter is ignored unless you use /silent. You have to specify the path to a .pgu file to save the undo history when using /noundomanager. If the .pgu file does not exist it will be created. If it does exist the action is added to the .pgu file. The difference between using and not using the undo manager is that the undo manager allows multiple PowerGREP instances to share the same undo history. You should not use /noundomanager unless you can be 100% sure no other PowerGREP instance is using the same .pgu file in any way.
55. /nocache can be used in combination with /silent to temporarily disable the conversion cache. Files in proprietary formats will be converted even if they were cached before. The conversions will not be added to the cache. The conversion manager will not be used at all. Use this option if the action you’re executing silently searches through files that you normally don’t search through. That way PowerGREP doesn’t needlessly take up disk space to cache the plain text conversions of these files. It also prevents PowerGREP from flushing files that you do regularly work with from the cache when the cache reaches its maximum size.