Run

Runs a script on files and streams the LLM output to stdout or a folder from the workspace root.

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.

genaiscript run code-annotator "src/*.ts"

If multiple files are specified, all files are included in env.files.

genaiscript run <script> "src/*.bicep" "src/*.ts"

Files

run takes one or more glob patterns to match files in the workspace.

genaiscript run <script> "**/*.md" "**/*.ts"

Resource resolutions

GenAIScript will automatically handle and resolve specific URI patterns.

• file:// - local file
• https://github.com/<owner>/<repo>/blob/<branch>/<path> - GitHub file
• https://github.com/<owner>/<repo>.git/<file glob> - GitHub repository and file glob
• gist://id/<file glob> - GitHub Gist and file glob
• https://gist.github.com/<owner>/<id>/<file glob> - GitHub Gist and file glob
• git://<owner>/<repo>.git/<file glob> - Git repository and file glob

Piping

run takes the stdin content and converts it into the stdin file. The LLM output is sent to stdout, while the rest of the logging is sent to stderr.

cat README.md | genaiscript run summarize > summary.md

--excluded-files files…

Excludes the specified files from the file set.

genaiscript run <script> <files> --excluded-files <excluded-files...>

--exclude-git-ignore

Exclude files ignored by the .gitignore file at the workspace root.

genaiscript run <script> <files> --exclude-git-ignore

Configuration

--model …

Configure the default or large model alias. Use echo to do a dry run and return the messages instead of calling a LLM provider.

--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.

genaiscript run <script> <files> --out out/res.json

If file does not end with .json, the path is treated as a directory path.

genaiscript run <script> <files> --out tmp

--json

Output the entire response as JSON to the stdout.

--out-trace file

Save the markdown trace to the specified file. Use --no-out-trace to disable the trace output.

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):

.github/workflows/genaiscript.yml

- 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.

genaiscript.pipeline.yml

- script: --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.

genaiscript run <script> <files> --out-annotations diags.csv

Use JSON lines (.jsonl) to aggregate annotations from multiple runs in a single file.

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 available, the JSON validation result is also stored.

genaiscript run <script> <files> --out-data data.jsonl

--out-changelogs file

Emit changelogs in the specified file as text.

genaiscript run <script> <files> --out-changelogs changelogs.txt

Remote scripts

You can specify a repository, branch to run a script from a remote repository. In that mode, the scripts from the current repository are ignored.

genaiscript run --remote <owner>/<repo>

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 the env when running the cli

    - run: --yes genaiscript run ... --pull-request-comment --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: genaiscript run ... --pull-request-description
  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)

genaiscript run ... --pull-request-description

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)

genaiscript run ... --pull-request-comment

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).

genaiscript run ... --pull-request-reviews

Read more

The full list of options is available in the CLI reference.