Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

User Commands

Regular users and group owners import, synchronize, and remove their own catalog repositories with the fuzzball workflow catalog source commands. Administrators have extra flags and deployment-wide scope – see Admin Commands.

The CLI is currently the only way to manage catalog repositories.

Importing a Catalog Repository

To add a catalog repository and synchronize its contents in one step, use import:

$ fuzzball workflow catalog source import <NAME> <URI> <BRANCH> [flags]

Arguments:

  • <NAME>: A descriptive name for the catalog repository
  • <URI>: The Git repository URI. HTTPS only – see Accepted Repository URIs
  • <BRANCH>: The branch to synchronize

Flags:

  • --owner-kind: The owner type for the catalog repository (default: group)
    • Options: group, organization
  • --access-token, -t: Access token for private git repositories (e.g. GitHub PAT)

Accepted Repository URIs

Fuzzball itself clones the repository, so a repository URI is a network destination your cluster connects to. Fuzzball validates the URI before it connects. A URI is rejected unless it:

  • uses the https scheme – ssh, git, file, and plain http are not accepted
  • names a host, and embeds no credentials (https://user:token@host/...) and no URI fragment – supply credentials with --access-token instead
  • resolves to a publicly routable address – loopback, private, link-local, and cloud instance-metadata addresses are refused

Administrators may further restrict repositories to an explicit list of hosts. If your repository is rejected, check with your administrator whether its host is on that list.

Example - Public Repository:

$ fuzzball workflow catalog source import \
    "Community Catalog" \
    "https://github.com/example/fuzzball-catalog" \
    main

Example - Private Repository:

$ fuzzball workflow catalog source import \
    "Private Catalog" \
    "https://github.com/example/private-catalog" \
    main \
    --access-token "xxxxxxxxxxxx"

Listing Catalog Repositories

To view all configured catalog repositories:

$ fuzzball workflow catalog source list

Example Output:

NAME                 | OWNER    | URI                                            | BRANCH
ciq-fuzzball-catalog | PROVIDER | https://github.com/ctrliq/ciq-fuzzball-catalog | v4.3
Community Catalog    | GROUP    | https://github.com/example/catalog             | main

The output lists each repository’s name, owner kind, URI, and branch. Use -o json or -o yaml for the full record, including the repository ID and last synchronized commit SHA.

Getting Repository Details

To view detailed information about a specific catalog repository:

$ fuzzball workflow catalog source get <SOURCE>

<SOURCE> is the repository’s name or its UUID. A name must be unique across the deployment; if two repositories share one, use the UUID. Without -o, get prints YAML.

Example:

$ fuzzball workflow catalog source get -o json 1d9c69b7-d394-4286-9c19-05dac07919b4

Example Output:

{
  "id": "1d9c69b7-d394-4286-9c19-05dac07919b4",
  "name": "Community Catalog",
  "uri": "https://github.com/example/catalog",
  "branch": "main",
  "accessToken": "",
  "lastSyncedSha": "ccb981ae3beaafc269a854615cd8976a0ec09e03",
  "ownerKind": "GROUP",
  "createTime": "2026-01-14T15:33:54.357487Z",
  "updateTime": "2026-01-14T15:33:54.602545Z"
}

Reloading a Catalog Repository

To synchronize a catalog repository and update its applications:

$ fuzzball workflow catalog source reload <SOURCE>

Example:

$ fuzzball workflow catalog source reload 1d9c69b7-d394-4286-9c19-05dac07919b4

reload fetches the latest commit from the branch and updates the repository’s applications, creating new ones and updating existing ones. Fuzzball also syncs every catalog repository on a timer – every four hours by default – so changes reach the catalog without a manual reload.

Removing a Catalog Repository

To remove a catalog repository:

$ fuzzball workflow catalog source remove <SOURCE>

Example:

$ fuzzball workflow catalog source remove 1d9c69b7-d394-4286-9c19-05dac07919b4
Removing a catalog repository removes its templates from the Fuzzball workflow catalog. Fuzzball never modifies the Git repository at its origin, so you can restore the repository by importing it again.

Adding a Repository Without Synchronizing It

import adds a repository and synchronizes it in one step. Use add instead when you want the repository registered before its contents are ready – for example, when the branch does not exist yet, or when you want to control the moment of the first clone:

$ fuzzball workflow catalog source add <NAME> <URI> <BRANCH> [flags]

add takes the same arguments and flags as import, plus --id, -i to assign the repository a specific UUID. Fuzzball does not clone the repository until you run reload, so its applications do not appear in the catalog before then:

$ fuzzball workflow catalog source add \
    "Development Catalog" \
    "https://github.com/example/dev-catalog" \
    develop

$ fuzzball workflow catalog source reload "Development Catalog"