apigentools CLI Reference

Note

This is documentation for apigentools major version 1, which has significant differences from the 0.X series. Refer to upgrading docs for further details.

Basic Usage

apigentools <APIGENTOOLS_ARGS> <SUBCOMMAND> <SUBCOMMAND_ARGS>

Many arguments take values from environment variables and coded-in defaults. In this case, the actual value is obtained like this:

Throughout this document, arguments with this behavior have a value both in their "Environment Variable" column as well as in their "Default" column.

Argument Description Environment Variable Default
-av API_VERSIONS, --api-versions API_VERSIONS The API version to run the specified action against. These must match what the config in the spec repo contains. Example: apigentools -av v1 -av v2 test APIGENTOOLS_API_VERSION None to run against all
--help Show help message and exit.
-l LANGUAGES, --languages LANGUAGES Languages to run the specified action against. These must match what the config in the spec repo contains. Example: apigentools -l go -l java test APIGENTOOLS_LANG None to run against all
-r SPEC_REPO_DIR, --spec-repo-dir SPEC_REPO_DIR Switch to this directory before doing anything else. APIGENTOOLS_SPEC_REPO_DIR .
--git-via-https Whether to use HTTPS (or SSH) for git actions. APIGENTOOLS_GIT_VIA_HTTPS false
--git-via-https-installation-access-token Use installation access token (authenticating a Github app) for git actions. Mutually exclusive with --git-via-https-oauth-token. APIGENTOOLS_GIT_VIA_HTTPS_INSTALLATION_ACCESS_TOKEN
--git-via-https-oauth-token Use OAuth over HTTPS, passing this token for git actions. Mutually exclusive with --git-via-https-installation-access-token. APIGENTOOLS_GIT_VIA_HTTPS_OAUTH_TOKEN
--verbose Log generation in verbose mode.
--delete-generated-files Delete generated files in output_dir before generation NA False
--skip-version-check Skip the check that the apigentools version is in range of whats supported in the spec config file. APIGENTOOLS_SKIP_VERSION_CHECK False

apigentools generate

Generates client code. When specified with the --clone-repo flag, the directory with generated code for that language must be empty.

Argument Description Environment Variable Default
--additional-stamp [ADDITIONAL_STAMP [ADDITIONAL_STAMP ...]] Additional components to add to the apigentoolsStamp variable passed to templates. APIGENTOOLS_ADDITIONAL_STAMP []
--branch When specified, changes the client repository branch before running code generation. APIGENTOOLS_PULL_REPO_BRANCH None
--clone-repo Whether to clone the client Github repositories before running code generation. APIGENTOOLS_PULL_REPO False
-f FULL_SPEC_FILE, --full-spec-file FULL_SPEC_FILE Name of the OpenAPI full spec file to write. Note that if some languages override config's spec_sections, additional files will be generated with name pattern full_spec.<lang>.yaml. APIGENTOOLS_FULL_SPEC_FILE full_spec.yaml
--is-ancestor Checks that the --branch is ancestor of specified branch. Useful to enforce in CI that the feature branch is on top of master branch: '-branch feature --is-ancestor master'. APIGENTOOLS_IS_ANCESTOR None
--help Show help message and exit.
--skip-templates Skip template preparation step. APIGENTOOLS_SKIP_TEMPLATES False

apigentools init

Initializes a new spec repo.

Argument Description Environment Variable Default
-g, --no-git-repo Don't initialize a git repository in the project directory.
--help Show help message and exit.

apigentools push

Pushes the content of the generated directory to its target git repository. The generated directory is left in the branch that was checked out to push the code.

Argument Description Environment Variable Default
--default-branch Default branch of client repo. If this branch does not exist, it is created and pushed to instead of a new feature branch APIGENTOOLS_DEFAULT_PUSH_BRANCH master
--dry-run Do a dry run (do not actualy create branches/commits or push). False
--git-email Email of the git commit author. APIGENTOOLS_GIT_AUTHOR_EMAIL None
--git-name Name of the git commit author. APIGENTOOLSGIT_AUTHOR_NAME None
--help Show help message and exit.
--push-commit-msg Commit message to use when pushing the generated clients. APIGENTOOLS_COMMIT_MSG Regenerate client from commit <COMMIT_ID> of spec repo
--skip-if-no-changes Skip committing/pushing for all repositories where only .apigentools-info has changed. APIGENTOOLS_SKIP_IF_NO_CHANGES False

Note Specifying the --git-* flags modifies the .git/config settings of each local repository that you push to to via apigentools. This does not modify the global .git/config.

apigentools split

Splits an existing one-file OpenAPI spec into multiple sections suitable for usage with apigentools. This is useful when doing a first-time batch import of an already existing spec.

Argument Description Environment Variable Default
--help Show help message and exit.
-i INPUT_FILE, --input-file INPUT_FILE Path to the OpenAPI full spec file to split.
-v API_VERSION, --api-version API_VERSION Version of API that the input spec describes. APIGENTOOLS_SPLIT_SPEC_VERSION v1

apigentools templates

Obtains upstream openapi-generator templates, applies template patches, and saves them to a templates directory.

Argument Description Environment Variable Default
--help Show help message and exit.

apigentools test

Runs tests of generated clients.

Argument Description Environment Variable Default
--container-env [CONTAINER_ENV [CONTAINER_ENV ...]] Additional environment variables to pass to containers running the tests, for example --container-env API_KEY=123 OTHER_KEY=234. Note that apigentools contains additional logic to treat these values as sensitive and avoid logging them during runtime. (NOTE: if the testing container itself prints this value, it will be logged as part of the test output by apigentools).
--help Show help message and exit.
--no-sensitive-output By default, it is considered that the environment values provided through --container-env may contain sensitive values and the whole command and its output is therefore hidden. You can override this behaviour by using this flag. APIGENTOOLS_NO_SENSITIVE_OUTPUT False

apigentools config

Displays information about the configuration for the spec being worked on, including supported languages, api versions, and the paths to the generated api yaml. These languages and api versions can be directly passed to the --languages and --api-versions flags of the supported commands.

Argument Description Environment Variable Default
-f FULL_SPEC_FILE, --full-spec-file FULL_SPEC_FILE Name of the OpenAPI full spec file to write. Note that if some languages override config's spec_sections, additional files will be generated with name pattern full_spec.<lang>.yaml. APIGENTOOLS_FULL_SPEC_FILE full_spec.yaml
-L, --list-languages Whether to only list the languages supported by this spec. Example: apigentools -l NA None to list both languages and versions
-V, --list-versions Whether to only list the API versions supported by this spec. Example: apigentools -av NA None to list both languages and versions
--help Show help message and exit.

apigentools validate

Runs validation steps defined in config/config.yaml.

Argument Description Environment Variable Default
-f FULL_SPEC_FILE, --full-spec-file FULL_SPEC_FILE Name of the OpenAPI full spec file to write. Note that if some languages override config's spec_sections, additional files will be generated with name pattern full_spec.<lang>.yaml. APIGENTOOLS_FULL_SPEC_FILE full_spec.yaml
--help Show help message and exit.