Command Line Options

Generic Options

Some command line options aren’t associated with a specific command, but can provided to any command instead.

--working-dir: Commodore creates a large amount of directories and files. By default, this happens in the current working directory of the environment in which Commodore is executed. If this option is provided, Commodore will create its directories and files in the provided location.
--version: Show the version and exit.
-v, --verbose: Control verbosity. Can be repeated for more verbose output. Can also be provided after subcommands (for example commodore catalog compile -v).

Currently three verbosity levels are implemented, regular operation is active when the flag isn’t provided, debug verbosity is enabled when the flag is provided once or more, and trace verbosity is enabled when the flag is provided three times or more.
--help: Show help message for generic options and available commands then exit.

Catalog Clean

This command doesn’t have any command line options.

Catalog Compile

--api-url URL: Lieutenant API URL.
--api-token TOKEN: Lieutenant API token.
--local: Run in local mode. Intended to be used to test/verify local changes (for example during component development) against an existing cluster inventory and catalog.

Local mode doesn’t try to connect to the Lieutenant API or fetch/push Git repositories. However, local mode expects the working directory to contain a valid inventory in inventory/ and all the dependencies (components and Jsonnet libraries) required by the inventory in dependencies/, with component classes symlinked to inventory/ and component and 3rd party Jsonnet libraries symlinked to dependencies/lib.

In local mode, uncommitted modifications to the inventory and dependencies are never discarded.

Local mode will fail when the cluster id of the inventory differs from the cluster id for which compilation was requested.

If catalog/ is provided for a local mode compilation, Commodore will show a diff of the changes compared to the provided catalog. There’s currently no mechanism that ensures that the provided cluster catalog actually matches the cluster for which compilation was requested.

The quickest way to get a working directory setup for local mode is to run a "regular" catalog compile for the cluster you want to work against.

See also local mode documentation.
--fetch-dependencies/--no-fetch-dependencies: Whether to fetch Jsonnet and Kapitan dependencies in local mode.

This flag doesn’t have an effect in regular mode, but speeds up local mode by not fetching Jsonnet dependencies, and disabling Kapitan’s dependency fetching. By default, Jsonnet and Kapitan dependencies are fetched in local mode, to make local testing of component and configuration changes easier. Additionally, having Jsonnet and Kapitan dependency fetching enabled in local mode is required to test some types of changes such as upgrading versions.

When you want to test adding a new component in local mode, you must run local mode with dependency fetching enabled at least once. After that, all the symlinks and dependencies which are required to compile the component will be present and you can disable dependency fetching.
-m, --migration: Specify a migration that you expect to happen for the cluster catalog. Currently known are the Kapitan 0.29 to 0.30 migration and a generic migration ignoring all non-functional YAML formatting changes. When the Kapitan 0.29 to 0.30 migration is selected, Commodore will suppress noise (changing managed-by labels, and reordered objects) caused by the migration in the diff output. When the ignore YAML formatting migration is selected, Commodore will suppress noise such as reordered objects, indentation and flow changes of lists or differences in string representation.
--push: Push catalog to remote repository as discovered in the cluster configuration fetched from the Lieutenant API.
--interactive: Show changes and prompt if they should be pushed to the remote repository. This doesn’t do anything unless --push is provided.
--git-author-name USERNAME: Name of catalog commit author
--git-author-email EMAIL: E-mail address of catalog commit author
--global-repo-revision-override REV: Git tree-ish to checkout for the global config repository. This command line parameter overrides the global git repository revision configured on the cluster or tenant object in Lieutenant. When this option is provided, Commodore will abort without compiling the catalog if --push is also provided.
--tenant-repo-revision-override REV: Git tree-ish to checkout for the tenant config repository. This command line parameter overrides the tenant git repository revision configured on the cluster object in Lieutenant. When this option is provided, Commodore will abort without compiling the catalog if --push is also provided.
-d, --dynamic-fact KEY=VALUE: Fallback dynamic facts to use when compiling a cluster which hasn’t reported its dynamic facts yet. Commodore will never use values provided through this parameter if the cluster response from the API has a dynamic facts field. Can be repeated. Commodore expects each fact to be specified as key=value. Nested keys can be provided as path.to.key. Commodore will parse values as JSON if they’re prefixed by json:. If the same key is provided multiple times, the last occurrence overrides the previous values. When providing a value for a key as JSON, previously specified subkeys of that key will be overwritten. Nested keys are ignored if any non-leaf level of the requested key already contains a non-dictionary value. If a value prefixed with json: isn’t valid JSON, it will be skipped.
--force / --no-force: With --force local changes (uncommitted changes, untracked files, or commits or branches which haven’t been pushed) in the global and tenant repo checkouts are discarded. Additionally, uncommitted changes in tracked files in dependency repos (components or packages) are discarded.

