CLI Command Reference

------------------------------------------------------------------------------

CREATE


NAME
	func create - Create a function project.

SYNOPSIS
	func create [-l|--language] [-t|--template] [-r|--repository]
	            [-c|--confirm]  [-v|--verbose]  [path]

DESCRIPTION
	Creates a new function project.

	  $ func create -l node -t http

	Creates a function in the current directory '.' which is written in the
	language/runtime 'node' and handles HTTP events.

	If [path] is provided, the function is initialized at that path, creating
	the path if necessary.

	To complete this command interactively, use --confirm (-c):
	  $ func create -c

	Available Language Runtimes and Templates:
	  Language     Template
	  --------     --------
	  go           cloudevents
	  go           http
	  go           lkingland/e2e
	  node         cloudevents
	  node         http
	  python       cloudevents
	  python       http
	  quarkus      cloudevents
	  quarkus      http
	  runtime      lkingland/template
	  rust         cloudevents
	  rust         http
	  springboot   cloudevents
	  springboot   http
	  typescript   cloudevents
	  typescript   http
	  

	To install more language runtimes and their templates see 'func repository'.


EXAMPLES
	o Create a Node.js function (the default language runtime) in the current
	  directory (the default path) which handles http events (the default
	  template).
	  $ func create

	o Create a Node.js function in the directory 'myfunc'.
	  $ func create myfunc

	o Create a Go function which handles CloudEvents in ./myfunc.
	  $ func create -l go -t cloudevents myfunc
		

Usage:
  func create [flags]

Flags:
  -c, --confirm             Prompt to confirm all options interactively (Env: $FUNC_CONFIRM)
  -h, --help                help for create
  -l, --language string     Language Runtime (see help text for list) (Env: $FUNC_LANGUAGE)
  -r, --repository string   URI to a Git repository containing the specified template (Env: $FUNC_REPOSITORY)
  -t, --template string     Function template. (see help text for list) (Env: $FUNC_TEMPLATE) (default "http")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

BUILD

Build a function project as a container image

This command builds the function project in the current directory or in the directory
specified by --path. The result will be a container image that is pushed to a registry.
The func.yaml file is read to determine the image name and registry.
If the project has not already been built, either --registry or --image must be provided
and the image name is stored in the configuration file.


Usage:
  func build [flags]

Examples:

# Build from the local directory, using the given registry as target.
# The full image name will be determined automatically based on the
# project directory name
func build --registry quay.io/myuser

# Build from the local directory, specifying the full image name
func build --image quay.io/myuser/myfunc

# Re-build, picking up a previously supplied image name from a local func.yml
func build

# Build using s2i instead of Buildpacks
func build --builder=s2i

# Build with a custom buildpack builder
func build --builder=pack --builder-image cnbs/sample-builder:bionic


Flags:
  -b, --builder string         build strategy to use when creating the underlying image. Currently supported build strategies are "pack" and "s2i". (default "pack")
      --builder-image string   builder image, either an as a an image name or a mapping name.
                               Specified value is stored in func.yaml (as 'builder' field) for subsequent builds. ($FUNC_BUILDER_IMAGE)
  -c, --confirm                Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)
  -h, --help                   help for build
  -i, --image string           Full image name in the form [registry]/[namespace]/[name]:[tag] (optional). This option takes precedence over --registry (Env: $FUNC_IMAGE)
  -p, --path string            Path to the project directory (Env: $FUNC_PATH) (default ".")
      --platform string        Target platform to build (e.g. linux/amd64).
  -u, --push                   Attempt to push the function image after being successfully built
  -r, --registry string        Registry + namespace part of the image to build, ex 'quay.io/myuser'.  The full image name is automatically determined based on the local directory name. If not provided the registry will be taken from func.yaml (Env: $FUNC_REGISTRY)

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

CONFIG

Configure a function

Interactive prompt that allows configuration of Volume mounts, Environment
variables, and Labels for a function project present in the current directory
or from the directory specified with --path.


Usage:
  func config [flags]
  func config [command]

