# Run

> Learn how to execute genai scripts on files with streaming output to stdout, including usage of glob patterns, environment variables, and output options.

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

```bash
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](https://en.wikipedia.org/wiki/Glob_\(programming\)) pattern.

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

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

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

## Files

[Section titled “Files”](#files)

`run` takes one or more [glob](https://en.wikipedia.org/wiki/Glob_\(programming\)) patterns to match files in the workspace.

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

### Resource resolutions

[Section titled “Resource resolutions”](#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

[Section titled “Piping”](#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`.

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

### `--excluded-files` *files…*

[Section titled “--excluded-files files…”](#--excluded-files-files)

Excludes the specified files from the file set.

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

### `--exclude-git-ignore`

[Section titled “--exclude-git-ignore”](#--exclude-git-ignore)

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

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

## Configuration

[Section titled “Configuration”](#configuration)

### `--model` …

[Section titled “--model …”](#--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` …

[Section titled “--provider …”](#--provider)

Loads a set of model aliases for the given LLM provider.

### `--vars` name=value name2=value2 …

[Section titled “--vars name=value name2=value2 …”](#--vars-namevalue-name2value2)

Populate values in the `env.vars` map that can be used when running the prompt.

## Output

[Section titled “Output”](#output)

### `--out` *file|directory*

[Section titled “--out file|directory”](#--out-filedirectory)

Saves the results in a JSON file, along with markdown files of the output and the trace.

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

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

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

### `--json`

[Section titled “--json”](#--json)

Output the entire response as JSON to the stdout.

### `--out-trace` *file*

[Section titled “--out-trace file”](#--out-trace-file)

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

```sh
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

```yaml
- 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](https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?view=azure-devops\&tabs=bash#uploadsummary-add-some-markdown-content-to-the-build-summary) in your pipeline to upload the trace as a summary.

genaiscript.pipeline.yml

```yaml
- 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*

[Section titled “--out-annotations file”](#--out-annotations-file)

Emit annotations in the specified file as a JSON array, JSON Lines, [SARIF](https://sarifweb.azurewebsites.net/) or a CSV file if the file ends with `.csv`.

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

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

```sh
genaiscript run <script> <files> --out-annotations diags.jsonl
```

### `--out-data` *file*

[Section titled “--out-data file”](#--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.

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

### `--out-changelogs` *file*

[Section titled “--out-changelogs file”](#--out-changelogs-file)

Emit changelogs in the specified file as text.

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

## Remote scripts

[Section titled “Remote scripts”](#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.

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

## Pull Requests and Issues[]()

[Section titled “Pull Requests and Issues ”](#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

[Section titled “GitHub Action workflow configuration”](#github-action-workflow-configuration)

Update your workflow configuration to include the following:

* add the `pull-requests: write` permission to the workflow/step

```yaml
permissions:
  pull-requests: write
```

* set the `GITHUB_TOKEN` secret in the `env` when running the cli

```yaml
    - run: --yes genaiscript run ... --pull-request-comment --out-trace $GITHUB_STEP_SUMMARY
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        ... # LLM secrets
```

### Azure DevOps configuration

[Section titled “Azure DevOps configuration”](#azure-devops-configuration)

* add `<your projectname> Build Service` in the **Collaborator** role to the repository
* pass secrets to scripts, including `System.AccessToken`

```yaml
- script: genaiscript run ... --pull-request-description
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)
    ... # LLM secrets
```

### `--pull-request-description` \[tag]

[Section titled “--pull-request-description \[tag\]”](#--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](https://github.com/microsoft/genaiscript/pull/564))

```sh
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];

[Section titled “--pull-request-comment \[tag\];”](#--pull-request-comment-tag)

Upserts a comment on the pull request/issue with the LLM output ([example](https://github.com/microsoft/genaiscript/pull/564#issuecomment-2200474305))

```sh
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`[]()

[Section titled “--pull-request-reviews ”](#--pull-request-reviews)

Create pull request review comments from each [annotations](/genaiscript/reference/scripts/annotations) ([example](https://github.com/microsoft/genaiscript/pull/564#pullrequestreview-2151692644)).

```sh
genaiscript run ... --pull-request-reviews
```

## Read more

[Section titled “Read more”](#read-more)

The full list of options is available in the [CLI reference](/genaiscript/reference/cli/commands#run).