The Kizuna CLI uses a TOML-based configuration system with support for multiple profiles, environment variable overrides, and cross-platform path conventions.

Configuration File

Location

Platform	Path
Linux	~/.config/kizuna/config.toml
macOS	~/.config/kizuna/config.toml
Windows	%APPDATA%\kizuna\config.toml

Run kz config path to see the exact paths on your system.

Initialize Configuration

kz config init

This creates the config directory and a default config.toml.

File Structure

# Default profile to use when --profile is not specified
default_profile = "default"

# Profile definitions
[profiles.default]
name = "default"
instance_url = "https://kizuna.yourdomain.com"
token = "kz_abc123..."            # Optional — set via `kz auth login`
default_org = "acme-corp"          # Optional — default organization
default_repo = "api-service"       # Optional — default repository

[profiles.staging]
name = "staging"
instance_url = "https://staging.kizuna.yourdomain.com"
default_org = "acme-corp"

[profiles.cloud]
name = "cloud"
instance_url = "https://cloud.kizuna.codes"

# API settings
[api]
timeout = 30      # Request timeout in seconds (default: 30)
retry = true      # Enable automatic request retries (default: true)

# UI preferences
[ui]
color = "auto"    # "auto", "always", or "never" (default: "auto")
format = "table"  # "table", "json", or "yaml" (default: "table")

Profiles

Profiles let you work with multiple Kizuna instances without re-authenticating.

Create a Profile

Edit config.toml directly or use the interactive wizard:

kz auth configure

Switch Profiles

# Switch default profile
kz auth switch staging

# Use a profile for a single command
kz --profile production auth status

View Active Profile

kz auth status

Credentials

Authentication tokens are stored separately from configuration for security:

Platform	Path
Linux	~/.config/kizuna/credentials.toml
macOS	~/.config/kizuna/credentials.toml
Windows	%APPDATA%\kizuna\credentials.toml

Security Note: The credentials file has restrictive permissions (600). Do not commit this file to version control.

Credentials Format

[profiles.default]
access_token = "kz_abc123..."
refresh_token = "kz_ref456..."
expires_at = "2026-04-01T00:00:00Z"

[profiles.staging]
access_token = "kz_stg789..."

Environment Variables

Environment variables override config file values:

Variable	Description	Example
KIZUNA_PROFILE	Override active profile	staging
KIZUNA_INSTANCE_URL	Override instance URL	https://kizuna.example.com
KIZUNA_TOKEN	Override auth token	kz_abc123...
KIZUNA_DEFAULT_ORG	Override default organization	acme-corp
NO_COLOR	Disable colored output	1

Example:

# Use in CI/CD without a config file
export KIZUNA_INSTANCE_URL="https://kizuna.example.com"
export KIZUNA_TOKEN="$CI_KIZUNA_TOKEN"
kz policy check --action "deploy.production" --resource "acme/api"

Data Directories

The CLI uses platform-standard directories for cache and data:

Directory	Linux/macOS	Windows	Purpose
Config	~/.config/kizuna/	%APPDATA%\kizuna\	Configuration and credentials
Cache	~/.cache/kizuna/	%LOCALAPPDATA%\kizuna\cache\	Cached API responses
Data	~/.local/share/kizuna/	%LOCALAPPDATA%\kizuna\data\	Audit logs, local state

Audit Log

Policy checks and invocations are logged locally at:

~/.local/share/kizuna/audit.log

This provides a local audit trail of all policy-related CLI operations.

Configuration Precedence

Values are resolved in this order (highest priority first):

1. Command-line flags (--profile, --instance, --json)
2. Environment variables (KIZUNA_INSTANCE_URL, etc.)
3. Profile settings in config.toml
4. Built-in defaults

Next Steps

• Commands Reference — All available commands
• TUI Guide — Terminal user interface
• Tutorial: CLI Workflow — Getting started with the CLI