CLI Mode and Scripting

kftui accepts command-line flags to load configurations, automate port forwards and run in scripts and pipelines.

Command-line flagsCopy Anchor Link

# Load configs from a local JSON file
kftui --configs-path config.json

# Load and save configs to the local database
kftui --configs-path config.json --save

# Load from a GitHub repository
kftui --github-url https://github.com/team/configs --configs-path env/dev.json

# Merge configs split across several files in the repository
kftui --github-url https://github.com/team/configs --configs-path env/dev.json,env/shared.json

# Auto-start all forwards on launch
kftui --configs-path config.json --auto-start

# Non-interactive mode (no TUI, forward and block)
kftui --json '[{"alias":"api","service":"api","namespace":"default","local_port":8080,"remote_port":80,"context":"dev","workload_type":"service","protocol":"tcp"}]' --auto-start --non-interactive

# Read configs from stdin
echo '[{"alias":"api",...}]' | kftui --stdin

# Replace existing configs with the imported ones
kftui --configs-path config.json --flush

# Only start configs tagged team=payments
kftui --auto-start --non-interactive --filter tag:team=payments

Config sourcesCopy Anchor Link

Pick one source per run: --configs-path, --github-url (with --configs-path), --json, --stdin or --auto-discover. kftui rejects a command that mixes independent sources.

Related flags need their parent flag. --save needs a source, --context needs --auto-discover, and --kubeconfig, --alias-as-domain and --auto-loopback need --auto-discover.

For a GitHub source, kftui trims spaces around each comma-separated path, skips empty entries and combines all the files into one list. A local --configs-path accepts one file name.

Storage: file or memoryCopy Anchor Link

• With no source, or with --save, kftui uses the file database in the configuration directory.
• With a source and no --save, kftui keeps the configs in an in-memory database. They disappear when kftui exits and never touch the file database. That run also sends no crash reports.

Import safetyCopy Anchor Link

kftui loads, parses and validates the whole source before it does anything else. A missing file, malformed JSON or an invalid config stops the run. With --flush, the clear happens only after that check, so an invalid source can't wipe your stored configs.

Importing is not a single database transaction. kftui clears the old configs first, then writes the new ones one at a time. If a database error hits in between, you can end up with an empty or partial set. Export your configs before you flush.

--flush only applies to the file database. Without --save, the in-memory database starts empty anyway.

Auto-start and filtersCopy Anchor Link

--auto-start starts every loaded config. When you also pass a source, it starts only the configs from that source. With --filter, it starts only the matching ones. --group-by changes how the tables look and doesn't change which configs start.

Non-interactive modeCopy Anchor Link

Combine --auto-start and --non-interactive to run forwards without opening the terminal interface. kftui starts the configured forwards and keeps running until you stop it.

kftui --configs-path config.json --auto-start --non-interactive

Use this mode for:

• Background port forwards on a server.
• Container-based development environments.
• CI/CD jobs that need port access during tests.

On Ctrl+C or SIGTERM (Unix), kftui stops the forwards it started and exits. Stops run in parallel under one shared deadline. If some forwards can't stop in time, kftui exits with an error. A second interrupt during the wait also ends with an error.

Without --auto-start, --non-interactive needs --save. kftui then imports and saves the configs, prints Configurations processed and exits.

In the interface, Ctrl+C or the Exit menu item stops the forwards before kftui exits. Graceful SIGTERM handling exists only in non-interactive mode.

Stdin and JSON inputCopy Anchor Link

You can pipe configurations in without creating files:

# Inline JSON
kftui --json '[{"alias":"api","service":"api","namespace":"default","local_port":8080,"remote_port":80,"context":"dev","workload_type":"service","protocol":"tcp"}]' --auto-start

# From another command
kubectl get configmap kftray-config -o jsonpath='{.data.config}' | kftui --stdin --auto-start

--stdin fails if stdin is a terminal, so pipe or redirect data into it.

Auto-discoveryCopy Anchor Link

Discover annotated services and start them without the interface:

kftui --auto-discover --context my-cluster --auto-start --non-interactive

This finds all annotated services in the context, starts a forward for each and keeps them running until Ctrl+C. See Auto Import for the annotation format and more examples.

CI/CD integrationCopy Anchor Link

In a CI pipeline, run kftui in non-interactive mode in the background so the forwards stay up while tests run:

# GitHub Actions example
- name: Start port forwards
  run: |
    kftui --configs-path config.json --auto-start --non-interactive &
    echo $! > kftui.pid
    sleep 5

- name: Run integration tests
  run: npm test

- name: Stop port forwards
  if: always()
  run: kill "$(cat kftui.pid)"

kill sends SIGTERM, so kftui stops its forwards and exits. A start can take up to 60 seconds while kftui waits for a Ready pod. Account for this startup deadline when choosing the wait time.

The same pattern works in a shell script:

kftui --configs-path config.json --auto-start --non-interactive &
KFTUI_PID=$!
npm test
kill $KFTUI_PID

Automation with tmux and screenCopy Anchor Link

For long-running forwards, run kftui in a detached terminal session:

# Start kftui in tmux, auto-forward all configs
tmux new-session -d -s kftray 'kftui --configs-path config.json --auto-start'

# Check if session is running
tmux has-session -t kftray 2>/dev/null && echo "Running"

# Attach to running session
tmux attach -t kftray

# Start in screen session
screen -dmS kftray kftui --configs-path config.json --auto-start

# Reattach
screen -r kftray

LogsCopy Anchor Link

By default kftui shows logs in the Logs panel and records warnings and errors. Use --log-level debug for more detail, and --logs-to-file to write them to app.log in the configuration directory.

Environment variablesCopy Anchor Link

See CLI Reference for startup commands and data directory paths.