dump Command

Bootstrap local definitions from remote Koji state using pattern matching.

Syntax

koji-habitude dump [OPTIONS] PATTERNS...

Description

The dump command searches Koji for objects matching given patterns and outputs their remote state as YAML. Unlike fetch, which requires local YAML definitions, dump operates entirely on remote data using pattern matching.

This command is particularly useful for:

  • Bootstrapping local YAML definitions from an existing Koji instance

  • Discovering objects by name patterns

  • Exporting specific objects or sets of objects

  • Creating local definitions without having existing YAML

The command supports:

  • Typed patterns: tag:foo, user:*bob*, target:*-build

  • Untyped patterns: *-build (applied to default types)

  • Glob patterns: Wildcards (*, ?, character classes [])

  • Exact matches: Direct object names

  • Dependency resolution: Optionally include related objects

Options

PATTERNS

One or more search patterns. Required. Patterns can be:

  • Typed: type:pattern (e.g., tag:foo, user:*bob*)

  • Untyped: pattern (applied to default types)

Can be repeated multiple times for multiple patterns.

--profile PROFILE, -p PROFILE

Koji profile to use for connection. Default: koji.

--output PATH, -o PATH

Path to output YAML file. Default: stdout.

--include-defaults, -d

Include default values in output. By default, default values are excluded.

--with-deps

Include dependencies of matched objects. For example, if dumping a tag, also include its parent tags and external repositories.

--with-dep-type TYPE

Limit dependencies to specific types. Can be repeated for multiple types. If specified, --with-deps is automatically enabled.

Valid types: tag, target, user, host

--max-depth N

Maximum dependency depth when using --with-deps. Default: unlimited. Limits how many levels of dependencies to follow.

--tags

Search tags by default for untyped patterns.

--targets

Search targets by default for untyped patterns.

--users

Search users by default for untyped patterns.

--hosts

Search hosts by default for untyped patterns.

Pattern Examples

Typed patterns:
tag:fedora-42-build

Exact match for tag named “fedora-42-build”

user:*bob*

All users with “bob” in their name (wildcard pattern)

target:*-build

All targets ending in “-build”

Untyped patterns (use default types):
*-build

Matches tags and targets (default) ending in “-build”

f40-*

Matches default types starting with “f40-”

Mixed patterns:
tag:foo target:bar *-build user:*admin*

Combination of typed and untyped patterns

Examples

Search tags and targets for patterns (default behavior):

koji-habitude dump *-build

Search specific types only:

koji-habitude dump --tags --users *bob*

Exact tag match with dependencies:

koji-habitude dump tag:f40-build --with-deps

Dependencies with depth limit:

koji-habitude dump tag:f40-build --with-deps --max-depth 2

Dependencies only for specific types:

koji-habitude dump tag:f40-build --with-deps --with-dep-type tag --with-dep-type external-repo

Mixed patterns:

koji-habitude dump tag:foo target:bar *-build user:*admin*

Save output to file:

koji-habitude dump --output my-tags.yaml *-build

Include default values:

koji-habitude dump --include-defaults tag:foo

Use Cases

  • Bootstrap: Create initial YAML definitions from existing Koji instance

  • Migration: Export objects from one instance for import to another

  • Audit: Discover and document what exists in Koji

  • Backup: Create YAML backups of specific object sets

  • Pattern Discovery: Find objects by name patterns

Exit Codes

  • 0 - Success

  • 1 - Error (e.g., invalid pattern, invalid type)