# apigenie run

Source: https://api-genie.dev/docs/reference/cli/run
Part of the reference of [apigenie](https://api-genie.dev/docs/reference/cli.md).
Its other pages: [bundle](https://api-genie.dev/docs/reference/cli/bundle.md), [changelog](https://api-genie.dev/docs/reference/cli/changelog.md), [commands](https://api-genie.dev/docs/reference/cli/command-index.md), [completion](https://api-genie.dev/docs/reference/cli/completion.md), [config](https://api-genie.dev/docs/reference/cli/config.md), [convert](https://api-genie.dev/docs/reference/cli/convert.md), [credits](https://api-genie.dev/docs/reference/cli/credits.md), [diff](https://api-genie.dev/docs/reference/cli/diff.md), [evolve](https://api-genie.dev/docs/reference/cli/evolve.md), [format](https://api-genie.dev/docs/reference/cli/format.md), [i18n](https://api-genie.dev/docs/reference/cli/i18n.md), [init](https://api-genie.dev/docs/reference/cli/init.md), [license](https://api-genie.dev/docs/reference/cli/license.md), [lint](https://api-genie.dev/docs/reference/cli/lint.md), [overlay](https://api-genie.dev/docs/reference/cli/overlay.md), [test](https://api-genie.dev/docs/reference/cli/test.md), [window](https://api-genie.dev/docs/reference/cli/window.md).

Runs a script: a named `apigenie` command line from the `scripts` section of `apigenie.yaml`. The
arguments after the name are added at the end of the command line. Since 0.13.0.

## Usage

```sh
apigenie run [--config FILE] [--json]
apigenie run [--config FILE] NAME [ARGS...]
```

```yaml
# apigenie.yaml
version: '1.0'
scripts:
  check: apigenie lint apis/orders/openapi.yaml
  bundle: apigenie bundle apis/orders/openapi.yaml -o dist/orders.yaml
```

```sh
apigenie run check
apigenie run check --formatter sarif > lint.sarif
```

## Description

A script gives a command line of `apigenie` a name in `apigenie.yaml`, so that a developer and a CI
job run it with `apigenie run NAME`.

The scripts are in the [`scripts` section](/docs/reference/cli/configuration#scripts) of the
[configuration file](/docs/reference/cli/configuration#where-the-file-is-found), or of the file
given with `--config`. They are not the
[scripts of `apigenie-server`](/docs/reference/server/scripts), the JavaScript modules of its hooks.
`apigenie run NAME` runs the script `NAME`:

- from the directory of the configuration file, whatever the current directory: the paths of the
  script, and those among the arguments after `NAME`, are relative to that directory;
- with the arguments after `NAME` added at the end of its command line, options included:
  `apigenie run check --json` runs `apigenie lint apis/orders/openapi.yaml --json`;
- with the same `apigenie` executable, not one found in `PATH`, and with no standard input.

To run a script, a file given with `--config` must be the one that the script's command finds
from the file's directory, such as `ci/apigenie.yaml`. With another file, such as `scripts.yaml`,
`apigenie run NAME` exits with 2, even when the scripts give `--config` themselves.
`apigenie run` without a name still lists the scripts of any file.

Before running the script, the command prints what it runs on the standard error after `> `: the
words of the script, quoted again where needed, and the arguments added. The standard output, the
standard error and the exit status are those of the script's command.

Without `NAME`, the command lists the scripts of the file with their command lines:

```text
Scripts of /home/me/orders/apigenie.yaml:
  check   apigenie lint apis/orders/openapi.yaml
  bundle  apigenie bundle apis/orders/openapi.yaml -o dist/orders.yaml
```

A file without scripts prints `<path> has no scripts.` When a name appears twice in the file, the
first script with that name is the one listed and run.

### Command lines

A command line starts with `apigenie`, followed by one of its commands other than `run`. No shell
reads it:

- blanks (spaces, tabs and line breaks) separate the words;
- single or double quotes group words: `'my api.yaml'` is one word, and so is `--title="My API"`,
  read as `--title=My API`. A quote of the other kind inside them is kept, and `''` is an empty
  word;
- nothing else is special: `$HOME`, `*`, `|`, `>` and `\` are passed as they are, so there are no
  variables, globs, pipes or redirections, and Windows paths need no escaping.

A script that runs another program, such as `npm test`, or a name outside the pattern of
[`scripts`](/docs/reference/cli/configuration#scripts), fails the schema check: every command that
reads the file exits with 2. A script that runs `apigenie run`, or has an unclosed quote, exits with
2 when it runs.

### Security

A script runs only commands of `apigenie`, and only when `apigenie run` is started, by a person or a
CI job. The desktop editor, the web editor, the VS Code extension and the
[MCP server](/docs/reference/cli/mcp) don't run scripts. Before running the scripts of a
repository you didn't write, read them with `apigenie run`: like the commands they run, they can
read and write files and send requests.

## Options

| Option          | Description |
| --------------- | ----------- |
| `--config FILE` | Uses FILE instead of the configuration file found in the repository. To run a script, FILE must be the file that the script's command finds from the directory of FILE ([Description](#description)). |
| `--no-config`   | Uses no configuration file: there is no script, and the command exits with 2. |
| `--json`        | Lists the scripts as one JSON document. |

The options of `apigenie run` come before `NAME`. Everything after `NAME` goes to the script's
command, `--help` and `--json` included.

## Exit status

| Status | Meaning |
| ------ | ------- |
| 0 | Without `NAME`: the scripts were listed. |
| 2 | No configuration file (`--no-config` included), a file that fails its schema, a standalone `apigenie-server` file ([Configuration](/docs/reference/cli/configuration#scripts)), a `--config` file other than the one the scripts' commands find from its directory, an unknown script, a command line that can't run, or `--json` with `NAME`. |
| any | With `NAME`: the exit status of the script's command, 0 included; see [exit status](/docs/reference/cli#exit-status). |

## JSON output

`apigenie run --json` prints `formatVersion`, `file` and `scripts`
([`apigenie-run-report.json`](https://apigenie.pl/schemas/apigenie-run-report.json)). `file` is the
path of the configuration file: absolute when it was found, as given when it came from `--config`.
`scripts` holds the scripts in the order of the file:

```json
{
  "formatVersion": 1,
  "file": "/home/me/orders/apigenie.yaml",
  "scripts": {
    "check": "apigenie lint apis/orders/openapi.yaml",
    "bundle": "apigenie bundle apis/orders/openapi.yaml -o dist/orders.yaml"
  }
}
```

For the JSON output of a script's command, give `--json` after the name:
`apigenie run check --json`.

## See also

- [Configuration](/docs/reference/cli/configuration#scripts): The `scripts` section.
- [Commands](/docs/reference/cli): The commands a script can run.
