edit Command

Edit remote koji objects interactively using an editor.

Syntax

koji-habitude edit [OPTIONS] NAMES [NAMES...]

Description

The edit command loads remote objects from a Koji instance, opens them in your system editor for interactive editing, validates the changes, shows a delta comparison, and optionally applies them. This is ideal for making quick changes to existing koji objects without needing to maintain local YAML files.

The command will:

  1. Connect to the Koji hub instance

  2. Load the specified remote objects

  3. Convert them to YAML format

  4. Open them in your system editor (via $EDITOR environment variable)

  5. Validate the edited YAML after each save

  6. Show a comparison of changes against the remote state

  7. Prompt for action: [A]pply / [E]dit / [Q]uit

The interactive workflow allows you to:

  • Edit objects multiple times until satisfied

  • Review changes before applying

  • Cancel at any time without making changes

  • See validation errors and retry editing

If validation errors occur (YAML parsing or object validation), you can choose to edit again or quit. The editor will be re-opened with the last edited content so you can fix the issues.

Options

NAMES

One or more object names to edit. Required. Can be specified in two formats:

  • TYPE:NAME - Explicitly specify the object type and name (e.g., tag:foo, user:bob, target:build-target)

  • NAME - Use the default type (specified with --type, defaults to tag) for untyped names (e.g., foo becomes tag:foo)

Can be repeated multiple times to edit multiple objects at once.

--templates PATH, -t PATH

Location to find templates that are not available in DATA directories. Can be repeated multiple times.

--profile PROFILE, -p PROFILE

Koji profile to use for connection. Default: koji.

--include-defaults, -d

Include default values in the YAML output. By default, fields with default values are omitted to keep the YAML concise. Use this flag to see all fields, including those with default values.

--type TYPE

Default type to use for untyped names (names without TYPE: prefix). Default: tag. Must be one of the core koji object types.

--show-unchanged

Show objects that don’t need any changes in the comparison output. By default, only objects with differences are shown.

--skip-phantoms

Skip objects that have phantom dependencies instead of exiting with an error. Use with caution, as this may lead to incomplete synchronization.

Examples

Edit a single tag:

koji-habitude edit tag:foo

Edit multiple objects of different types:

koji-habitude edit tag:foo user:bob target:build-target

Edit objects using default type (tag):

koji-habitude edit foo bar

Edit targets using default type:

koji-habitude edit build-target dest-target --type=target

Edit with all default values included:

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

Edit using a specific Koji profile:

koji-habitude edit --profile production tag:prod-tag

Show all objects including unchanged ones:

koji-habitude edit tag:foo --show-unchanged

Use Cases

  • Quick Edits: Make small changes to existing koji objects without maintaining local YAML files

  • Interactive Exploration: Load remote objects to see their current state and structure

  • One-Off Changes: Modify objects that don’t warrant creating or updating data files

  • Learning Tool: Examine how koji objects are represented in YAML format

  • Emergency Fixes: Quickly fix misconfigured objects directly from the command line

Exit Codes

  • 0 - Success (changes applied) or edit cancelled by user

  • 1 - Error encountered (e.g., invalid object type, no objects found, validation failures)