With --no-force, local changes in global, tenant, or dependency checkouts are preserved, and the catalog compilation will abort with an error if there’s local changes present. Specifying --force has no effect if --local is given, and is silently ignored. Defaults to --no-force.
--help: Show catalog clean usage and options then exit.

Catalog List

-o, --out TEXT: Output format. One of: (json, yaml, id)
-t, --tenant TEXT: If non-empty, only show clusters of the tenant with the provided ID
--sort-by TEXT: If non-empty, sort list using this flag specification. One of: (id, tenant, displayName)

Component Compile

-f, --values FILE: Specify inventory class in a YAML file. This option can be repeated to provide multiple files. Files specified later win when resolving inventory values.
-n, --name NAME: Provide component name to use when compiling. By default, the component name is derived from the directory which is being compiled.
-a, --alias ALIAS: Provide component alias to use when compiling component.
-J, --search-paths DIRECTORY: Specify additional search paths.
-o, --output DIRECTORY: Specify output path for compiled component. Defaults to ./.
--help: Show catalog compile usage and options then exit.

Component New

--name TEXT: The component’s name as it will be written in the documentation. Defaults to the slug.
--lib / --no-lib: Add a component library template. Defaults to no.
--pp / --no-pp: Add a component postprocessing template. Defaults to no.
--owner TEXT: The GitHub user or project name where the component will be hosted. Defaults to projectsyn.
--copyright TEXT: The copyright holder added to the license file. Defaults to "VSHN AG <info@vshn.ch>."
--golden-tests / --no-golden-tests: Enable golden tests for the component. Defaults to yes.
--matrix-tests / --no-matrix-tests: Enable test matrix for the component compile and golden tests. Defaults to yes.
--output-dir DIRECTORY: The directory in which to place the new component. If not provided, the component is placed into dependencies/<component-slug> in the Commodore working directory.
--template-url TEXT: The URL of the component cookiecutter template. By default github.com/projectsyn/commodore-component-template.git is used.
--template-version TEXT: The component template version (Git tree-ish) to use. Defaults to main.
--additional-test-case, -t CASE: Additional test cases to generate in the new component. Can be repeated. Test case defaults will always be generated. Commodore will deduplicate the provided test cases.
--help: Show component new usage and options then exit.

Component Update

--lib / --no-lib: Add or remove the component library template. When neither is provided, the command will reuse the previous value for the flag. Defaults to unset.
--pp / --no-pp: Add or remove the component postprocessing config. When neither is provided, the command will reuse the previous value for the flag. Defaults to unset.
--golden-tests / --no-golden-tests: Enable or disable golden tests for the component. When neither is provided, the command will reuse the previous value for the flag. Defaults to unset.
--matrix-tests / --no-matrix-tests: Enable test matrix for the component compile and golden tests. When neither is provided, the command will reuse the previous value for the flag. Defaults to unset.
--copyright TEXT: Update the copyright holder in the license file. When this flag isn’t provided the copyright holder is left unchanged. Defaults to unset.
--update-copyright-year / --no-update-copyright-year: Update the year in the copyright notice to the current year. Defaults to false.
--additional-test-case, -t CASE: Additional test cases to add to the component. Can be repeated. Commodore will deduplicate the provided test cases.
--remove-test-case CASE: Test cases to remove from the component. Can be repeated.
--commit / --no-commit: Whether to commit the rendered template changes.
--help: Show component new usage and options then exit.

Component Sync

--github-token TEXT

The GitHub access token to use when interacting with the GitHub API. We recommend passing the token in environment variable COMMODORE_GITHUB_TOKEN.

--dry-run

If this flag is provided, the sync command doesn’t commit the rendered changes, doesn’t push the template branch to GitHub and doesn’t create or update any PRs.

-b, --pr-branch BRANCH

The branch name to use when pushing updates to GitHub. By default template-sync is used used as the branch name.

Changing this flag will orphan any open update PRs created with a different branch name.

-l, --pr-label LABEL

Labels to set on the PR. Can be repeated.

When changing the set of labels, new labels will be added to open PRs. However, labels added by previous runs can’t be removed since we’ve got no easy way to distinguish between old labels and externally added labels.

--pr-batch-size COUNT

The number of PRs to create before pausing. Tune this parameter if your sync job hits the GitHub secondary rate limit.

--github-pause SECONDS

The duration for which to pause (in seconds) after creating a number of PRs according to --pr-batch-size. Tune this parameter if your sync job hits the GitHub secondary rate limit.

--filter REGEX

Regex to select which dependencies to sync. If the option isn’t given, all dependencies listed in the provided YAML are synced.

Inventory Components / Packages / Show

