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.

Short flagLong flagDescription
-h--helpShow context sensitive help.
-v--versionPrint version and exit.
--verbosePrint verbose output.


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.

The CLI applies the required annotations and values to meet the Crossplane XPKG specification.

The crossplane CLI supports building configuration, function and provider package types.


Short flagLong flagDescription
--embed-runtime-image-name=NAMEThe image name and tag of an image to include in the package. Only for provider and function packages.
--embed-runtime-image-tarball=PATHThe 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=PATHDirectory and filename of the created package.
-f--package-root="."Directory to search for YAML files.

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

Upbound Marketplace uses files included with --examples-root as documentation for published packages.

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.

The --embed-runtime-image-tarball flag includes a local OCI image tarball inside the function or provider package.

xpkg install

Download and install packages into Crossplane with crossplane xpkg install.

By default the crossplane xpkg install command uses the Kubernetes configuration defined in ~/.kube/config.

Define a custom Kubernetes configuration file location with the environmental variable KUBECONFIG.

Specify the package kind, package file and optionally a name to give the package inside Crossplane.

crossplane xpkg install <package-kind> <registry URL package name and tag> [<optional-name>]

The <package-kind> is either a configuration, function or provider.

For example, to install version 0.42.0 of the AWS S3 provider:

crossplane xpkg install provider


Short flagLong flagDescription
--runtime-config=<runtime config name>Install the package with a runtime configuration.
-m--manual-activationSet the revisionActiviationPolicy to Manual.
--package-pull-secrets=<list of secrets>A comma-separated list of Kubernetes secrets to use for authenticating to the package registry.
-r--revision-history-limit=<number of revisions>Set the revisionHistoryLimit. Defaults to 1.
-w--wait=<number of seconds>Number of seconds to wait for a package to install.

Wait for package install

When installing a package the crossplane xpkg install command doesn’t wait for the package to download and install. View any download or installation problems by inspecting the configuration with kubectl describe configuration.

Use --wait to have the crossplane xpkg install command to wait for a package to have the condition HEALTHY before continuing. The command returns an error if the wait time expires before the package is HEALTHY.

Require manual package activation

Set the package to require manual activation, preventing an automatic upgrade of a package with --manual-activation

Authenticate to a private registry

To authenticate to a private package registry use --package-pull-secrets and provide a list of Kubernetes Secret objects.

The secrets must be in the same namespace as the Crossplane pod.

Customize the number of stored package versions

By default Crossplane only stores a single inactive package in the local package cache.

Store more inactive copies of a package with --revision-history-limit.

Read more about package revisions in the package documentation.

xpkg login

Use xpkg login to authenticate to, the Upbound Marketplace container registry.

Register with the Upbound Marketplace to push packages and create private repositories.


Short flagLong flagDescription
-u--username=<username>Username to use for authentication.
-p--password=<password>Password to use for authentication.
-t--token=<token string>User token string to use for authentication.
-a--account=<organization>Specify an Upbound organization during authentication.

Authentication options

The crossplane xpkg login command can use a username and password or Upbound API token.

By default, crossplane xpkg login without arguments, prompts for a username and password.

Provide a username and password with the --username and --password flags or set the environmental variable UP_USER for a username or UP_PASSWORD for the password.

Use an Upbound user token instead of a username and password with --token or the UP_TOKEN environmental variable.

The --token or UP_TOKEN environmental variables take precedence over a username and password.

Using - as the input for --password or --token reads the input from stdin.
For example, crossplane xpkg login --password -.

After logging in the Crossplane CLI creates a profile in .crossplane/config.json to cache unprivileged account information.


The session field of config.json file is a session cookie identifier.

The session value isn’t used for authentication. This isn’t a token.

Authenticate with a registered Upbound organization

Authenticate to a registered organization in the Upbound Marketplace with the --account option, along with the username and password or token.

For example, crossplane xpkg login --account=Upbound --username=my-user --password -.

xpkg logout

Use crossplane xpkg logout to invalidate the current crossplane xpkg login session.

Using crossplane xpkg logout removes the session from the ~/.crossplane/config.json file, but doesn’t delete the configuration file.

xpkg push

Push a Crossplane package file to a package registry.

The Crossplane CLI pushes images to the Upbound Marketplace at by default.

Pushing a package may require authentication with crossplane xpkg login

Specify the organization, package name and tag with
crossplane xpkg push <package>

By default the command looks in the current directory for a single .xpkg file to push.

To push multiple files or to specify a specific .xpkg file use the -f flag.

For example, to push a local package named my-package to crossplane-docs/my-package:v0.14.0 use:

crossplane xpkg push -f my-package.xpkg crossplane-docs/my-package:v0.14.0

To push to another package registry, like DockerHub provide the full URL along with the package name.

For example, to push a local package named my-package to DockerHub organization crossplane-docs/my-package:v0.14.0 use: crossplane xpkg push -f my-package.xpkg


