it2 Configuration

it2 reads defaults from ~/.it2/config.yaml, applies supported environment
variables, and then applies command-line flags. Command-line flags therefore
have the highest precedence.

Create and Inspect the File

# Create ~/.it2/config.yaml with default values.
it2 config init

# Print the path used by this build.
it2 config path

# Print the values loaded from the file and environment.
it2 config show

The configuration path is currently fixed at ~/.it2/config.yaml.
IT2_CONFIG is not supported.

Effective Command Defaults

The root command currently consumes these configuration fields:

url: ws://localhost:1912
timeout: 5s
format: table
Field Environment Flag Default
url IT2_URL --url ws://localhost:1912
timeout IT2_TIMEOUT --timeout 5s
format IT2_FORMAT --format table

timeout uses Go duration syntax, such as 500ms, 10s, or 2m.
Supported output formats are table, text, json, and yaml.

Examples:

# Override a default for one command.
IT2_FORMAT=json it2 session list

# Flags override both the environment and the file.
IT2_FORMAT=json it2 --format yaml session list

# Use a longer connection timeout.
it2 --timeout 30s session list

Authentication and Debugging

Authentication is normally requested and managed automatically. The client
also reads these environment variables when they are supplied:

Variable Purpose
ITERM2_COOKIE iTerm2 API authentication cookie
ITERM2_KEY iTerm2 API authentication key
ITERM2_DEBUG Enable client protocol diagnostics when non-empty

Avoid storing authentication values in the YAML file or committing them to
version control.

Plugin Configuration

Plugin discovery and execution use environment variables rather than the YAML
file:

Variable Purpose
IT2_PLUGIN_PATHS Additional plugin directories
IT2_PLUGIN_DEADLINE Plugin execution deadline; defaults to 5s

PATH plugins take priority over IT2_PLUGIN_PATHS, and both take priority
over embedded plugins.

Stored but Not Applied

The configuration data model currently serializes the following additional
fields:

color: true
template: ""
retry_attempts: 3
retry_delay: 1s
log_level: info
verbose: false
debug: false
show_progress: true
cookie: ""
key: ""

it2 config show displays these values, but the main command does not
currently use them to control formatting, retry behavior, logging, progress,
or authentication. Treat them as reserved fields, not active runtime options.

The data model also reserves corresponding IT2_COLOR, IT2_TEMPLATE,
IT2_RETRY_ATTEMPTS, IT2_RETRY_DELAY, IT2_LOG_LEVEL, IT2_VERBOSE,
IT2_DEBUG, and IT2_SHOW_PROGRESS environment names. They are not command
behavior controls at present.

File Permissions

it2 config init creates ~/.it2 with mode 0700 and writes the configuration
file with mode 0600.

To repair permissions on an existing file:

chmod 700 ~/.it2
chmod 600 ~/.it2/config.yaml

Troubleshooting

# Confirm which file is read.
it2 config path

# Inspect effective file and environment values.
it2 config show

# Test the API connection with explicit root flags.
it2 --timeout 10s --format json auth check

YAML duration values must use Go duration syntax. Boolean values should be
true or false.

Next steps