-f, --values: Specify an additional inventory class in a YAML file. This option can be repeated to provide multiple files. Files specified later win when resolving inventory values. Use this mechanism to specify any facts (such as the cluster’s distribution) that should be taken into account when rendering the inventory.
-o, --output-format: The output format for the command. Supported values are json and yaml. Defaults to yaml.

Inventory Lint

-l, --linter: Which linters to enable. Supported values are component-versions and deprecated-parameters. Can be repeated. If this parameter isn’t specified, all known linters are enabled.
--ignore-patterns=GLOB: Glob pattern(s) indicating path(s) to ignore. Can be repeated.

Login

--oidc-discovery-url URL: The discovery URL of the IdP. OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL. Typically this is at auth.example.com/.well-known/openid-configuration.
--oidc-client TEXT: The OIDC client-id.
--api-url URL: Lieutenant API URL.

Fetch Token

--oidc-discovery-url URL: The discovery URL of the IdP. OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL. Typically this is at auth.example.com/.well-known/openid-configuration.
--oidc-client TEXT: The OIDC client-id.
--api-url URL: Lieutenant API URL. This parameter is required. If the OIDC discovery URL and OIDC client aren’t provided, Commodore will try to fetch those informations from the given Lieutenant API.

Package New

--name TEXT: The package’s name as it will be written in the documentation. Defaults to the slug.
--owner TEXT: The GitHub user or project name where the package will be hosted. Defaults to projectsyn.
--copyright TEXT: The copyright holder added to the license file. Defaults to "VSHN AG <info@vshn.ch>."
--golden-tests / --no-golden-tests: Enable golden tests for the package. Defaults to yes.
--template-url TEXT: The URL of the package cookiecutter template. Defaults to github.com/projectsyn/commodore-config-package-template.git.
--template-version TEXT: The package template version (Git tree-ish) to use. Defaults to main.
--output-dir DIRECTORY: The directory in which to place the new package. If this option isn’t provided, the command will place the new package under inventory/classes/ in the Commodore working directory.
--additional-test-case, -t CASE: Additional test cases to generate in the new package. Can be repeated. Test case defaults will always be generated. Commodore will deduplicate the provided test cases.

Package Update

--copyright TEXT: The copyright holder added to the license file. If not provided, the existing copyright holder of the package is kept.
--golden-tests / --no-golden-tests: Enable golden tests for the package. If neither option is provided, the package’s existing config is used.
--additional-test-case, -t CASE: Additional test cases to add to the package. Can be repeated. Commodore will deduplicate the provided test cases.
--remove-test-case CASE: Test cases to remove from the package. Can be repeated.
--commit / --no-commit: Whether to commit the rendered template changes.

Package Compile

-f, --values FILE

Specify an additional inventory class in a YAML file. This option can be repeated to provide multiple files. Files specified later win when resolving inventory values.

These classes are included before the target class which is getting compiled. This allows users to customize cluster facts or similar when compiling packages standalone.

--local

Run in local mode. Intended to be used to test/verify local changes (for example during component development) of a package.

Local mode doesn’t try to fetch components included by the package. In local mode, uncommitted modifications to the inventory and dependencies are never discarded.

However, local mode expects that the working directory contains:

a valid inventory in inventory/
all the dependencies required by the package available locally
component classes symlinked to inventory/
components and Jsonnet dependencies symlinked to vendor/

The quickest way to get a working directory setup for local mode is to run a "regular" package compile for the package you want to work on.

+ Overall, this flag has the same semantics as --local of catalog compile.

--fetch-dependencies/--no-fetch-dependencies

Whether to fetch Jsonnet and Kapitan dependencies in local mode.

This flag doesn’t have an effect in regular mode, but speeds up local mode by not fetching Jsonnet dependencies, and disabling Kapitan’s dependency fetching. By default, Jsonnet and Kapitan dependencies are fetched in local mode, to make local testing of component and configuration changes easier. Additionally, having Jsonnet and Kapitan dependency fetching enabled in local mode is required to test some types of changes such as upgrading versions.

When you want to test adding a new component in local mode, you must run local mode with dependency fetching enabled at least once. After that, all the symlinks and dependencies which are required to compile the component will be present and you can disable dependency fetching.

Overall, this flag has the same semantics as --fetch-dependencies of catalog compile.

--keep-dir / --no-keep-dir

Whether to keep the compilation temp directory after the compilation is done.

This flag allows users to keep the package compilation temp directory created by Commodore for subsequent package compilations in local mode. If this flag isn’t provided, Commodore will delete the temp directory after compilation is done.

--tmp-dir PATH

Temp directory to use for compilation. Implies --keep-dir.

When this flag is provided, Commodore will use the provided path as the directory for the compilation. It’s the users responsibility to clean up the temp directory when this flag is provided.

If the specified path doesn’t exist, Commodore will create it as a directory.

Package Sync