Available Commands:
  envs        List and manage configured environment variable for a function
  labels      List and manage configured labels for a function
  volumes     List and manage configured volumes for a function

Flags:
  -h, --help          help for config
  -p, --path string   Path to the project directory (Env: $FUNC_PATH) (default ".")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

Use "func config [command] --help" for more information about a command.

------------------------------------------------------------------------------

CREATE


NAME
	func create - Create a function project.

SYNOPSIS
	func create [-l|--language] [-t|--template] [-r|--repository]
	            [-c|--confirm]  [-v|--verbose]  [path]

DESCRIPTION
	Creates a new function project.

	  $ func create -l node -t http

	Creates a function in the current directory '.' which is written in the
	language/runtime 'node' and handles HTTP events.

	If [path] is provided, the function is initialized at that path, creating
	the path if necessary.

	To complete this command interactively, use --confirm (-c):
	  $ func create -c

	Available Language Runtimes and Templates:
	  Language     Template
	  --------     --------
	  go           cloudevents
	  go           http
	  go           lkingland/e2e
	  node         cloudevents
	  node         http
	  python       cloudevents
	  python       http
	  quarkus      cloudevents
	  quarkus      http
	  runtime      lkingland/template
	  rust         cloudevents
	  rust         http
	  springboot   cloudevents
	  springboot   http
	  typescript   cloudevents
	  typescript   http
	  

	To install more language runtimes and their templates see 'func repository'.


EXAMPLES
	o Create a Node.js function (the default language runtime) in the current
	  directory (the default path) which handles http events (the default
	  template).
	  $ func create

	o Create a Node.js function in the directory 'myfunc'.
	  $ func create myfunc

	o Create a Go function which handles CloudEvents in ./myfunc.
	  $ func create -l go -t cloudevents myfunc
		

Usage:
  func create [flags]

Flags:
  -c, --confirm             Prompt to confirm all options interactively (Env: $FUNC_CONFIRM)
  -h, --help                help for create
  -l, --language string     Language Runtime (see help text for list) (Env: $FUNC_LANGUAGE)
  -r, --repository string   URI to a Git repository containing the specified template (Env: $FUNC_REPOSITORY)
  -t, --template string     Function template. (see help text for list) (Env: $FUNC_TEMPLATE) (default "http")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

DELETE

Undeploy a function

This command undeploys a function from the cluster. By default the function from 
the project in the current directory is undeployed. Alternatively either the name 
of the function can be given as argument or the project path provided with --path.

No local files are deleted.


Usage:
  func delete [NAME] [flags]

Examples:

# Undeploy the function defined in the local directory
func delete

# Undeploy the function 'myfunc' in namespace 'apps'
func delete -n apps myfunc


Flags:
  -a, --all string    Delete all resources created for a function, eg. Pipelines, Secrets, etc. (Env: $FUNC_ALL) (allowed values: "true", "false") (default "true")
  -c, --confirm       Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)
  -h, --help          help for delete
  -p, --path string   Path to the project directory (Env: $FUNC_PATH) (default ".")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

DEPLOY

Deploy a function

Builds a container image for the function and deploys it to the connected Knative enabled cluster. 
The function is picked up from the project in the current directory or from the path provided
with --path.
If not already configured, either --registry or --image has to be provided and is then stored 
in the configuration file.

If the function is already deployed, it is updated with a new container image
that is pushed to an image registry, and finally the function's Knative service is updated.


Usage:
  func deploy [flags]

Examples:

# Build and deploy the function from the current directory's project. The image will be
# pushed to "quay.io/myuser/<function name>" and deployed as Knative service with the 
# same name as the function to the currently connected cluster.
func deploy --registry quay.io/myuser

# Same as above but using a full image name, that will create a Knative service "myfunc" in 
# the namespace "myns"
func deploy --image quay.io/myuser/myfunc -n myns


