CLI Reference

The ternux CLI is the permanent management interface for installation, diagnostics, repair, benchmarking, desktop lifecycle, and system information.

This reference describes the full Termux host command installed at $PREFIX/bin/ternux. The Debian/Xfce terminal has a separate guest-aware /usr/local/bin/ternux companion with only status, info, doctor (verify is an alias), env, --version, and help. It rejects host lifecycle commands instead of nesting a second PRoot session. Switch to Termux for every host command documented below.

Both commands are executed and version-checked during installation; file presence by itself is not considered a successful CLI installation.

Usage

ternux <command> [options] [subcommand]

Global flags

The dispatcher recognizes these flags before loading a command, so they may appear before or after the command name. Recognition is not a promise that every command has a machine-readable implementation. Do not pass --json to install, the live logs tail stream, or uninstall and expect a JSON schema; use it only where this page explicitly shows structured output. Shared dispatch/environment failures use command: "error", status: "fatal", and a message field; an unknown command also includes requested_command. A failure before lib/core.sh can load is necessarily plain stderr, not JSON.

Commands

ternux install

Install or reinstall the full ternux desktop environment.

ternux install [options]

ternux start

Start the Xfce4 desktop session. Runs the launcher (~/x.sh) which:

1. Cleans up any previous session
2. Starts PulseAudio with TCP bridge
3. Launches Termux:X11 display
4. Starts the VirGL server if needed
5. Enters the PRoot Debian container and starts Xfce4

ternux start

ternux stop

Stop the desktop session and clean up sockets.

ternux stop

Kills: termux-x11, pulseaudio, virgl_test_server, dbus. Removes: stale X11 sockets, pulse socket. Releases: wake-lock.

ternux restart

Restart the desktop session (stop + 1 second delay + start).

ternux restart

ternux doctor

Run system diagnostics. Checks 11 categories: Termux environment, storage, PRoot/Debian, Termux:X11, PulseAudio, Vulkan, GPU/backend, renderer, Android child-process setting, launcher, VirGL.

ternux doctor [--json]

JSON output example:

{
  "command": "doctor",
  "status": "warning",
  "gpu": "Adreno (730)",
  "backend": "zink",
  "renderer": "zink Vulkan (Adreno ... (MESA_TURNIP))",
  "vulkan": "yes",
  "issues": ["phantom_process_killer_enabled"],
  "recommended_actions": ["review Android process restrictions and other Signal 9 causes"]
}

ternux repair

Inspect and repair common issues in 6 steps:

1. Repair a broken curl/OpenSSL toolchain
2. Install a missing termux-x11-nightly host package
3. Validate/apply the configured GPU backend, reinstall missing validated Turnip targets when needed, and align the launcher with that backend
4. Regenerate a still-missing or syntactically broken launcher
5. Clear a populated Mesa shader cache
6. Add a missing PulseAudio TCP bridge

A successful health check is not counted as a performed repair. A partial failure returns non-zero; restart the desktop and verify the renderer after a backend or launcher repair.

ternux repair

ternux verify

Verify installation completeness. Checks binaries, launcher, Debian container, and GPU driver files. A failed verification returns a nonzero exit status in both human and --json modes.

ternux verify [--json]

ternux benchmark

Run GPU benchmarks inside the Debian container (requires active desktop).

ternux benchmark [--json]

Benchmarks:

• glmark2 — OpenGL 2.0 performance score
• vkmark — Vulkan performance score
• Renderer inspection — identifies Zink/Turnip, VirGL/virpipe, or software rendering; a VirGL name alone does not prove a hardware-backed path

ternux profile

Device hardware profiling and management.

ternux profile <subcommand> [name]

JSON output (ternux profile --json):

{
  "command": "profile",
  "status": "complete",
  "android_version": "14",
  "architecture": "aarch64",
  "gpu": "Adreno (730)",
  "backend": "zink",
  "vulkan": "yes (Adreno)"
}

ternux backend

GPU backend management.

ternux backend <subcommand> [backend]

JSON output (ternux backend --json):

{
  "command": "backend",
  "status": "ok",
  "gpu": "Adreno (730)",
  "backend": "zink",
  "renderer": "zink Vulkan (Adreno ... (MESA_TURNIP))",
  "vulkan": "yes (Adreno)",
  "available_backends": "zink,virgl"
}

ternux info

Show system information summary: device model, Android version, GPU, backend, renderer, Vulkan status, and the readable Android child-process setting.

ternux info [--json]

ternux state

Show installation state: completed phases, configuration, benchmark and repair history.

ternux state [--json]

ternux logs

View and manage log files.

ternux logs <subcommand> [n]

ternux update

Self-update ternux CLI from GitHub.

ternux update [check]

ternux uninstall

Scoped removal of ternux components. With no action, an interactive menu is shown. In a non-interactive shell, name the action explicitly.

ternux uninstall [session|launcher|state|container|all] [--yes]

Options menu:

• 1 / session — stop the desktop and remove stale sockets
• 2 / launcher — remove ~/x.sh and the delimited shell-alias blocks
• 3 / state — remove ternux state and logs (not the container)
• 4 / container — delete the Debian container and everything inside it
• 5 / all — perform all four actions above
• 0 — cancel

all does not uninstall Termux packages or the ternux CLI/libraries, revoke storage access, reset mirrors, or revert the Termux PulseAudio configuration. Container deletion requires confirmation. --yes is intended only for a caller that deliberately accepts irreversible data loss.

Shell completion

Bash completion is available in share/ternux-completion.bash:

source share/ternux-completion.bash

This provides tab-completion for all commands, subcommands, flags, and saved profile names.

Environment variables

Every variable below is read at startup; command-line flags always win.

Full descriptions: Configuration → Installer output.

Architecture

bin/ternux          ← Thin command/flag dispatcher
lib/core.sh         ← Shared I/O, JSON builder, state, logging
lib/help.sh         ← Central help system
lib/detect.sh       ← Device detection (GPU, Vulkan, Android, etc.)
lib/desktop.sh      ← Desktop lifecycle (start, stop, restart)
lib/doctor.sh       ← Diagnostics + verification
lib/info.sh         ← System information
lib/backend.sh      ← GPU backend management
lib/profile.sh      ← Device profiling
lib/benchmark.sh    ← GPU benchmarks and renderer classification
lib/repair.sh       ← Repair engine using validated phase implementations
lib/logs.sh         ← Log management
lib/update.sh       ← Self-update
lib/state.sh        ← Installation state
lib/uninstall.sh    ← Scoped, confirmed component removal
lib/phases.sh       ← 11-phase installation implementation
lib/ui.sh           ← Installer renderer: dashboard, plain frame, log stream

Adding a new command:

1. Create lib/<name>.sh with a tnx_cmd_<name>() function
2. Add help in lib/help.sh with tnx_help_<name>()
3. Done — auto-discovered by the dispatcher

ternux — Copyright (c) 2026 Sobuj Miah (@soobujmiah) · Apache-2.0