--- weight: 50 title: Command Reference description: "Command reference for the Crossplane CLI" --- The `crossplane` CLI provides utilities to make using Crossplane easier. Read the [Crossplane CLI overview]({{}}) page for information on installing `crossplane`. ## Global flags The following flags are available for all commands. {{< table "table table-sm table-striped">}} | Short flag | Long flag | Description | |------------|-------------|------------------------------| | `-h` | `--help` | Show context sensitive help. | | | `--verbose` | Print verbose output. | {{< /table >}} ## version The `crossplane version` command returns the version of Crossplane CLI and the control plane. ```shell crossplane version Client Version: v1.17.0 Server Version: v1.17.0 ``` ## render The `crossplane render` command previews the output of a [composite resource]({{}}) after applying any [composition functions]({{}}). {{< hint "important" >}} The `crossplane render` command requires you to use composition functions. {{< /hint >}} The `crossplane render` command connects to the locally running Docker Engine to pull and run composition functions. {{}} Running `crossplane render` requires [Docker](https://www.docker.com/). {{< /hint >}} Provide a composite resource, composition and composition function YAML definition with the command to render the output locally. For example, `crossplane render xr.yaml composition.yaml function.yaml` The output includes the original composite resource followed by the generated managed resources. {{}} ```yaml --- apiVersion: nopexample.org/v1 kind: XBucket metadata: name: test-xrender status: bucketRegion: us-east-2 --- apiVersion: s3.aws.upbound.io/v1beta1 kind: Bucket metadata: annotations: crossplane.io/composition-resource-name: my-bucket generateName: test-xrender- labels: crossplane.io/composite: test-xrender ownerReferences: - apiVersion: nopexample.org/v1 blockOwnerDeletion: true controller: true kind: XBucket name: test-xrender uid: "" spec: forProvider: region: us-east-2 ``` {{< /expand >}} ### Flags {{< table "table table-sm table-striped">}} | Short flag | Long flag | Description | | ------------ | ------------- | ------------------------------ | | | `--context-files==,=` | A comma separated list of files to load for function "contexts." | | | `--context-values==,=` | A comma separated list of key-value pairs to load for function "contexts." | | `-r` | `--include-function-results` | Include the "results" or events from the function. | | `-o` | `--observed-resources=` | Provide artificial managed resource data to the function. | | `-e` | `--extra-resources=PATH` | A YAML file or directory of YAML files specifying extra resources to pass to the Function pipeline. | | `-c` | `--include-context` | Include the context in the rendered output as a resource of kind: Context. | | `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. | | | `--timeout=` | Amount of time to wait for a function to finish. (Default 1 minute) | {{< /table >}} The `crossplane render` command relies on standard [Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) to connect to the local Docker Engine and run composition functions. ### Provide function context The `--context-files` and `--context-values` flags can provide data to a function's `context`. The context is JSON formatted data. ### Include function results If a function produces Kubernetes events with statuses use the `--include-function-results` to print them along with the managed resource outputs. ### Include the composite resource Composition functions can only change the `status` field of a composite resource. By default, the `crossplane render` command only prints the `status` field with `metadata.name`. Use `--include-full-xr` to print the full composite resource, including the `spec` and `metadata` fields. ### Mock managed resources Provide mocked, or artificial data representing a managed resource with `--observed-resources`. The `crossplane render` command treats the provided inputs as if they were resources in a Crossplane cluster. A function can reference and manipulate the included resource as part of running the function. The `observed-resources` may be a single YAML file with multiple resources or a directory of YAML files representing multiple resources. Inside the YAML file include an {{}}apiVersion{{}}, {{}}kind{{}}, {{}}metadata{{}} and {{}}spec{{}}. ```yaml {label="apiVersion"} apiVersion: example.org/v1alpha1 kind: ComposedResource metadata: name: test-render-b annotations: crossplane.io/composition-resource-name: resource-b spec: coolerField: "I'm cooler!" ``` The schema of the resource isn't validated and may contain any data. ### Mock Extra Resources Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren't part of the Composition. The `--extra-resources` option points at a directory containing YAML manifests of resources to mock. Use Extra Resources in combination with a function like [function-extra-resources](https://github.com/crossplane-contrib/function-extra-resources) or the built-in support in [function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources). ## xpkg The `crossplane xpkg` commands create, install and update Crossplane [packages]({{}}) as well as enable authentication and publishing of Crossplane packages to a Crossplane package registry. ### xpkg build Using `crossplane xpkg build` provides automation and simplification to build Crossplane packages. The Crossplane CLI combines a directory of YAML files and packages them as an [OCI container image](https://opencontainers.org/). The CLI applies the required annotations and values to meet the [Crossplane XPKG specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md). The `crossplane` CLI supports building [configuration]({{< ref "../concepts/packages" >}}), [function]({{}}) and [provider]({{}}) package types. #### Flags {{< table "table table-sm table-striped">}} | Short flag | Long flag | Description | | ------------ | ------------- | ------------------------------ | | | `--embed-runtime-image-name=NAME` | The image name and tag of an image to include in the package. Only for provider and function packages. | | | `--embed-runtime-image-tarball=PATH` | The filename of an image to include in the package. Only for provider and function packages. | | `-e` | `--examples-root="./examples"` | The path to a directory of examples related to the package. | | | `--ignore=PATH,...` | List of files and directories to ignore. | | `-o` | `--package-file=PATH` | Directory and filename of the created package. | | `-f` | `--package-root="."` | Directory to search for YAML files. | {{< /table >}} The `crossplane xpkg build` command recursively looks in the directory set by `--package-root` and attempts to combine any files ending in `.yml` or `.yaml` into a package. All YAML files must be valid Kubernetes manifests with `apiVersion`, `kind`, `metadata` and `spec` fields. #### Ignore files Use `--ignore` to provide a list of files and directories to ignore. For example, `crossplane xpkg build --ignore="./test/*,kind-config.yaml"` #### Set the package name `crossplane` automatically names the new package a combination of the `metadata.name` and a hash of the package contents and saves the contents in the same location as `--package-root`. Define a specific location and filename with `--package-file` or `-o`. For example, `crossplane xpkg build -o /home/crossplane/example.xpkg`. #### Include examples Include YAML files demonstrating how to use the package with `--examples-root`. #### Include a runtime image Functions and Providers require YAML files describing their dependencies and settings as well as a container image for their runtime. Using `--embed-runtime-image-name` runs a specified image and includes the image inside the function or provider package. {{}} Images referenced with `--embed-runtime-image-name` must be in the local Docker cache. Use `docker pull` to download a missing image. {{< /hint >}} The `--embed-runtime-image-tarball` flag includes a local OCI image tarball inside the function or provider package. ### xpkg init The `crossplane xpkg init` command populates the current directory with files to build a package. Provide a name to use for the package and the package template to start from with the command `crossplane xpkg init