docs: argument file and croql string (#917)

Author: katerina20

src/main/java/com/crowdin/cli/commands/picocli/PicocliRunner.java

@@ -58,7 +58,8 @@ private void init() {
             .setExecutionExceptionHandler(executionExceptionHandler)
             .setColorScheme(colorScheme)
             .setCaseInsensitiveEnumValuesAllowed(true)
-            .setExitCodeExceptionMapper(ExitCodeExceptionMapper::getExitCode);
+            .setExitCodeExceptionMapper(ExitCodeExceptionMapper::getExitCode)
+            .setExpandAtFiles(true);
         HelpCommand.setOptions(commandLine, System.out, colorScheme);
     }
 

website/docs/advanced.md

@@ -168,6 +168,39 @@ Example of the configuration:
 ]
 ```
 
+### Argument File
+
+Crowdin CLI supports loading command-line arguments from a file.
+The arguments can be stored in a plain text file and be passed to the CLI using the `@filename` syntax.
+
+This can be useful when:
+- You have a long list of options
+- You want to reuse the same configuration
+- You want to avoid issues with escaping special characters (like quotes) on Windows shells (PowerShell, cmd.exe)
+
+#### How to use
+Create a text file containing the arguments you would normally type in the command line.
+Each argument must be separated by a new line.
+In your CLI command, reference the file using `@` followed by the filename.
+
+Example file (args.txt):
+```
+--branch feat
+--directory src
+```
+
+Run CLI using file:
+
+```bash
+crowdin string list @args.txt
+```
+
+For PowerShell:
+
+```powershell
+crowdin string list "@args.txt"
+```
+
 ### Multilingual Files
 
 For multilingual file formats (containing multiple languages in one file) you can use the `multilingual` option in the configuration. This option allows you to omit the language placeholders in the `translation` pattern:

website/mantemplates/crowdin-string-list.adoc

@@ -15,6 +15,33 @@ include::{includedir}/{command}.adoc[tag=picocli-generated-man-section-options]
 
 include::{includedir}/{command}.adoc[tag=picocli-generated-man-section-footer]
 
+=== Notes
+
+When passing CroQL queries or any argument that includes double quotes ("), correct escaping is required depending on the shell you are using.
+
+If you do not use an link:https://crowdin.github.io/crowdin-cli/advanced#argument-file[argument file], here is how to manually format your command:
+
+- Bash (Linux, macOS, Git Bash)
+Use single quotes ' around the entire query:
+
+```bash
+crowdin string list --croql 'identifier CONTAINS "label"'
+```
+
+- PowerShell
+Escape each double quote " by using escaped backticks `:
+
+```powershell
+crowdin string list --croql "identifier CONTAINS \`"label\`""
+```
+
+- cmd.exe (Command Prompt)
+Escape double quotes by doubling them "":
+
+```cmd
+crowdin string list --croql "identifier CONTAINS ""label"""
+```
+
 === See also
 
 * link:https://developer.crowdin.com/croql/[Crowdin Query Language (CroQL)]