apigenie run

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

apigenie run [--config FILE] [--json]
apigenie run [--config FILE] NAME [ARGS...]
# apigenie.yaml
version: '1.0'
scripts:
  check: apigenie lint apis/orders/openapi.yaml
  bundle: apigenie bundle apis/orders/openapi.yaml -o dist/orders.yaml
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 of the configuration file, or of the file given with --config. They are not the scripts of apigenie-server, 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:

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

JSON output

apigenie run --json prints formatVersion, file and scripts (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:

{
  "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

Last updated on View as Markdown
Was this helpful?