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"

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.

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

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 &lt;file&gt;

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 the env 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