Flags:
  -b, --build string           Build specifies the way the function should be built. Supported types are "disabled", "local" or "git" (Env: $FUNC_BUILD) (default "local")
      --builder string         build strategy to use when creating the underlying image. Currently supported build strategies are "pack" and "s2i". (default "pack")
      --builder-image string   builder image, either an as a an image name or a mapping name.
                               Specified value is stored in func.yaml (as 'builder' field) for subsequent builds. ($FUNC_BUILDER_IMAGE)
  -c, --confirm                Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)
  -e, --env stringArray        Environment variable to set in the form NAME=VALUE. You may provide this flag multiple times for setting multiple environment variables. To unset, specify the environment variable name followed by a "-" (e.g., NAME-).
  -t, --git-branch string      Git branch to be used for remote builds (Env: $FUNC_GIT_BRANCH)
  -d, --git-dir string         Directory in the repo where the function is located (Env: $FUNC_GIT_DIR)
  -g, --git-url string         Repo url to push the code to be built (Env: $FUNC_GIT_URL)
  -h, --help                   help for deploy
  -i, --image string           Full image name in the form [registry]/[namespace]/[name]:[tag]@[digest]. This option takes precedence over --registry. Specifying digest is optional, but if it is given, 'build' and 'push' phases are disabled. (Env: $FUNC_IMAGE)
  -p, --path string            Path to the project directory (Env: $FUNC_PATH) (default ".")
      --platform string        Target platform to build (e.g. linux/amd64).
  -u, --push                   Attempt to push the function image to registry before deploying (Env: $FUNC_PUSH) (default true)
  -r, --registry string        Registry + namespace part of the image to build, ex 'quay.io/myuser'.  The full image name is automatically determined based on the local directory name. If not provided the registry will be taken from func.yaml (Env: $FUNC_REGISTRY)

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

INFO

Show details of a function

Prints the name, route and any event subscriptions for a deployed function in
the current directory or from the directory specified with --path.


Usage:
  func info <name> [flags]

Examples:

# Show the details of a function as declared in the local func.yaml
func info

# Show the details of the function in the myotherfunc directory with yaml output
func info --output yaml --path myotherfunc


Flags:
  -h, --help            help for info
  -o, --output string   Output format (human|plain|json|xml|yaml|url) (Env: $FUNC_OUTPUT) (default "human")
  -p, --path string     Path to the project directory (Env: $FUNC_PATH) (default ".")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

INVOKE


NAME
	func invoke - test a function by invoking it with test data

SYNOPSIS
	func invoke [-t|--target] [-f|--format]
	             [--id] [--source] [--type] [--data] [--file] [--content-type]
	             [-s|--save] [-p|--path] [-c|--confirm] [-v|--verbose]

DESCRIPTION
	Invokes the function by sending a test request to the currently running
	function instance, either locally or remote.  If the function is running
	both locally and remote, the local instance will be invoked.  This behavior
	can be manually overridden using the --target flag.

	Functions are invoked with a test data structure consisting of five values:
		id:            A unique identifier for the request.
		source:        A sender name for the request (sender).
		type:          A type for the request.
		data:          Data (content) for this request.
		content-type:  The MIME type of the value contained in 'data'.

	The values of these parameters can be individually altered from their defaults
	using their associated flags. Data can also be provided from a file using the
	--file flag.

	Invocation Target
	  The function instance to invoke can be specified using the --target flag
	  which accepts the values "local", "remote", or <URL>.  By default the
	  local function instance is chosen if running (see func run).
	  To explicitly target the remote (deployed) function:
	    func invoke --target=remote
	  To target an arbitrary endpoint, provide a URL:
	    func invoke --target=https://myfunction.example.com

	Invocation Data
	  Providing a filename in the --file flag will base64 encode its contents
	  as the "data" parameter sent to the function.  The value of --content-type
	  should be set to the type from the source file.  For example, the following
	  would send a JPEG base64 encoded in the "data" POST parameter:
	    func invoke --file=example.jpeg --content-type=image/jpeg

	Message Format
	  By default functions are sent messages which match the invocation format
	  of the template they were created using; for example "http" or "cloudevent".
	  To override this behavior, use the --format (-f) flag.
	    func invoke -f=cloudevent -t=http://my-sink.my-cluster

