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
NAMEadded at the end of its command line, options included:apigenie run check --jsonrunsapigenie lint apis/orders/openapi.yaml --json; - with the same
apigenieexecutable, not one found inPATH, 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
- Configuration: The
scriptssection. - Commands: The commands a script can run.