openfaas/faas-cli

faas-cli

faas-cli is the official CLI for OpenFaaS

Run a demo with faas-cli --help

The CLI can be used to build and deploy functions to OpenFaaS. 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.

New user? See how it works: Morning coffee with the faas-cli Already an OpenFaaS user? Try 5 tips and tricks for the OpenFaaS CLI

Get started: Install the CLI

You 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.

Utility script with curl:

$ curl -sSL https://cli.openfaas.com | sudo sh

Non-root with curl (requires further actions as advised after downloading):

$ curl -sSL https://cli.openfaas.com | sh

Via brew:

$ brew install faas-cli

Note: The brew release may not run the latest minor release but is updated regularly.

Via npm (coming soon):

$ npm install --global @openfaas/faas-cli

Note: See npm specific installation instructions and usage in the npm README.md

Windows

To install the faas-cli on Windows go to Releases and download the latest faas-cli.exe.

Or in PowerShell:

$version = (Invoke-WebRequest "https://api.github.com/repos/openfaas/faas-cli/releases/latest" | ConvertFrom-Json)[0].tag_name
(New-Object System.Net.WebClient).DownloadFile("https://github.com/openfaas/faas-cli/releases/download/$version/faas-cli.exe", "faas-cli.exe")

Build from source

The contributing guide has instructions for building from source and for configuring a Golang development environment.

Run the CLI

The main commands supported by the CLI are:

• faas-cli new - creates a new function via a template in the current directory

• faas-cli login - stores basic auth credentials for OpenFaaS gateway (supports multiple gateways)

• faas-cli logout - removes basic auth credentials for a given gateway

• faas-cli up - a combination of build/push and deploy

• faas-cli build - builds Docker images from the supported language types

• faas-cli push - pushes Docker images into a registry

• faas-cli deploy - deploys the functions into a local or remote OpenFaaS gateway

• faas-cli publish - build and push multi-arch images for CI and release artifacts

• faas-cli remove - removes the functions from a local or remote OpenFaaS gateway

• faas-cli invoke - invokes the functions and reads from STDIN for the body of the request

• faas-cli store - allows browsing and deploying OpenFaaS store functions

• faas-cli secret - manage secrets for your functions

• faas-cli pro auth - initiates an OAuth2 authorization flow to obtain a token

• faas-cli registry-login - generate registry auth file in correct format by providing username and password for docker/ecr/self hosted registry

The default gateway URL of 127.0.0.1:8080 can be overridden in three places including an environmental variable.

• 1st priority --gateway flag
• 2nd priority --yaml / -f flag or stack.yaml if in current directory
• 3rd priority OPENFAAS_URL environmental variable

For Kubernetes users you may want to set this in your .bash_rc file:

export OPENFAAS_URL=http://127.0.0.1:31112

Did you know? By setting FAAS_DEBUG=1, the CLI will print out the HTTP request that it's making to the OpenFaaS Gateway.

Advanced commands:

• faas-cli template pull - pull in templates from a remote git repository Detailed Documentation

The default template URL of https://github.com/openfaas/templates.git can be overridden in two places including an environmental variable

• 1st priority CLI input
• 2nd priority OPENFAAS_TEMPLATE_URL environmental variable

Help for all of the commands supported by the CLI can be found by running:

• faas-cli help or faas-cli [command] --help

You can chose between using a programming language template where you only need to provide a handler file, or a Docker that you can build yourself.

faas-cli pro auth

The auth command is only licensed for OpenFaaS Pro customers.

Use the auth command to obtain a JWT to use as a Bearer token.

code grant - default

Use this flow to obtain a token for interactive use from your workstation.

The code grant flow uses the PKCE extension.

At 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.

Example:

faas-cli pro auth \
  --auth-url https://tenant0.eu.auth0.com/authorize \
  --token-url https://tenant0.eu.auth0.com/oauth/token \
  --audience http://gw.example.com \
  --client-id "${OAUTH_CLIENT_ID}"

client_credentials grant

Use this flow for machine to machine communication such as when you want to deploy a function to a gateway that uses OAuth2 / OIDC.

Example:

faas-cli pro auth \
  --grant client_credentials \
  --auth-url https://tenant0.eu.auth0.com/oauth/token \
  --client-id "${OAUTH_CLIENT_ID}" \
  --client-secret "${OAUTH_CLIENT_SECRET}"\
  --audience http://gw.example.com

Environment variable substitution

The 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.

Here 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.

functions:
  url-ping:
    lang: python
    handler: ./sample/url-ping
    image: ${DOCKER_USER:-exampleco}/faas-url-ping:0.2

Use the default:

$ faas-cli build
$ DOCKER_USER="" faas-cli build

Override with "alexellis2":

$ DOCKER_USER="alexellis2" faas-cli build

See also: envsubst package from Drone.

Build templates

Command: faas-cli new FUNCTION_NAME --lang python/node/go/ruby/Dockerfile/etc

In your YAML you can also specify lang: node/python/go/csharp/ruby

• Supports common languages

• Quick and easy - just write one file

• Specify dependencies on Gemfile / requirements.txt or package.json etc

• Customise the provided templates

Perhaps you need to have gcc or another dependency in your Python template? That's not a problem.

You 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.

See also: faas-cli new --help

Third-party community templates

