{"id":13495370,"url":"https://github.com/cirruslabs/cirrus-cli","last_synced_at":"2026-02-20T19:05:37.874Z","repository":{"id":37030665,"uuid":"278458949","full_name":"cirruslabs/cirrus-cli","owner":"cirruslabs","description":"CLI for executing Cirrus tasks locally and in any CI","archived":false,"fork":false,"pushed_at":"2024-04-26T06:57:09.000Z","size":2865,"stargazers_count":187,"open_issues_count":9,"forks_count":17,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-01T10:18:34.999Z","etag":null,"topics":["ci-cd","containers","devops","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cirruslabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2020-07-09T19:59:59.000Z","updated_at":"2024-08-14T19:40:55.158Z","dependencies_parsed_at":"2023-02-18T00:45:58.770Z","dependency_job_id":"e17afbfb-18ad-435a-a30b-264209ce69e5","html_url":"https://github.com/cirruslabs/cirrus-cli","commit_stats":null,"previous_names":[],"tags_count":257,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirruslabs%2Fcirrus-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirruslabs%2Fcirrus-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirruslabs%2Fcirrus-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirruslabs%2Fcirrus-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cirruslabs","download_url":"https://codeload.github.com/cirruslabs/cirrus-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248126161,"owners_count":21051876,"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":["ci-cd","containers","devops","golang"],"created_at":"2024-07-31T19:01:34.014Z","updated_at":"2026-01-07T13:16:30.764Z","avatar_url":"https://github.com/cirruslabs.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Cirrus CLI\n\n[![Build Status](https://api.cirrus-ci.com/github/cirruslabs/cirrus-cli.svg?branch=master)](https://cirrus-ci.com/github/cirruslabs/cirrus-cli)\n\nCirrus CLI is a tool for running containerized tasks reproducibly in any environment. Most commonly, Cirrus tasks are used as part of continuous integration workflows \nbut can also be used as part of local development process as a [hermetic replacement of helper scripts/Makefiles](https://medium.com/cirruslabs/using-cirrus-cli-instead-of-makefiles-for-generating-grpc-87b949a67449).\nCirrus CLI runs your tasks locally the same way they are executed in CI or on your colleague's machine. Immutability of containers ensures\nthe tasks will be executed the same way years from now regardless what versions of packages you'll have locally.\n\n![Cirrus CLI Demo](images/cirrus-cli-demo.gif)\n\n## Installation\n\n* [Homebrew](INSTALL.md#homebrew)\n* [Debian-based distributions](INSTALL.md#debian-based-distributions) (Debian, Ubuntu, etc.)\n* [RPM-based distributions](INSTALL.md#rpm-based-distributions) (Fedora, CentOS, etc.)\n* [Prebuilt Binary](INSTALL.md#prebuilt-binary)\n* [Golang](INSTALL.md#golang)\n* CI integrations\n  * [GitHub Actions](INSTALL.md#github-actions)\n  * [Travis CI](INSTALL.md#travis-ci)\n  * [Circle CI](INSTALL.md#circle-ci)\n  * [TeamCity](INSTALL.md#teamcity)\n  * [Cloud Build](INSTALL.md#cloud-build)\n  * [Cirrus CI](INSTALL.md#cirrus-ci)\n\n## Usage\n\nCirrus CLI reuses the [same YAML configuration format as Cirrus CI](https://cirrus-ci.org/guide/writing-tasks/) which allows to\nreuse a large [list of examples](https://cirrus-ci.org/examples/) created by Cirrus CI community.\n\n**Note:** Cirrus CLI can be used in any environment that has [Docker](INSTALL.md#docker) or [Podman](INSTALL.md#podman) installed. It can be your laptop or any CI system you already have\nlike Jenkins, GitHub Actions, Travis CI, etc. With Cirrus CLI it's no longer a requirement to use Cirrus CI in order to benefit from Cirrus\nconfiguration format that we (Cirrus Labs) have crafted for so long and really proud of.\n\nHere is an example of `.cirrus.yml` configuration file for testing a Go application with several Go versions:\n\n```yaml\ntask:\n  env:\n    matrix:\n      VERSION: 1.21\n      VERSION: 1.22\n  name: Tests (Go $VERSION)\n  container:\n    image: golang:$VERSION\n  modules_cache:\n    fingerprint_script: cat go.sum\n    folder: $GOPATH/pkg/mod\n  get_script: go get ./...\n  build_script: go build ./...\n  test_script: go test ./...\n```\n\nNote: `container:` implies the `amd64` architecture. If you're running on `arm64`, please use with the `arm_container` instead.\n\n### Running Cirrus Tasks\n\nTo run Cirrus tasks, simply switch to a directory where the `.cirrus.yml` is located and run:\n                                \n```shell script\ncirrus run\n```\n\nBy default, working directory will be `rsync`ed into a container while respecting `.gitignore`\nconfiguration. This makes sure Cirrus Tasks are executed from a clean state only with source code\nchanges.\n\nIn case `rsync`-ing the whole working directory is too costly, you can pass a `--dirty` flag which \nwill result in all operations being done against the actual working directory (and not it's `rsync`ed copy):\n\n```shell script\ncirrus run --dirty Lint\n```\n\nSince most linters and code-analysis tools are read-only by their nature there is no need in extra precautions and\nthe potentially costly `rsync`-ing can be safely avoided.\n\nIt is also possible to run a particular task by name:\n                          \n```shell script\ncirrus run \"Tests (Go 1.15)\"\n```\n\nOr pass some extra environment variables with `-e` flag:\n\n```shell script\ncirrus run -e CIRRUS_TAG=\"test-release\" Release\n```\n\n**Note:** Cirrus CLI only supports [Linux `container`](https://cirrus-ci.org/guide/linux/#linux-containers) and\n[`macos_instance` VMs](https://cirrus-ci.org/guide/macOS/) at the moment. Linux containers support the\n[Dockerfile as a CI environment](https://cirrus-ci.org/guide/docker-builder-vm/#dockerfile-as-a-ci-environment) feature.\n\n### Validating Cirrus Configuration\n\nTo validate a Cirrus configuration, simply switch to a directory where the `.cirrus.yml` is located and run:\n\n```shell script\ncirrus validate\n```\n\n## Caching\n\nBy default, Cirrus CLI stores blob artifacts produced by the [cache instruction](https://cirrus-ci.org/guide/writing-tasks/#cache-instruction)\nin the [user-specific cached data folder](https://golang.org/pkg/os/#UserCacheDir). [Similar to Cirrus Cloud](https://cirrus-ci.org/guide/writing-tasks/#http-cache)\nthe CLI can use a caching HTTP server for more efficient sharing of cached artifacts between tasks executed on different physical hosts.\n\nCaching HTTP server should support a single `/\u003ckey\u003e` REST endpoint with `PUT`, `GET` and `HEAD` methods available for\nuploading, downloading and checking availability of a cached artifact under `\u003ckey\u003e` key respectively. There are reference\nimplementations of such HTTP servers for [Google Cloud Storage](https://github.com/cirruslabs/google-storage-proxy) and\n[AWS S3](https://github.com/cirruslabs/aws-s3-proxy) and [Azure's Blob Storage](https://github.com/cirruslabs/azure-blob-storage-proxy).\n\nTo start using your own HTTP caching server simply pass it's hostname as `CIRRUS_HTTP_CACHE_HOST` to [`run` command](#running-cirrus-tasks):\n\n```bash\ncirrus run --environment CIRRUS_HTTP_CACHE_HOST=http-cache-host.internal:8080\n```\n\n## Security\n\nCirrus CLI aims to run in different environments, but in some environments we choose to provide more usability at the cost of some security trade-offs:\n\n* SELinux\n  * both the task container and the helper container (that copies the project directory into a per-task container volume using `rsync`) run unconfined\n\nPlease [open an issue](https://github.com/cirruslabs/cirrus-cli/issues/new) if your use-case requires a different approach.\n\n## FAQ\n\n\u003cdetails\u003e\n \u003csummary\u003eWhat is the relationship between Cirrus CI and Cirrus CLI?\u003c/summary\u003e\n \n Cirrus CI was [released in the early 2018](https://medium.com/cirruslabs/introducing-cirrus-ci-a75cd1f49af0) with an idea\n to bring some innovation to CI space. A lot of things have changed in CI-as-a-service space since then but Cirrus CI\n pioneered many ideas in CI-as-a-service space including per-second billing and support for Linux, Windows and macOS all together.\n \n Over the past two and a half years we heard only positive feedback about Cirrus CI's YAML configuration format. Users liked how\n concise their configuration looked and that it was easy to reason about.\n \n Another feedback we heard from users was that it's hard to migrate from one CI to another. There is a need to rewrite CI configurations\n from one format into another that basically still locks into another vendor.\n \n And now in 2020 with Cirrus CLI we are trying to solve the \"vendor lock\" problem by popularizing Cirrus configuration format\n and building community around it. Stay tuned for the upcoming option to use [Starlark templates instead of YAML](https://github.com/cirruslabs/cirrus-cli/issues/53)!\n \n Think of Cirrus CLI as an executor of Cirrus Tasks on a single machine only in Docker containers for simple CI scenarious.\n And Cirrus CI as an option for more specific cases where Cirrus Tasks can be executed in containers and VMs using \n a [variety of supported compute services](https://cirrus-ci.org/guide/supported-computing-services/) or\n using a [managed infrastructure with per-second billing](https://cirrus-ci.org/pricing/#compute-credits).\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirruslabs%2Fcirrus-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirruslabs%2Fcirrus-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirruslabs%2Fcirrus-cli/lists"}