Configuration

Configuration

iructl can be configured to read persistent settings from YAML configuration files.

Table of contents

• Configuration key options
• Default config file locations
  • User config
  • Local repo config
• Precedence
• Sample config file
• First-time setup
• Troubleshooting

Configuration key options

Key	Type	Allowed values	Default	Environment variable	CLI flag
output_format	enum	table, plist, json, yaml	table	IRUCTL_OUTPUT_FORMAT	--format / -f
info_format	enum	plist, json, yaml	plist	IRUCTL_INFO_FORMAT	--info-format
git_enabled	boolean	true, false	true	IRUCTL_GIT_ENABLED	--git/--no-git
tenant_url	string	Iru tenant API URL	unset (prompted)	IRUCTL_TENANT	--tenant-url/-u
payload_dir	string	directory path	<repo>/payloads	IRUCTL_PAYLOAD_DIR	--payload-dir
debug	boolean	true, false	false	IRUCTL_DEBUG	--debug
preview	boolean	true, false	false	IRUCTL_PREVIEW	--preview

output_format

Format used by show-style commands when printing resources to the terminal.

output_format: json

info_format

On-disk format for the info files of newly created resources (new, import, and lifecycle commands). Existing info files keep their format unless rewritten with --reformat.

info_format: yaml

git_enabled

Whether iructl performs git interactions (commits, status checks) when modifying the repository. Set to false if you manage version control yourself.

git_enabled: false

tenant_url

Your Iru tenant's API URL. When unset, commands that talk to the tenant prompt for it interactively.

tenant_url: https://subdomain.api.iru.com

payload_dir

Directory holding app installer binaries, relative to the repository root.

payload_dir: installers

debug

Enable debug logging.

debug: true

preview

Enable experimental preview features.

preview: true

Important

The Iru API token cannot be set in a config file — provide it with the --api-token / -t flag or by setting the IRUCTL_TOKEN environment variable. See Token Permissions for the permissions the token requires.

Default config file locations

User config

Platform	Default path
macOS	~/Library/Application Support/iructl/config.yaml
Linux	~/.config/iructl/config.yaml
Windows	not currently supported

Note

XDG support: if the XDG_CONFIG_HOME environment variable is set, iructl uses $XDG_CONFIG_HOME/iructl/config.yaml instead. For example, with XDG_CONFIG_HOME=~/.config exported, the user config lives at ~/.config/iructl/config.yaml.

Local repo config

The .iructl marker file at the root of an iructl repository doubles as the repo-level config. The same file that marks the directory as an iructl repository can contain YAML settings. These settings are shared by everyone working in that repo. An empty .iructl file is valid, and means that a repo-level config is not set.

Warning

A repository still using the legacy .kst marker must be migrated before iructl will recognize it.

Precedence

Each setting is resolved independently, with the highest precedence first:

1. CLI flag — e.g. --format json
2. Environment variable — e.g. IRUCTL_OUTPUT_FORMAT=json
3. Repo config — the .iructl file at the repository root
4. User config — your personal config.yaml
5. Built-in default

A key that is omitted from a layer (or set to an empty value) falls through to the next layer down. The first layer that sets the key wins.

Sample config file

A complete config.yaml (or repo-level .iructl) setting every key — in practice, set only the keys you want to pin and leave the rest unset:

# iructl configuration
output_format: table
info_format: plist
git_enabled: true
tenant_url: https://subdomain.api.iru.com
payload_dir: payloads
debug: false
preview: false

First-time setup

Create the config directory and file:

macOS

mkdir -p "$HOME/Library/Application Support/iructl"
touch "$HOME/Library/Application Support/iructl/config.yaml"

Linux (or any platform with XDG_CONFIG_HOME set)

mkdir -p ~/.config/iructl
touch ~/.config/iructl/config.yaml

For repo-level settings, edit the .iructl file at the repository root instead and commit it so the whole team shares the same default settings.

Troubleshooting

Symptom	Cause
Invalid Iru Control configuration in <path>: … Extra inputs are not permitted	Unknown or misspelled key — only the documented keys are allowed.
Invalid Iru Control configuration in <path>: … Input should be 'table', 'plist', 'json' or 'yaml'	Value is not one of the key's allowed values.
Invalid Iru Control configuration in <path>: expected a mapping of keys to values.	The YAML parses to a list or scalar instead of key: value pairs.
Setting appears to be ignored	A higher-precedence layer sets the same key — check CLI flags, IRUCTL_* environment variables, and the repo .iructl file.
tenant_url or payload_dir set to "" has no effect	Empty and whitespace-only strings are treated as unset by design.
Repo config not loading	You are outside the repository, or the root has a legacy .kst marker instead of .iructl.