Short flagLong flagDescription
-f--package-files=PATHA comma-separated list of xpkg files to push.

xpkg update

The crossplane xpkg update command downloads and updates an existing package.

By default the crossplane xpkg update command uses the Kubernetes configuration defined in ~/.kube/config.

Define a custom Kubernetes configuration file location with the environmental variable KUBECONFIG.

Specify the package kind, package file and optionally the name of the package already installed in Crossplane.

crossplane xpkg update <package-kind> <registry package name and tag> [<optional-name>]

The package file must be an organization, image and tag on the registry on Upbound Marketplace.

For example, to update to version 0.42.0 of the AWS S3 provider:

crossplane xpkg update provider


Crossplane beta commands are experimental. These commands may change the flags, options or outputs in future releases.

Crossplane maintainers may promote or remove commands under beta in future releases.

beta render

The crossplane beta render command previews the output of a composite resource after applying any composition functions.


The crossplane beta render command doesn’t apply patch and transform composition patches.

The command only supports function “patch and transforms.”

The crossplane beta render command connects to the locally running Docker Engine to pull and run composition functions.

Running crossplane beta render requires Docker.

Provide a composite resource, composition and composition function YAML definition with the command to render the output locally.

For example, crossplane beta render xr.yaml composition.yaml function.yaml

The output includes the original composite resource followed by the generated managed resources.

 3kind: XBucket
 5  name: test-xrender
 7  bucketRegion: us-east-2
10kind: Bucket
12  annotations:
13 my-bucket
14  generateName: test-xrender-
15  labels:
16 test-xrender
17  ownerReferences:
18  - apiVersion:
19    blockOwnerDeletion: true
20    controller: true
21    kind: XBucket
22    name: test-xrender
23    uid: ""
25  forProvider:
26    region: us-east-2


Short flagLong flagDescription
--context-files=<key>=<file>,<key>=<file>A comma separated list of files to load for function “contexts.”
--context-values=<key>=<value>,<key>=<value>A comma separated list of key-value pairs to load for function “contexts.”
-r--include-function-resultsInclude the “results” or events from the function.
-o--observed-resources=<directory or file>Provide artificial managed resource data to the function.
--timeout=Amount of time to wait for a function to finish.

The crossplane beta render command relies on standard Docker environmental 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.

Mock managed resources

Provide mocked, or artificial data representing a managed resource with --observed-resources. The crossplane beta 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.

2kind: ComposedResource
4  name: test-render-b
5  annotations:
6 resource-b
8  coolerField: "I'm cooler!"

The schema of the resource isn’t validated and may contain any data.

beta trace

Use the crossplane beta trace command to display a visual relationship of Crossplane objects. The trace command supports claims, compositions or managed resources.

The command requires a resource type and a resource name.

crossplane beta trace <resource kind> <resource name>

For example to view a resource named my-claim of type
crossplane beta trace my-claim

The command also accepts Kubernetes CLI style <kind>/<name> input.
For example,
crossplane beta trace

By default the crossplane beta trace command uses the Kubernetes configuration defined in ~/.kube/config.

Define a custom Kubernetes configuration file location with the environmental variable KUBECONFIG.


Short flagLong flagDescription
-n--namespaceThe namespace of the resource.
-o--output=Change the graph output with wide, json, or dot for a Graphviz dot output.
-s--show-connection-secretsPrint any connection secret names. Doesn’t print the secret values.

Output options

By default crossplane beta trace prints directly to the terminal, limiting the “Ready” condition and “Status” messages to 64 characters.

The following an example output a “cluster” claim from the AWS reference platform, which includes multiple Compositions and composed resources:

 1crossplane beta trace platform-ref-aws
 2NAME                                                              SYNCED   READY   STATUS
 3Cluster/platform-ref-aws (default)                                True     True    Available
 4└─ XCluster/platform-ref-aws-mlnwb                                True     True    Available
 5   ├─ XNetwork/platform-ref-aws-mlnwb-6nvkx                       True     True    Available
 6   │  ├─ VPC/platform-ref-aws-mlnwb-ckblr                         True     True    Available
 7   │  ├─ InternetGateway/platform-ref-aws-mlnwb-r7w47             True     True    Available
 8   │  ├─ Subnet/platform-ref-aws-mlnwb-lhr4h                      True     True    Available
 9   │  ├─ Subnet/platform-ref-aws-mlnwb-bss4b                      True     True    Available
