{"id":18420364,"url":"https://github.com/kubeshop/monokle-cli","last_synced_at":"2025-06-12T13:07:43.169Z","repository":{"id":98076025,"uuid":"586809871","full_name":"kubeshop/monokle-cli","owner":"kubeshop","description":"CLI for Monokle core validation library","archived":false,"fork":false,"pushed_at":"2024-04-17T10:06:51.000Z","size":857,"stargazers_count":22,"open_issues_count":7,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-25T22:04:48.088Z","etag":null,"topics":["helm","kubernetes","kustomize","static-analysis","validator","yaml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubeshop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-09T09:32:36.000Z","updated_at":"2025-04-17T13:21:57.000Z","dependencies_parsed_at":"2024-04-17T11:36:46.814Z","dependency_job_id":null,"html_url":"https://github.com/kubeshop/monokle-cli","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/kubeshop/monokle-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubeshop%2Fmonokle-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubeshop%2Fmonokle-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubeshop%2Fmonokle-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubeshop%2Fmonokle-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubeshop","download_url":"https://codeload.github.com/kubeshop/monokle-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubeshop%2Fmonokle-cli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259470949,"owners_count":22862998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helm","kubernetes","kustomize","static-analysis","validator","yaml"],"created_at":"2024-11-06T04:21:20.977Z","updated_at":"2025-06-12T13:07:43.111Z","avatar_url":"https://github.com/kubeshop.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/large-icon-256.png\" alt=\"Monokle Logo\" width=\"128\" height=\"128\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/kubeshop/monokle-cli\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/package-json/v/kubeshop/monokle-cli/master\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/kubeshop/monokle-cli/actions/workflows/check.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/kubeshop/monokle-cli/check.yml\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/kubeshop/monokle-cli\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Welcome to Monokle CLI\n\nMonokle CLI is a command-line interface for static analysis of Kubernetes resources.\n\nUse it to prevent misconfigurations within Kustomize, Helm or default Kubernetes resources. The output is available as a SARIF file which you can upload to GitHub CodeScan.\n\nMonokle CLI allows for integration with [Monokle Cloud](https://app.monokle.com/) and [Monokle Enterprise](https://monokle.io/) to manage and enforce validation policies centrally for all your repos and pipelines.\n\nYou can read more about Monokle CLI features and entire Monokle Ecosystem in [announcement blog-post](https://monokle.io/blog/monokle-cli-flexible-kubernetes-yaml-validation).\n\n## Table of contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Validation](#validation)\n  - [Validate a YAML file](#validate-a-yaml-file)\n  - [Validate a directory](#validate-a-directory)\n  - [Validate a templated Helm chart](#validate-a-templated-helm-chart)\n  - [Validate a Kustomize build](#validate-a-kustomize-build)\n  - [Validate using local configuration file](#validate-using-local-configuration-file)\n  - [Validate using centralized policy from Monokle Cloud](#validate-using-centralized-policy-from-monokle-cloud)\n  - [Frameworks](#frameworks)\n  - [Generate SARIF analysis](#generate-sarif-analysis)\n- [Using with Monokle Cloud](#using-with-monokle-cloud)\n- [Using with Monokle Enterprise](#using-with-monokle-enterprise)\n- [Using on CI/CD pipelines](#using-on-cicd-pipelines)\n- [Monokle GitHub Bot](#monokle-github-bot)\n- [Configuration](#configuration)\n  - [Command-line arguments](#command-line-arguments)\n  - [@monokle/validation rules](#monoklevalidation-rules)\n  - [Custom validators](#custom-validators)\n- [Docker](#docker)\n\n## Installation\n\nYou can install Monokle CLI via npm:\n\n```bash\nnpm install --global @monokle/cli\n```\n\nOr using brew if you're on MacOS:\n\n```bash\nbrew install kubeshop/monokle/monokle-cli\n```\n\n## Usage\n\nMonokle CLI exposes following commands:\n\n* `monokle validate [path]` - validate Kubernetes resources in a given path.\n* `monokle init` - generate local configuration file.\n* `monokle login` - login to Monokle Cloud or Enterprise to use remote policy.\n* `monokle logout`- logout from Monokle Cloud or Enterprise.\n* `monokle whoami` - get information about currently authenticated user.\n* `monokle config show [path]` - show policy configuration file which will be used to validated given path.\n\nYou can always use `--help` argument to get list of all available commands or detailed information about each command.\n\n## Validation\n\nMonokle CLI includes built-in validators to provide you with comprehensive validation possibilities for K8s configurations out of the box:\n\n- **Pod Security Standards** validation for secure deployments\n- **Kubernetes Schema** validation to ensure your resource are compliant with their schemas and a target K8s version\n- **Resource links** validates that reference to other Kubernetes resources are valid.\n- **Metadata** validation for standard and custom labels/annotations\n- **Common practices** validation for basic configuration sanity\n- **Security policies** based on OPA (Open Policy Agent) to reduce your attack surface.\n- **YAML Syntax** validates that your manifests have correct YAML syntax.\n\nUnder the hood it uses [@monokle/validation][https://github.com/kubeshop/monokle-core/tree/main/packages/validation] which allows you to configure validation rules extensively.\n\nOnce installed, using the CLI is straight-forward.\n\n### Validate a YAML file\n\n```bash\nmonokle validate bundle.yaml\n```\n\n### Validate a directory\n\nThis will recursively scan all YAML files and parse them as plain Kubernetes resources.\n\n```bash\nmonokle validate k8s-dir\n```\n\n### Validate a templated Helm chart\n\n```bash\nhelm template helm-dir | monokle validate -\n```\n\n### Validate a Kustomize build\n\n```bash\nkustomize build kustomize-dir/overlays/local | monokle validate -\n```\n\n### Validate using local configuration file\n\n```bash\nmonokle validate path/to/validate -c path/to/config/monokle.validation.yaml\n```\n\n### Validate using centralized policy from Monokle Cloud\n\nTo use remote policy, you need to login to Monokle CLoud first. This can be done via `monokle login` command:\n\n```bash\nmonokle login\n```\n\nAfter that, simply run `validate` command. Monokle CLI will fetch remote policy based on your user data:\n\n```bash\nmonokle validate path/to/validate\n```\n\n\u003e **IMPORTANT**: Please keep in mind that remote policies needs to be configured first. Please refer to [Using with Monokle Cloud](#using-with-monokle-cloud) section below.\n\n### Frameworks\n\nMonokle CLI supports predefined sets of rules called frameworks, which allow you to quickly run Monokle validation without the need for additional configuration.\nBy using a framework, you can easily perform comprehensive validations based on established best practices and industry standards.\n\nWhen using a framework, you don't have to configure the `monokle.validation.yaml` file manually.\nSimply specify the desired framework using the `--framework` or `-f` CLI arguments, and Monokle CLI will automatically apply the corresponding set of rules.\n\nAvailable frameworks:\n\n- `pss-restricted`\n- `pss-baseline`\n- `nsa`\n\nUsing frameworks is an excellent way to get started quickly with Monokle CLI and perform comprehensive validations without the need for extensive configuration.\n\nHere's an example of how to use the `--framework` argument:\n\n```bash\nmonokle validate k8s-dir --framework pss-restricted\n```\n\nIf you prefer a more customized validation, you can still configure the `monokle.validation.yaml` file with your own rules. The easiest way is to use `monokle init` command which will guide you through creating custom configuration based on available frameworks.\n\n### Generate SARIF analysis\n\nThe Monokle CLI can output its results in [SARIF format](https://sarifweb.azurewebsites.net/).\n\n```bash\nmonokle validate --output sarif k8s-dir \u003e results.sarif\n```\n\nAfterward you could use [VSC's SARIF Viewer][vsc-sarif] or other tools to inspect the results.\n\n## Using with Monokle Cloud\n\nTo use remote policy with Monokle CLI you will need to create a project and configure policy for it in Monokle Cloud. Start by signing in to [Monokle Cloud](https://app.monokle.com).\n\n\u003e In case of doubts, refer to [Getting Started Guide](https://docs.monokle.com/tutorials/getting-started) or hit us directly on [Discord](https://discord.com/invite/6zupCZFQbe).\n\n### Project setup\n\nAfter signing up, start by creating a project on [Projects page](https://app.monokle.com/dashboard/projects):\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/projects.png\"/\u003e\n\u003c/p\u003e\n\n### Add your repository to your project\n\nAfter project is created, add a repository (the one you will be working locally with) to a project. This can be done by going to `Repositories` tab in project view and using `Add repository` button:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/repos.png\"/\u003e\n\u003c/p\u003e\n\n### Policy setup\n\nThe last step is policy setup. You can use policy wizard by going to `Policy` tab in project view:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/policies.png\"/\u003e\n\u003c/p\u003e\n\nAfter the setup is done, you can run `monokle validate` command and it will use remote policy as long as you are logged in.\n\n## Using with Monokle Enterprise\n\nUsing with Monokle Enterprise (self-hosted) is very similar to usage with Monokle Cloud. The main difference is the origin (URLs) with which Monokle CLI will communicate. This can be set on `login` or for each command separately (useful for automated scenarios).\n\n```bash\nmonokle login --origin https://monokle.mydomain.com\n```\n\n\u003e **IMPORTANT**: Env variable `MONOKLE_ORIGIN` can be also used to set origin for logging command. If neither is used, CLI will prompt whenever to use custom origin.\n\nFor using `--origin` flag without logging in, please refer to [Using on CI/CD pipelines](#using-on-cicd-pipelines) section below.\n\n## Using on CI/CD pipelines\n\n\u003e We have dedicated [`Monokle GitHub Bot`](#monokle-github-bot) to integrate centralized policy management into GitHub CI/CD pipelines which gives tighter integration with Monokle Cloud than using CLI directly.\n\nTo use Monokle CLI as part of CI/CD pipeline, it needs to be installed first and then simply run with `monokle validate path/to/resources`.\n\nThe other case is using centrally managed policy from Monokle Cloud in such scenarios. In such, one should use Automation Token (which can be generated via `Automation token` tab in `Workspace` view) together with project id from which policy should be used:\n\n```bash\nmonokle validate project/path -t YOUR_AUTOMATION_TOKEN -p PROJECT_ID\n```\n\n\u003e Project id can be obtain on Project details page from URL `https://app.monokle.com/dashboard/projects/\u003cprojectId\u003e`.\n\nYou can also change origin which will be used to fetch policies from (e.g. when running your own instance of Monokle Enterprise):\n\n```bash\nmonokle validate project/path -t YOUR_AUTOMATION_TOKEN -p PROJECT_ID -r https://monokle.mydomain.com\n```\n\n\u003e **IMPORTANT**: Always remember to keep your API token as secret and pass it to CI/CD jobs the same way as other secrets.\n\n## Monokle GitHub Bot\n\nThe [Monokle GitHub Bot](https://docs.monokle.com/concepts/github-bot) can be used to validate your resources as part of your GitHub CI/CD pipelines. It is integrated with [Monokle Cloud](https://app.monokle.com/) out-of-the-box to allow easy centralized policy management.\n\n## Monokle GitHub Action\n\nThe [Monokle GitHub Action](https://github.com/marketplace/actions/monokle-validation) can be used to validate your resources as part of your CI/CD pipelines\non GitHub. It gives more customizability when it comes to validating Dry Runs results.\n\nIf you need something tightly integrated with Monokle Cloud, we recommend using [`Monokle GitHub Bot`](#monokle-github-bot).\n\n## Configuration\n\n### Command-line arguments\n\nYou can use `--help` to access help information directly from the CLI.\n\n### @monokle/validation rules\n\nThe Monokle CLI looks for a Monokle Validation configuration file at `./monokle.validation.yaml`. You can change this by using the `--config` flag.\n\nAll rules are enabled by default and are described in the [Monokle Validation configuration][monokle-validation-docs] documentation.\n\n**Example**\n\n```yaml\nplugins:\n  yaml-syntax: true\n  kubernetes-schema: true\nrules:\n  yaml-syntax/no-bad-alias: \"warn\"\n  yaml-syntax/no-bad-directive: false\n  open-policy-agent/no-last-image: \"err\"\n  open-policy-agent/cpu-limit: \"err\"\n  open-policy-agent/memory-limit: \"err\"\n  open-policy-agent/memory-request: \"err\"\nsettings:\n  kubernetes-schema:\n    schemaVersion: v1.24.2\n```\n\n### Custom validators\n\nIt is easy to extend the Monokle CLI with [custom validators][custom-validators] that can be shared with others using our [Monokle Community Plugins][monokle-community-plugins] repository.\n\n## Docker\n\nYou can use the Docker image `monokle-cli:latest` to run the Monokle CLI in a containerized environment.\nThis can be particularly useful for integrating Monokle into CI/CD pipelines or other automated systems.\n\nTo run the Docker image, you can use the `docker run` command.\nThe Monokle CLI arguments can be passed directly to the Docker run command.\nFor example:\n```\ndocker run -v /path/to/input:/input -e CONFIG_FILE=my-validation-config.yaml monokle-cli:latest validate /input\n```\n\nIn this command:\n  - `-v /path/to/input:/input` mounts a directory from your host system to the /input directory inside the Docker container.\n  - `-e CONFIG_FILE=my-validation-config.yaml` sets an environment variable inside the Docker container. If this environment variable is set, the Docker container will use the specified file as the Monokle validation configuration.\n  - `validate /input` is the command that will be passed to the Monokle CLI. You can replace this with any command you want to run with the Monokle CLI.\n\n[core-validators]: https://github.com/kubeshop/monokle-core/blob/main/packages/validation/docs/core-plugins.md\n[custom-validators]: https://github.com/kubeshop/monokle-core/blob/main/packages/validation/docs/custom-plugins.md\n[monokle-community-plugins]: https://github.com/kubeshop/monokle-community-plugins\n[monokle-validation]: https://github.com/kubeshop/monokle-core/tree/main/packages/validation\n[monokle-validation-docs]: https://github.com/kubeshop/monokle-core/blob/main/packages/validation/docs/configuration.md\n[vsc-sarif]: https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubeshop%2Fmonokle-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubeshop%2Fmonokle-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubeshop%2Fmonokle-cli/lists"}