{"id":13424984,"url":"https://github.com/openfaas/faas-cli","last_synced_at":"2025-05-14T05:10:49.350Z","repository":{"id":20446402,"uuid":"87833671","full_name":"openfaas/faas-cli","owner":"openfaas","description":"Official CLI for OpenFaaS","archived":false,"fork":false,"pushed_at":"2025-04-15T12:05:11.000Z","size":24198,"stargazers_count":804,"open_issues_count":63,"forks_count":223,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-15T13:22:12.582Z","etag":null,"topics":["cli","docker","faas","faas-cli","golang","hacktoberfest","handler","lambda","nodejs","python","templating"],"latest_commit_sha":null,"homepage":"https://www.openfaas.com/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openfaas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-10T16:33:04.000Z","updated_at":"2025-04-15T12:01:58.000Z","dependencies_parsed_at":"2023-09-27T15:13:57.205Z","dependency_job_id":"ebd50745-f323-47dc-b659-ac43f7a4331a","html_url":"https://github.com/openfaas/faas-cli","commit_stats":{"total_commits":936,"total_committers":74,"mean_commits":12.64864864864865,"dds":"0.48290598290598286","last_synced_commit":"6bb351bade10f1269de19dcaef5e19e679df22f0"},"previous_names":["alexellis/faas-cli"],"tags_count":219,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfaas%2Ffaas-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfaas%2Ffaas-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfaas%2Ffaas-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfaas%2Ffaas-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openfaas","download_url":"https://codeload.github.com/openfaas/faas-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"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":["cli","docker","faas","faas-cli","golang","hacktoberfest","handler","lambda","nodejs","python","templating"],"created_at":"2024-07-31T00:01:01.530Z","updated_at":"2025-05-14T05:10:49.227Z","avatar_url":"https://github.com/openfaas.png","language":"Go","readme":"## faas-cli\n\n[![Build Status](https://github.com/openfaas/faas-cli/workflows/build/badge.svg?branch=master)](https://github.com/openfaas/faas-cli/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/openfaas/faas-cli)](https://goreportcard.com/report/github.com/openfaas/faas-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![OpenFaaS](https://img.shields.io/badge/openfaas-serverless-blue.svg)](https://www.openfaas.com)\n\nfaas-cli is the official CLI for [OpenFaaS](https://github.com/openfaas/faas)\n\nRun a demo with `faas-cli --help`\n\nThe CLI can be used to build and deploy functions to [OpenFaaS](https://github.com/openfaas/faas). You can build OpenFaaS functions from a set of supported language templates (such as Node.js, Python, CSharp and Ruby). That means you just write a handler file such as (handler.py/handler.js) and the CLI does the rest to create a Docker image.\n\nNew user? See how it works: [Morning coffee with the faas-cli](https://blog.alexellis.io/quickstart-openfaas-cli/)\nAlready an OpenFaaS user? Try [5 tips and tricks for the OpenFaaS CLI](https://www.openfaas.com/blog/five-cli-tips/)\n\n### Get started: Install the CLI\n\nYou can install the CLI with a `curl` utility script, `brew` or by downloading the binary from the releases page. Once installed you'll get the `faas-cli` command and `faas` alias.\n\nUtility script with `curl`:\n\n```\n$ curl -sSL https://cli.openfaas.com | sudo sh\n```\n\nNon-root with curl (requires further actions as advised after downloading):\n\n```\n$ curl -sSL https://cli.openfaas.com | sh\n```\n\nVia brew:\n\n```\n$ brew install faas-cli\n```\n\nNote: The `brew` release may not run the latest minor release but is updated regularly.\n\nVia npm (coming soon):\n\n```\n$ npm install --global @openfaas/faas-cli\n```\n\nNote: See `npm` specific installation instructions and usage in the [npm README.md](https://github.com/openfaas/faas-cli/blob/master/npm/README.md)\n\n#### Windows\n\nTo install the faas-cli on Windows go to [Releases](https://github.com/openfaas/faas-cli/releases) and download the latest faas-cli.exe.\n\nOr in PowerShell:\n\n```\n$version = (Invoke-WebRequest \"https://api.github.com/repos/openfaas/faas-cli/releases/latest\" | ConvertFrom-Json)[0].tag_name\n(New-Object System.Net.WebClient).DownloadFile(\"https://github.com/openfaas/faas-cli/releases/download/$version/faas-cli.exe\", \"faas-cli.exe\")\n```\n\n#### Build from source\n\nThe [contributing guide](CONTRIBUTING.md) has instructions for building from source and for configuring a Golang development environment.\n\n### Run the CLI\n\nThe main commands supported by the CLI are:\n\n* `faas-cli new` - creates a new function via a template in the current directory\n* `faas-cli login` - stores basic auth credentials for OpenFaaS gateway (supports multiple gateways)\n* `faas-cli logout` - removes basic auth credentials for a given gateway\n\n* `faas-cli up` - a combination of `build/push and deploy`\n\n* `faas-cli build` - builds Docker images from the supported language types\n* `faas-cli push` - pushes Docker images into a registry\n* `faas-cli deploy` - deploys the functions into a local or remote OpenFaaS gateway\n\n* `faas-cli publish` - build and push multi-arch images for CI and release artifacts\n\n* `faas-cli remove` - removes the functions from a local or remote OpenFaaS gateway\n* `faas-cli invoke` - invokes the functions and reads from STDIN for the body of the request\n* `faas-cli store` - allows browsing and deploying OpenFaaS store functions\n\n* `faas-cli secret` - manage secrets for your functions\n\n* `faas-cli pro auth` - initiates an OAuth2 authorization flow to obtain a token\n\n* `faas-cli registry-login` - generate registry auth file in correct format by providing username and password for docker/ecr/self hosted registry\n\nThe default gateway URL of `127.0.0.1:8080` can be overridden in three places including an environmental variable.\n\n* 1st priority `--gateway` flag\n* 2nd priority `--yaml` / `-f` flag or `stack.yaml` if in current directory\n* 3rd priority `OPENFAAS_URL` environmental variable\n\nFor Kubernetes users you may want to set this in your `.bash_rc` file:\n\n```\nexport OPENFAAS_URL=http://127.0.0.1:31112\n```\n\n\u003e Did you know? By setting `FAAS_DEBUG=1`, the CLI will print out the HTTP request that it's making to the OpenFaaS Gateway.\n\nAdvanced commands:\n\n* `faas-cli template pull` - pull in templates from a remote git repository [Detailed Documentation](guide/TEMPLATE.md)\n\nThe default template URL of `https://github.com/openfaas/templates.git` can be overridden in two places including an environmental variable\n\n* 1st priority CLI input\n* 2nd priority `OPENFAAS_TEMPLATE_URL` environmental variable\n\nHelp for all of the commands supported by the CLI can be found by running:\n\n* `faas-cli help` or `faas-cli [command] --help`\n\nYou can chose between using a [programming language template](https://github.com/openfaas/templates/tree/master/template) where you only need to provide a handler file, or a Docker that you can build yourself.\n\n#### `faas-cli pro auth`\n\nThe `auth` command is only licensed for OpenFaaS Pro customers.\n\nUse the `auth` command to obtain a JWT to use as a Bearer token.\n\n##### `code` grant - default\n\nUse this flow to obtain a token for interactive use from your workstation.\n\nThe code grant flow uses the PKCE extension.\n\nAt this time the `token` cannot be saved or retained in your OpenFaaS config file. You can pass the token using a CLI flag of `--token=$TOKEN`.\n\nExample:\n\n```sh\nfaas-cli pro auth \\\n  --auth-url https://tenant0.eu.auth0.com/authorize \\\n  --token-url https://tenant0.eu.auth0.com/oauth/token \\\n  --audience http://gw.example.com \\\n  --client-id \"${OAUTH_CLIENT_ID}\"\n```\n\n##### `client_credentials` grant\n\nUse this flow for machine to machine communication such as when you want to deploy a function to a gateway that uses OAuth2 / OIDC.\n\nExample:\n\n```sh\nfaas-cli pro auth \\\n  --grant client_credentials \\\n  --auth-url https://tenant0.eu.auth0.com/oauth/token \\\n  --client-id \"${OAUTH_CLIENT_ID}\" \\\n  --client-secret \"${OAUTH_CLIENT_SECRET}\"\\\n  --audience http://gw.example.com\n```\n\n##### Environment variable substitution\n\nThe CLI supports the use of `envsubst`-style templates. This means that you can have a single file with multiple configuration options such as for different user accounts, versions or environments.\n\nHere is an example use-case, in your project there is an official and a development Docker Hub username/account. For the CI server images are always pushed to `exampleco`, but in development you may want to push to your own account such as `alexellis2`.\n\n```yaml\nfunctions:\n  url-ping:\n    lang: python\n    handler: ./sample/url-ping\n    image: ${DOCKER_USER:-exampleco}/faas-url-ping:0.2\n```\n\nUse the default:\n\n```sh\n$ faas-cli build\n$ DOCKER_USER=\"\" faas-cli build\n```\n\nOverride with \"alexellis2\":\n\n```\n$ DOCKER_USER=\"alexellis2\" faas-cli build\n```\n\nSee also: [envsubst package from Drone](https://github.com/drone/envsubst).\n\n#### Build templates\n\nCommand: `faas-cli new FUNCTION_NAME --lang python/node/go/ruby/Dockerfile/etc`\n\nIn your YAML you can also specify `lang: node/python/go/csharp/ruby`\n\n* Supports common languages\n* Quick and easy - just write one file\n* Specify dependencies on Gemfile / requirements.txt or package.json etc\n\n* Customise the provided templates\n\nPerhaps you need to have [`gcc` or another dependency](https://github.com/faas-and-furious/faas-office-sample) in your Python template? That's not a problem.\n\nYou can customise the Dockerfile or code for any of the templates. Just create a new directory and copy in the templates folder from this repository. The templates in your current working directory are always used for builds.\n\nSee also: `faas-cli new --help`\n\n**Third-party community templates**\n\nTemplates created and maintained by a third-party can be added to your local system using the `faas-cli template pull` command.\n\nRead more on [community templates here](guide/TEMPLATE.md).\n\n**Templates store**\n\nThe template store is a great way to find official, incubator and third-party templates.\n\nFind templates with: `faas-cli template store list`\n\n\u003e Note: You can set your own custom store location with `--url` flag or set `OPENFAAS_TEMPLATE_STORE_URL` environmental variable\n\nTo pull templates from the store just write the name of the template you want `faas-cli template store pull golang-middleware` or the repository and name `faas-cli template store pull openfaas/golang-middleware`\n\nTo get more detail on a template just use the `template store describe` command and pick a template of your choice, example with `go` would look like this `faas-cli template store describe golang-middleware`\n\n\u003e Note: This feature is still in experimental stage and in the future the CLI verbs might be changed\n\n#### HMAC\n\nIt is possible to sign a `faas-cli invoke` request using a sha1 HMAC.  To do this, the name of a header to hold the code during transmission should be specified using the `--sign` flag, and the shared secret used to hash the message should be provided through `--key`. E.g.\n\n```sh\n$ echo -n OpenFaaS | faas-cli invoke env --sign X-Hub-Signature --key yoursecret\n```\n\nResults in the following header being added:\n\n```\nHttp_X_Hub_Signature=sha1=2fc4758f8755f57f6e1a59799b56f8a6cf33b13f\n```\n\n#### Docker image as a function\n\nSpecify `lang: Dockerfile` if you want the faas-cli to execute a build or `skip_build: true` for pre-built images.\n\n* Ultimate versatility and control\n* Package anything\n* If you are using a stack file add the `skip_build: true` attribute\n* Use one of the [samples as a basis](https://github.com/openfaas/faas/tree/master/sample-functions)\n\nRead the blog post/tutorial: [Turn Any CLI into a Function with OpenFaaS](https://blog.alexellis.io/cli-functions-with-openfaas/)\n\n#### `faas-cli registry-login`\n\nThis command allows to generate the registry auth file in the correct format in the location `./credentials/config.json`\n\n#### Prepare your Docker registry (if not using AWS ECR)\n\nIf you are using Dockerhub you only need to supply your --username and --password-stdin (or --password, but this leaves the password in history).\n\n```bash\nfaas-cli registry-login --username \u003cyour-registry-username\u003e --password-stdin\n(then enter your password and use ctrl+d to finish input)\n```\n\nYou could also have you password in a file, or environment variable and echo/cat this instead of entering interactively\nIf you are using a different registry (that is not ECR) then also provide a `--server` as well.\n\n#### Prepare your Docker registry (if using AWS ECR)\n```\nfaas-cli registry-login --ecr --region \u003cyour-aws-region\u003e --account-id \u003cyour-account-id\u003e\n```\n\n### Private registries\n\n* For Kubernetes - [see here](https://docs.openfaas.com/deployment/kubernetes/#use-a-private-registry-with-kubernetes)\n\n* For faasd - [see here](https://github.com/openfaas/faasd)\n\n### Use faas-cli in CI environments\n\nIf you're running faas-cli in a CI environment like [Github Actions](https://docs.github.com/en/free-pro-team@latest/actions/reference/environment-variables#default-environment-variables), [CircleCI](https://circleci.com/docs/2.0/env-vars/#built-in-environment-variables), or [Travis](https://docs.travis-ci.com/user/environment-variables/#default-environment-variables), chances are you get the env var `CI` set to true.\n\nIf the `CI` env var is set to `true` or `1`, faas-cli change the location of the OpenFaaS config from the default `~/.openfaas/config.yml` to `.openfaas/config.yml` with elevated permissions for the `config.yml` and the shrinkwrapped `build` dir (if there is one).\n\nThis is really useful when running faas-cli as a container image. The recommended image type to use in a CI environment is the root variant, tagged with `-root` suffix.\nCI environments like Github Actions require you to use Docker images having a root user. Learn more about it [here](https://docs.github.com/en/free-pro-team@latest/actions/creating-actions/dockerfile-support-for-github-actions#user).\n\n### Use a YAML stack file\n\nRead the [YAML reference guide in the OpenFaaS docs](https://docs.openfaas.com/reference/yaml/).\n\n#### Quick guide\n\nA YAML stack file groups functions together and also saves on typing.\n\nYou can define individual functions or a set of them within a YAML file. This makes the CLI easier to use and means you can use this file to deploy to your OpenFaaS instance.  By default the faas-cli will attempt to load `stack.yaml` from the current directory.\n\nHere is an example file using the `stack.yaml` file included in the repository.\n\n```yaml\nprovider:\n  name: openfaas\n  gateway: http://127.0.0.1:8080\n\nfunctions:\n  url-ping:\n    lang: python\n    handler: ./sample/url-ping\n    image: alexellis2/faas-urlping\n```\n\nThis url-ping function is defined in the sample/url-ping folder makes use of Python. All we had to do was to write a `handler.py` file and then to list off any Python modules in `requirements.txt`.\n\n* Build the files in the .yml file:\n\n```sh\n$ faas-cli build\n```\n\n\u003e `-f` specifies the file or URL to download your YAML file from. The long version of the `-f` flag is: `--yaml`.\n\nYou can also download over HTTP(s), for example:\n\n```sh\n$ faas-cli build -f https://raw.githubusercontent.com/openfaas/store-functions/master/stack.yml\n```\n\nDocker along with a Python template will be used to build an image named alexellis2/faas-urlping.\n\n* Deploy your function\n\nNow you can use the following command to deploy your function(s):\n\n```sh\n$ faas-cli deploy\n```\n\n### Access functions with `curl`\n\nYou can initiate a HTTP POST via `curl`:\n\n* with the `-d` flag i.e. `-d \"my data here\"`\n* or with `--data-binary @filename.txt` to send a whole file including newlines\n* if you want to pass input from STDIN then use `--data-binary @-`\n\n```sh\n$ curl -d '{\"hello\": \"world\"}' http://127.0.0.1:8080/function/nodejs-echo\n{ nodeVersion: 'v6.9.1', input: '{\"hello\": \"world\"}' }\n\n$ curl --data-binary @README.md http://127.0.0.1:8080/function/nodejs-echo\n\n$ uname -a | curl http://127.0.0.1:8080/function/nodejs-echo--data-binary @-\n```\n\n\u003e For further instructions on the manual CLI flags (without using a YAML file) read [manual_cli.md](https://github.com/openfaas/faas-cli/blob/master/MANUAL_CLI.md)\n\n### Environment variable overrides\n\n* `OPENFAAS_TEMPLATE_URL` - to set the default URL to pull templates from\n* `OPENFAAS_PREFIX` - for use with `faas-cli new` - this can act in place of `--prefix`\n* `OPENFAAS_URL` - to override the default gateway URL\n* `OPENFAAS_CONFIG` - to override the location of the configuration folder, which contains auth configuration.\n* `CI` - to override the location of the configuration folder, when true, the configuration folder is `.openfaas` in the current working directory. This value is ignored if `OPENFAAS_CONFIG` is set.\n\n### Contributing\n\nSee [contributing guide](https://github.com/openfaas/faas-cli/blob/master/CONTRIBUTING.md).\n\n### License\n\nPortions of this project are licensed under the OpenFaaS Pro EULA.\n\nThe remaining source unless annotated is licensed under the MIT License.\n","funding_links":[],"categories":["Go","Devops"],"sub_categories":["Jenkins"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfaas%2Ffaas-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenfaas%2Ffaas-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfaas%2Ffaas-cli/lists"}