10   │  ├─ Subnet/platform-ref-aws-mlnwb-fzbxx                      True     True    Available
11   │  ├─ Subnet/platform-ref-aws-mlnwb-vxbf4                      True     True    Available
12   │  ├─ RouteTable/platform-ref-aws-mlnwb-cs9nl                  True     True    Available
13   │  ├─ Route/platform-ref-aws-mlnwb-vpxdg                       True     True    Available
14   │  ├─ MainRouteTableAssociation/platform-ref-aws-mlnwb-sngx5   True     True    Available
15   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-hprsp       True     True    Available
16   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-shb8f       True     True    Available
17   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-hvb2h       True     True    Available
18   │  ├─ RouteTableAssociation/platform-ref-aws-mlnwb-m58vl       True     True    Available
19   │  ├─ SecurityGroup/platform-ref-aws-mlnwb-xxbl2               True     True    Available
20   │  ├─ SecurityGroupRule/platform-ref-aws-mlnwb-7qt56           True     True    Available
21   │  └─ SecurityGroupRule/platform-ref-aws-mlnwb-szgxp           True     True    Available
22   ├─ XEKS/platform-ref-aws-mlnwb-fqjzz                           True     True    Available
23   │  ├─ Role/platform-ref-aws-mlnwb-gmpqv                        True     True    Available
24   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-t6rct        True     True    Available
25   │  ├─ Cluster/platform-ref-aws-mlnwb-crrt8                     True     True    Available
26   │  ├─ ClusterAuth/platform-ref-aws-mlnwb-dgn6f                 True     True    Available
27   │  ├─ Role/platform-ref-aws-mlnwb-tdnx4                        True     True    Available
28   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-qzljh        True     True    Available
29   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-l64q2        True     True    Available
30   │  ├─ RolePolicyAttachment/platform-ref-aws-mlnwb-xn2px        True     True    Available
31   │  ├─ NodeGroup/platform-ref-aws-mlnwb-4sfss                   True     True    Available
32   │  ├─ OpenIDConnectProvider/platform-ref-aws-mlnwb-h26xx       True     True    Available
33   │  └─ ProviderConfig/platform-ref-aws                          -        -
34   └─ XServices/platform-ref-aws-mlnwb-bgndx                      True     True    Available
35      ├─ Release/platform-ref-aws-mlnwb-bcj7r                     True     True    Available
36      └─ Release/platform-ref-aws-mlnwb-7hfkv                     True     True    Available

Wide outputs

Print the entire “Ready” or “Status” message if they’re longer than 64 characters with --output=wide.

For example, the output truncates the “Status” message that’s too long.

1crossplane trace platform-ref-aws
2NAME                                                              SYNCED   READY   STATUS
3Cluster/platform-ref-aws (default)                                True     False   Waiting: ...resource claim is waiting for composite resource to become Ready

Use --output=wide to see the full message.

1crossplane trace platform-ref-aws --output=wide
2NAME                                                              SYNCED   READY   STATUS
3Cluster/platform-ref-aws (default)                                True     False   Waiting: Composite resource claim is waiting for composite resource to become Ready

Graphviz dot file output

Use the --output=dot to print out a textual Graphviz dot output.

Save the output and export it or the output directly to Graphviz dot to render an image.

For example, to save the output as a graph.png file use dot -Tpng -o graph.png.

crossplane beta trace platform-ref-aws -o dot | dot -Tpng -o graph.png

Use -s to print any connection secret names along with the other resources.

The crossplane beta trace command doesn’t print secret values.

The output includes both the secret name along with the secret’s namespace.

 1NAME                                                                        SYNCED   READY   STATUS
 2Cluster/platform-ref-aws (default)                                          True     True    Available
 3└─ XCluster/platform-ref-aws-mlnwb                                          True     True    Available
 4   ├─ XNetwork/platform-ref-aws-mlnwb-6nvkx                                 True     True    Available
 5   │  ├─ SecurityGroupRule/platform-ref-aws-mlnwb-szgxp                     True     True    Available
 6   │  └─ Secret/3f11c30b-dd94-4f5b-aff7-10fe4318ab1f (upbound-system)       -        -
 7   ├─ XEKS/platform-ref-aws-mlnwb-fqjzz                                     True     True    Available
 8   │  ├─ OpenIDConnectProvider/platform-ref-aws-mlnwb-h26xx                 True     True    Available
 9   │  └─ Secret/9666eccd-929c-4452-8658-c8c881aee137-eks (upbound-system)   -        -
10   ├─ XServices/platform-ref-aws-mlnwb-bgndx                                True     True    Available
11   │  ├─ Release/platform-ref-aws-mlnwb-7hfkv                               True     True    Available
12   │  └─ Secret/d0955929-892d-40c3-b0e0-a8cabda55895 (upbound-system)       -        -
13   └─ Secret/9666eccd-929c-4452-8658-c8c881aee137 (upbound-system)          -        -

beta xpkg init

The crossplane beta 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 beta xpkg init <name> <template>

The <name> input isn’t used. Crossplane reserves the <name> for future releases.

The <template> value may be one of three well known templates:

Instead of a well known template the <template> value can be a git repository URL.


Short flagLong flagDescription
-d--directoryThe directory to create and load the template files into. Uses the current directory by default.