EXAMPLES

	o Invoke the default (local or remote) running function with default values
	  $ func invoke

	o Run the function locally and then invoke it with a test request:
	  (run in two terminals or by running the first in the background)
	  $ func run
	  $ func invoke

	o Deploy and then invoke the remote function:
	  $ func deploy
	  $ func invoke

	o Invoke a remote (deployed) function when it is already running locally:
	  (overrides the default behavior of preferring locally running instances)
	  $ func invoke --target=remote

	o Specify the data to send to the function as a flag
	  $ func invoke --data="Hello World!"

	o Send a JPEG to the function
	  $ func invoke --file=example.jpeg --content-type=image/jpeg

	o Invoke an arbitrary endpoint (HTTP POST)
		$ func invoke --target="https://my-http-handler.example.com"

	o Invoke an arbitrary endpoint (CloudEvent)
		$ func invoke -f=cloudevent -t="https://my-event-broker.example.com"



Usage:
  func invoke [flags]

Flags:
  -c, --confirm               Prompt to confirm all options interactively. (Env: $FUNC_CONFIRM)
      --content-type string   Content Type of the data. (Env: $FUNC_CONTENT_TYPE) (default "application/json")
      --data string           Data to send in the request. (Env: $FUNC_DATA) (default "{\"message\":\"Hello World\"}")
      --file string           Path to a file to use as data. Overrides --data flag and should be sent with a correct --content-type. (Env: $FUNC_FILE)
  -f, --format string         Format of message to send, 'http' or 'cloudevent'.  Default is to choose automatically. (Env: $FUNC_FORMAT)
  -h, --help                  help for invoke
      --id string             ID for the request data. (Env: $FUNC_ID)
  -p, --path string           Path to the project directory (Env: $FUNC_PATH) (default ".")
      --source string         Source value for the request data. (Env: $FUNC_SOURCE) (default "/boson/fn")
  -t, --target string         Function instance to invoke.  Can be 'local', 'remote' or a URL.  Defaults to auto-discovery if not provided. (Env: $FUNC_TARGET)
      --type string           Type value for the request data. (Env: $FUNC_TYPE) (default "boson.fn")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

LIST

List functions

Lists all deployed functions in a given namespace.


Usage:
  func list [flags]

Examples:

# List all functions in the current namespace with human readable output
func list

# List all functions in the 'test' namespace with yaml output
func list --namespace test --output yaml

# List all functions in all namespaces with JSON output
func list --all-namespaces --output json


Flags:
  -A, --all-namespaces   List functions in all namespaces. If set, the --namespace flag is ignored.
  -h, --help             help for list
  -o, --output string    Output format (human|plain|json|xml|yaml) (Env: $FUNC_OUTPUT) (default "human")

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------

REPOSITORY


NAME
	func - Manage set of installed repositories.

SYNOPSIS
	func repo [-c|--confirm] [-v|--verbose]
	func repo list [-r|--repositories] [-c|--confirm] [-v|--verbose]
	func repo add <name> <url>[-r|--repositories] [-c|--confirm] [-v|--verbose]
	func repo rename <old> <new> [-r|--repositories] [-c|--confirm] [-v|--verbose]
	func repo remove <name> [-r|--repositories] [-c|--confirm] [-v|--verbose]

DESCRIPTION
	Manage template repositories installed on disk at either the default location
	(~/.config/func/repositories) or the location specified by the --repository
	flag.  Once added, a template from the repository can be used when creating
	a new function.

	Interactive Prompts:
	To complete these commands interactively, pass the --confirm (-c) flag to
	the 'repository' command, or any of the inidivual subcommands.

	The Default Repository:
	The default repository is not stored on disk, but embedded in the binary and
	can be used without explicitly specifying the name.  The default repository
	is always listed first, and is assumed when creating a new function without
	specifying a repository name prefix.
	For example, to create a new Go function using the 'http' template from the
	default repository.
		$ func create -l go -t http

	The Repository Flag:
	Installing repositories locally is optional.  To use a template from a remote
	repository directly, it is possible to use the --repository flag on create.
	This leaves the local disk untouched.  For example, To create a function using
	the Boson Project Hello-World template without installing the template
	repository locally, use the --repository (-r) flag on create:
		$ func create -l go \
			--template hello-world \
			--repository https://github.com/boson-project/templates

	Alternative Repositories Location:
	Repositories are stored on disk in ~/.config/func/repositories by default.
	This location can be altered by setting the FUNC_REPOSITORIES_PATH
	environment variable.


