Run
Runs a script on files and streams the LLM output to stdout or a folder from the workspace root.
npx genaiscript run <script> "<files...>"
where <script>
is the id or file path of the tool to run, and <files...>
is the name of the spec file to run it on.
Files can also include glob pattern.
npx genaiscript run code-annotator "src/*.ts"
If multiple files are specified, all files are included in env.files
.
npx genaiscript run <script> "src/*.bicep" "src/*.ts"
Files
run
takes one or more glob patterns to match files in the workspace.
npx genaiscript run <script> "**/*.md" "**/*.ts"
—excluded-files <files…>
Excludes the specified files from the file set.
npx genaiscript run <script> <files> --excluded-files <excluded-files...>
—exclude-git-ignore
Exclude files ignored by the .gitignore
file at the workspace root.
npx genaiscript run <script> <files> --exclude-git-ignore
Configuration
—model …
Configure the default or large
model alias
—provider …
Loads a set of model aliases for the given LLM provider.
—vars name=value name2=value2 …
Populate values in the env.vars
map that can be used when running the prompt.
Output
—out <file|directory>
Saves the results in a JSON file, along with markdown files of the output and the trace.
npx genaiscript run <script> <files> --out out/res.json
If file
does not end with .json
, the path is treated as a directory path.
npx genaiscript run <script> <files> --out tmp
—json
Output the entire response as JSON to the stdout.
—yaml
Output the entire response as YAML to the stdout.
—out-trace <file>
Save the markdown trace to the specified file.
npx genaiscript run <script> <files> --out-trace <file>
In a GitHub Actions workflow, you can use this feature to save the trace as a step summary (GITHUB_STEP_SUMMARY
):
- name: Run GenAIScript tool on spec run: | genaiscript run <script> <files> --out-trace $GITHUB_STEP_SUMMARY
In Azure Dev Ops, you can use the task.uploadSummary in your pipeline to upload the trace as a summary.
- script: npx --yes genaiscript run poem --out-trace $(System.DefaultWorkingDirectory)/trace.md displayName: "Run GenAIScript tool" continueOnError: true- script: echo "##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/trace.md" displayName: "append readme to pipeline report"
—out-annotations <file>
Emit annotations in the specified file as a JSON array, JSON Lines, SARIF or a CSV file if the file ends with .csv
.
npx genaiscript run <script> <files> --out-annotations diags.csv
Use JSON lines (.jsonl
) to aggregate annotations from multiple runs in a single file.
npx genaiscript run <script> <files> --out-annotations diags.jsonl
—out-data <file>
Emits parsed data as JSON, YAML or JSONL. If a JSON schema is specified and availabe, the JSON validation result is also stored.
npx genaiscript run <script> <files> --out-data data.jsonl
—out-changelogs <file>
Emit changelogs in the specified file as text.
npx genaiscript run <script> <files> --out-changelogs changelogs.txt
Pull Requests and Issues
The CLI can update a pull request/issue description and comments when running in a GitHub Action or Azure DevOps pipeline.
GitHub Action workflow configuration
Update your workflow configuration to include the following:
- add the
pull-requests: write
permission to the workflow/step
permissions: pull-requests: write
- set the
GITHUB_TOKEN
secret in theenv
when running the cli
- run: npx --yes genaiscript run ... -prc --out-trace $GITHUB_STEP_SUMMARY env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ... # LLM secrets
Azure DevOps configuration
- add
<your projectname> Build Service
in the Collaborator role to the repository - pass secrets to scripts, including
System.AccessToken
- script: npx genaiscript run ... -prd env: SYSTEM_ACCESSTOKEN: $(System.AccessToken) ... # LLM secrets
—pull-request-description [tag]
When running within a GitHub Action or Azure DevOps pipeline on a pull request, the CLI inserts the LLM output in the description of the pull request (example)
npx genaiscript run ... -prd
The tag
parameter is a unique id used to differentiate description generate by different runs. Default is the script id.
—pull-request-comment [tag];
Upserts a comment on the pull request/issue with the LLM output (example)
npx genaiscript run ... -prc
The tag
parameter is a unique id used to differentiate description generate by different runs. Default is the script id.
—pull-request-reviews
Create pull request review comments from each annotations (example).
npx genaiscript run ... -prr
Read more
The full list of options is available in the CLI reference.