Star

command line reference

both kftray interfaces operate primarily through their respective user interfaces, but understanding command-line behavior helps with automation, troubleshooting, and integration scenarios.

when command-line knowledge matters

command-line understanding becomes important when someone needs to integrate port forwarding into scripts, debug startup issues, or automate configuration management. developers working in CI/CD environments or server deployments particularly benefit from understanding these patterns.

the desktop interface (kftray) operates primarily through the graphical interface but accepts some command-line parameters. the terminal interface (kftui) provides keyboard-driven interaction rather than traditional command-line options.

desktop interface command-line behavior

startup and initialization

the desktop application launches through standard platform mechanisms: application bundle on macos, executable on windows, or AppImage on linux. double-clicking the application icon or using platform-specific launchers provides the typical startup method.

command-line execution works for automation and debugging scenarios:

# macOS
/Applications/KFtray.app/Contents/MacOS/KFtray

# Linux 
./KFtray.AppImage

# Windows
KFtray.exe

configuration directory and data location

the application stores configuration and state in platform-appropriate locations. understanding these paths helps with backup procedures and troubleshooting:

  • macOS: ~/Library/Application Support/kftray/
  • Linux: ~/.local/share/kftray/ or $XDG_DATA_HOME/kftray/
  • Windows: %APPDATA%\kftray\

the SQLite database (kftray.db) contains all configuration and state information. log files appear in app.log within the same directory.

debugging and verbose output

enabling debug output helps diagnose startup and connection issues. the application logs detailed information to the app.log file automatically, but console output provides immediate feedback during troubleshooting:

# Enable debug logging (varies by platform)
RUST_LOG=debug ./KFtray.AppImage

# On macOS with bundle
RUST_LOG=debug /Applications/KFtray.app/Contents/MacOS/KFtray

this approach shows initialization steps, kubernetes connectivity attempts, and port forwarding operations in real-time.

terminal interface interaction patterns

kftui operates entirely through keyboard commands within the terminal interface. the application doesn't accept traditional command-line arguments but responds to terminal environment variables and settings.

launching the terminal interface requires appropriate terminal dimensions and capabilities:

# Basic launch
kftui

# With specific terminal settings
TERM=xterm-256color kftui

# In screen or tmux session
screen -S kftray kftui
tmux new-session -s kftray kftui

terminal size requirements affect interface usability. minimum 80x24 character dimensions provide basic functionality, while larger terminals improve readability and information display.

keyboard command reference

the interface operates through single-key commands that perform immediate actions:

navigation commands:

  • arrow keys navigate through configuration lists
  • tab switches between interface sections
  • enter confirms selections and actions

configuration management:

  • i opens import dialog for JSON configuration files
  • e exports current configurations to JSON files
  • d deletes selected configurations with confirmation

port forwarding operations:

  • f toggles port forwarding for selected configurations
  • space bar selects individual configurations for batch operations
  • ctrl+a selects all configurations simultaneously

utility commands:

  • h opens contextual help for current interface section
  • q quits the application cleanly
  • r refreshes kubernetes context and service information

file import and export workflow

configuration management through file operations provides automation and sharing capabilities. the import process accepts JSON files with configuration arrays:

# Configuration file format
[
  {
    "service": "api-gateway",
    "namespace": "development", 
    "local_port": 8080,
    "remote_port": 80,
    "protocol": "tcp",
    "alias": "dev-api"
  }
]

export operations create files in the same format, suitable for version control, backup, or sharing across team members.

environment configuration and integration

kubernetes context management

both interfaces inherit kubernetes configuration from the environment. standard kubectl configuration applies directly to kftray operations:

# Context selection affects kftray behavior
kubectl config use-context development-cluster

# Custom kubeconfig location
export KUBECONFIG=/path/to/custom-config

# Multiple configuration files
export KUBECONFIG=~/.kube/config:~/.kube/dev-config

namespace access depends on kubernetes RBAC permissions. the same permissions that allow kubectl port-forward operations enable kftray port forwarding.

logging and output control

log level and output destination configuration helps with debugging and monitoring:

# Environment variable control
export RUST_LOG=info          # Basic information
export RUST_LOG=debug         # Detailed debugging
export RUST_LOG=warn          # Warnings and errors only

# Component-specific logging
export RUST_LOG=kftray=debug,kube=info

the terminal interface respects terminal capabilities and adjusts display accordingly. colorization, character encoding, and terminal type detection happen automatically based on environment variables.

automation and scripting integration

desktop interface automation

the desktop interface provides limited automation capabilities through configuration file management and system integration:

# Automated configuration deployment
cp team-configs.json ~/.local/share/kftray/
# Application detects and imports automatically

# Backup automation
tar -czf kftray-backup.tar.gz ~/.local/share/kftray/

github sync functionality provides team-level automation for configuration distribution and updates.

terminal interface scripting

the terminal interface works well in scripted environments with proper session management:

#!/bin/bash
# Example automation script

# Start persistent session
screen -dmS kftray-session kftui

# Import configurations (requires manual interaction)
# screen -S kftray-session -p 0 -X stuff 'i^M'

# Monitor session
screen -ls | grep kftray

fully automated operation requires pre-positioned configuration files and careful session management due to the interactive nature of the interface.

integration with development workflows

ci/cd pipeline integration

continuous integration scenarios often need programmatic port forwarding for testing:

# Example CI workflow component
if command -v kftui >/dev/null 2>&1; then
    # Launch in background session
    screen -dmS testing-forwards kftui
    
    # Wait for initialization
    sleep 5
    
    # Run tests against forwarded services
    npm run test:integration
    
    # Clean up
    screen -S testing-forwards -X quit
fi

this approach provides isolated port forwarding for testing scenarios without interfering with development environments.

container and orchestration usage

containerized development environments benefit from port forwarding automation:

# Example development container setup
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y curl screen
RUN curl -L -o kftui https://github.com/hcavarsan/kftray/releases/latest/download/kftui_amd64
RUN chmod +x kftui && mv kftui /usr/local/bin/

# Container startup can launch kftui in background
CMD ["screen", "-dmS", "kftray", "kftui"]

kubernetes environments can deploy the terminal interface for debugging and development access scenarios.

troubleshooting command-line issues

common startup problems

permission and dependency issues often prevent proper application startup:

# Check execution permissions
ls -la /usr/local/bin/kftui
chmod +x /usr/local/bin/kftui

# Verify dependencies (Linux)
ldd /usr/local/bin/kftui

# Check system requirements
echo $TERM
tput colors

library dependency problems typically indicate missing system packages or incompatible linux distributions.

configuration and state problems

command-line diagnostic procedures help identify configuration issues:

# Check configuration directory
ls -la ~/.local/share/kftray/

# Verify database accessibility
file ~/.local/share/kftray/kftray.db

# Review recent logs
tail -f ~/.local/share/kftray/app.log

database corruption or permission problems often require configuration directory cleanup and reinitialization.

kubernetes connectivity debugging

verifying kubernetes access independently helps isolate connection problems:

# Test basic connectivity
kubectl cluster-info

# Verify context and permissions
kubectl config current-context
kubectl auth can-i create pods

# Test port forwarding manually
kubectl port-forward svc/test-service 8080:80

these commands verify that kubernetes access works correctly outside of kftray, helping distinguish between kubernetes and application issues.

this reference provides the foundation for integrating kftray interfaces into various development and operational workflows while understanding the command-line aspects that support automation and troubleshooting scenarios.

Edit this page on GitHub
Table of Contents