COMMANDS

	With no arguments, this help text is shown.  To manage repositories with
	an interactive prompt, use the use the --confirm (-c) flag.
	  $ func repository -c

	add
	  Add a new repository to the installed set.
	    $ func repository add <name> <URL>

	  For Example, to add the Boson Project repository:
	    $ func repository add boson https://github.com/boson-project/templates

	  Once added, a function can be created with templates from the new repository
	  by prefixing the template name with the repository.  For example, to create
	  a new function using the Go Hello World template:
	    $ func create -l go -t boson/hello-world

	list
	  List all available repositories, including the installed default
	  repository.  Repositories available are listed by name.  To see the URL
	  which was used to install remotes, use --verbose (-v).

	rename
	  Rename a previously installed repository from <old> to <new>. Only installed
	  repositories can be renamed.
	    $ func repository rename <name> <new name>

	remove
	  Remove a repository by name.  Removes the repository from local storage
	  entirely.  When in confirm mode (--confirm) it will confirm before
	  deletion, but in regular mode this is done immediately, so please use
	  caution, especially when using an altered repositories location
	  (via the FUNC_REPOSITORIES_PATH environment variable).
	    $ func repository remove <name>

EXAMPLES
	o Run in confirmation mode (interactive prompts) using the --confirm flag
	  $ func repository -c

	o Add a repository and create a new function using a template from it:
	  $ func repository add boson https://github.com/boson-project/templates
	  $ func repository list
	  default
	  boson
	  $ func create -l go -t boson/hello-world
	  ...

	o List all repositories including the URL from which remotes were installed
	  $ func repository list -v
	  default
	  boson	https://github.com/boson-project/templates

	o Rename an installed repository
	  $ func repository list
	  default
	  boson
	  $ func repository rename boson boson-examples
	  $ func repository list
	  default
	  boson-examples

	o Remove an installed repository
	  $ func repository list
	  default
	  boson-examples
	  $ func repository remove boson-examples
	  $ func repository list
	  default


Usage:
  func repository [flags]
  func repository [command]

Aliases:
  repository, repo, repositories

Available Commands:
  add         Add a repository
  list        List repositories
  remove      Remove a repository
  rename      Rename a repository

Flags:
  -c, --confirm   Prompt to confirm all options interactively (Env: $FUNC_CONFIRM)
  -h, --help      help for repository

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

Use "func repository [command] --help" for more information about a command.

------------------------------------------------------------------------------

RUN

Run the function locally

Runs the function locally in the current directory or in the directory
specified by --path flag.

Building
By default the function will be built if never built, or if changes are detected
to the function's source.  Use --build to override this behavior.



Usage:
  func run [flags]

Examples:

# Run the function locally, building if necessary
func run

# Run the function, forcing a rebuild of the image.
#   This is useful when the function's image was manually deleted, necessitating
#   A rebuild even when no changes have been made the function's source.
func run --build

# Run the function's existing image, disabling auto-build.
#   This is useful when filesystem changes have been made, but one wishes to
#   run the previously built image without rebuilding.
func run --build=false



Flags:
  -b, --build string[="true"]   Build the function. [auto|true|false]. (default "auto")
  -e, --env stringArray         Environment variable to set in the form NAME=VALUE. You may provide this flag multiple times for setting multiple environment variables. To unset, specify the environment variable name followed by a "-" (e.g., NAME-).
  -h, --help                    help for run
  -p, --path string             Path to the project directory (Env: $FUNC_PATH) (default ".")
  -r, --registry string         Registry + namespace part of the image if building, ex 'quay.io/myuser' (Env: $FUNC_REGISTRY)

Global Flags:
  -n, --namespace string   The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
  -v, --verbose            Print verbose logs ($FUNC_VERBOSE)

------------------------------------------------------------------------------