CLI Reference
Look up startup commands, kftui flags, environment variables, data directories and logging options for kftray and kftui.
Use these commands to start kftray or kftui. Set environment variables to choose the configuration directory, credentials and proxies.
Desktop startup
# Launch from Applications folder
open /Applications/kftray.app
# Launch from terminal
/Applications/kftray.app/Contents/MacOS/kftrayWhen you start kftray from a terminal, it also prints log lines at the info level to that terminal. The desktop app writes its logs to the configuration directory. It doesn't use RUST_LOG to set the level.
Terminal launch
# Basic launch
kftui
# Load from a JSON file
kftui --configs-path config.json
# Load from GitHub repository
kftui --github-url https://github.com/team/configs --configs-path env/dev.json
# Auto-start all forwards
kftui --configs-path config.json --auto-start
# Non-interactive mode (no TUI)
kftui --json '[{...}]' --auto-start --non-interactive
# Read from stdin
cat config.json | kftui --stdin
# Discover annotated services and start forwards headlessly
kftui --auto-discover --context my-cluster --auto-start --non-interactive
# Start only the configs that match a filter
kftui --auto-start --non-interactive --filter tag:env=dev
# With custom terminal type
TERM=xterm-256color kftui
# Inside tmux session
tmux new-session -s kftray kftui
# Inside screen session
screen -S kftray kftuiCommand-line flags
| Flag | Description |
|---|---|
-c, --configs-path | Path to a JSON configuration file, or a path inside the repository with --github-url (comma-separate several paths) |
-s, --save | Save imported configs to the local database. Needs a config source |
-g, --github-url | GitHub repository URL to import configs from |
-a, --auto-start | Start all forwards on launch |
--non-interactive | Run without the terminal interface and keep forwarding until interrupted. Needs --auto-start or --save |
-j, --json | Inline JSON configuration string |
--stdin | Read configuration from stdin |
--flush | Replace existing configs with the imported ones. Nothing is cleared if the source can't be read or a config is invalid |
--filter | Show and start matching configs, such as tag:env=dev or namespace=api,web. Repeat the flag to combine conditions. All conditions must match |
--group-by | Group this terminal session by context, namespace, kubeconfig, workload_type, protocol, tag:<key> or none |
--auto-discover | Find services with Kubernetes annotations. Needs --context |
--context | Kubernetes context for auto-discovery |
--kubeconfig | Kubeconfig path for auto-discovery. Uses the system default if omitted |
--alias-as-domain | Use each discovered config's alias as its local domain |
--auto-loopback | Assign a loopback address to each discovered config |
--ssl | Turn on SSL/TLS for port forwarding (overrides settings) |
--log-level | Global log level: error, warn, info, debug, trace or off |
--logs-to-file | Write logs to app.log in the configuration directory instead of the Logs panel |
--no-update-check | Skip the update check at startup |
Config sources are mutually exclusive. See CLI mode and scripting for the rules, storage behavior and examples.
Environment variables
| Variable | Purpose | Example values |
|---|---|---|
KFTRAY_CONFIG | Configuration directory for the database and logs | /path/to/dir |
XDG_CONFIG_HOME | Parent of the kftray configuration directory when KFTRAY_CONFIG is unset | ~/.config |
KUBECONFIG | Custom kubeconfig path or multiple files | /path/to/config, /path/one:/path/two |
GITHUB_TOKEN | GitHub personal access token for private repository imports in kftui | ghp_xxxxxxxxxxxx |
DO_NOT_TRACK | Turns off crash reports and performance data, whatever the settings say | 1 |
HTTPS_PROXY | HTTPS proxy for Kubernetes API requests | http://proxy.example.com:8080 |
HTTP_PROXY | HTTP proxy for Kubernetes API requests | http://proxy.example.com:8080 |
NO_PROXY | Hosts that bypass the proxy | localhost,127.0.0.1,.local |
TERM | Terminal type for kftui | xterm-256color, screen-256color |
Data directories
kftray and kftui look for their files in one configuration directory on every operating system. kftray picks the first match:
KFTRAY_CONFIG$XDG_CONFIG_HOME/kftray~/.kftray(%USERPROFILE%\.kftrayon Windows)
| Path in the directory | Content |
|---|---|
configs.db | Configuration database |
http_logs/ | HTTP logs, written by both apps |
kftray_<date>_<time>.log | Desktop application logs |
logger-errors.log | Desktop logger errors |
app.log | kftui logs, with --logs-to-file |
kftray doesn't use ~/Library/Logs, ~/.local/share or %APPDATA% for these files. See Configuration for details.
Terminal keyboard shortcuts
| Key | Action |
|---|---|
↑ ↓ ← → | Navigate lists and sections |
Space | Mark or unmark an item |
a | Mark all items |
f | Start or stop the marked forwards |
i | Import configuration from a JSON file |
e | Export configurations to JSON |
d | Delete the marked configurations |
s | Open settings |
l | Turn HTTP logging on or off |
L | Set HTTP log retention and maximum size |
V | View HTTP logs |
o | Open HTTP logs in an external editor |
r | Replay an HTTP request from the log detail view |
v | Group by and filter configs |
t | Edit tags |
/ | Search |
h | Show help |
q | Show About |
Tab | Switch between sections |
Ctrl+C | Exit |
See the terminal interface guide for the full reference and workflow examples.
Debug logging
Raise the level to investigate connection failures, authentication errors or unexpected behavior.
# Terminal with debug output in the Logs panel
kftui --log-level debug
# Write the logs to <configuration directory>/app.log
kftui --log-level debug --logs-to-fileThe log output includes:
| Category | Details |
|---|---|
| Kubernetes API | Requests and responses |
| Port binding | Attempts and failures |
| Configuration | Database operations |
| Proxy server | Deployment events |
| HTTP parsing | Requests and responses when you turn on HTTP logging |
For the desktop app, open the log viewer from the footer menu, the tray menu or Settings > Log Files > View Logs, or read the kftray_*.log files in the configuration directory.