Templates created and maintained by a third-party can be added to your local system using the faas-cli template pull command.

Read more on community templates here.

Templates store

The template store is a great way to find official, incubator and third-party templates.

Find templates with: faas-cli template store list

Note: You can set your own custom store location with --url flag or set OPENFAAS_TEMPLATE_STORE_URL environmental variable

To 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

To 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

Note: This feature is still in experimental stage and in the future the CLI verbs might be changed

HMAC

It 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.

$ echo -n OpenFaaS | faas-cli invoke env --sign X-Hub-Signature --key yoursecret

Results in the following header being added:

Http_X_Hub_Signature=sha1=2fc4758f8755f57f6e1a59799b56f8a6cf33b13f

Docker image as a function

Specify lang: Dockerfile if you want the faas-cli to execute a build or skip_build: true for pre-built images.

• Ultimate versatility and control
• Package anything
• If you are using a stack file add the skip_build: true attribute
• Use one of the samples as a basis

Read the blog post/tutorial: Turn Any CLI into a Function with OpenFaaS

faas-cli registry-login

This command allows to generate the registry auth file in the correct format in the location ./credentials/config.json

Prepare your Docker registry (if not using AWS ECR)

If you are using Dockerhub you only need to supply your --username and --password-stdin (or --password, but this leaves the password in history).

faas-cli registry-login --username <your-registry-username> --password-stdin
(then enter your password and use ctrl+d to finish input)

You could also have you password in a file, or environment variable and echo/cat this instead of entering interactively If you are using a different registry (that is not ECR) then also provide a --server as well.

Prepare your Docker registry (if using AWS ECR)

faas-cli registry-login --ecr --region <your-aws-region> --account-id <your-account-id>

Private registries

• For Kubernetes - see here

• For faasd - see here

Use faas-cli in CI environments

If you're running faas-cli in a CI environment like Github Actions, CircleCI, or Travis, chances are you get the env var CI set to true.

If 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).

This 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. CI environments like Github Actions require you to use Docker images having a root user. Learn more about it here.

Use a YAML stack file

Read the YAML reference guide in the OpenFaaS docs.

Quick guide

A YAML stack file groups functions together and also saves on typing.

You 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.

Here is an example file using the stack.yaml file included in the repository.

provider:
  name: openfaas
  gateway: http://127.0.0.1:8080

functions:
  url-ping:
    lang: python
    handler: ./sample/url-ping
    image: alexellis2/faas-urlping

This 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.

• Build the files in the .yml file:

$ faas-cli build

-f specifies the file or URL to download your YAML file from. The long version of the -f flag is: --yaml.

You can also download over HTTP(s), for example:

$ faas-cli build -f https://raw.githubusercontent.com/openfaas/store-functions/master/stack.yml

Docker along with a Python template will be used to build an image named alexellis2/faas-urlping.

• Deploy your function

Now you can use the following command to deploy your function(s):

$ faas-cli deploy

Access functions with curl

You can initiate a HTTP POST via curl:

• with the -d flag i.e. -d "my data here"
• or with --data-binary @filename.txt to send a whole file including newlines
• if you want to pass input from STDIN then use --data-binary @-

$ curl -d '{"hello": "world"}' http://127.0.0.1:8080/function/nodejs-echo
{ nodeVersion: 'v6.9.1', input: '{"hello": "world"}' }

$ curl --data-binary @README.md http://127.0.0.1:8080/function/nodejs-echo

$ uname -a | curl http://127.0.0.1:8080/function/nodejs-echo--data-binary @-

For further instructions on the manual CLI flags (without using a YAML file) read manual_cli.md

Environment variable overrides

• OPENFAAS_TEMPLATE_URL - to set the default URL to pull templates from
• OPENFAAS_PREFIX - for use with faas-cli new - this can act in place of --prefix
• OPENFAAS_URL - to override the default gateway URL
• OPENFAAS_REMOTE_BUILDER - default value for --remote-builder
• OPENFAAS_PAYLOAD_SECRET - default value for --payload-secret
• OPENFAAS_BUILDER_PUBLIC_KEY - builder public key as a literal value, or a path to a file containing raw base64 or the JSON response from /public-key
• OPENFAAS_BUILDER_KEY_ID - default value for --builder-key-id when pinning a raw base64 public key file
• OPENFAAS_CONFIG - to override the location of the configuration folder, which contains auth configuration.
• 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.

For encrypted remote-builder builds, the safest option is to read the builder public key from a file rather than putting the key inline on the command line. The file can contain either:

• the raw base64 public key
• or the JSON document returned by GET /public-key

The --builder-public-key flag and OPENFAAS_BUILDER_PUBLIC_KEY env var also accept a literal value directly. If the value points to an existing file, the CLI reads the file; otherwise it treats the value itself as the key material.

Basic remote-builder example using automatic GET /public-key discovery:

faas-cli publish \
  --remote-builder http://127.0.0.1:8081 \
  --payload-secret /var/openfaas/secrets/payload-secret \
  -f stack.yml

If any functions in stack.yml define build_secrets, the CLI will fetch /public-key from the builder automatically unless --builder-public-key is set.

Contributing

See contributing guide.

License

Portions of this project are licensed under the OpenFaaS Pro EULA.

The remaining source unless annotated is licensed under the MIT License.