K Shell/ Documentation

The K Shell handbook

Install on Windows, choose a theme, and run your first commands.

Before you begin
  • Windows 10 or 11, x64
  • PowerShell 5.1 or newer
  • No admin access or Rust needed

Windows Terminal is recommended. Already installed? Jump to configuration.

1

Install K Shell

Open PowerShell from the Start menu. Paste this command and press Enter.

PowerShell · install K Shell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/chaovanthoung168/k-shell/main/install.ps1 | iex"

When setup finishes, you’ll see “K Shell is ready.” Your Windows Terminal profile and user PATH are set up for you.

What does the installer change?

It downloads the latest stable GitHub release, verifies its SHA256 checksum, and installs into %LOCALAPPDATA%\Programs\KShell. It adds that folder to your user PATH and creates a K Shell profile in Windows Terminal.

Your default Terminal profile and command history are preserved. The execution-policy flag applies only to the setup process. This is an unsigned early Windows release.

Read the installer source
Prefer a portable ZIP or a custom installation?

Download the Windows x64 ZIP and its SHA256 file. Compare the checksum with Get-FileHash, extract the entire ZIP, and run kshell.exe for a portable session.

To install from the extracted folder instead:

PowerShell · extracted release folder
powershell -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1 -PathScope User

The repository’s install.ps1 also accepts -InstallDirectory, -Version, -NoTerminalProfile, and -PathScope None. Download the script first to use these options.

Next: open your first session
2

Open your first session

Close and reopen your terminal app to refresh PATH. In a new PowerShell or Command Prompt window, run:

PowerShell or Command Prompt
kshell

Using Windows Terminal? Open its dropdown beside + and select K Shell. Once you see the › prompt, you’re inside K Shell.

C:\Users\you

› help

K Shell

Type help and press Enter to see the available commands.

Watch the label above each command

PowerShell means your Windows setup shell. K Shell means the new shell you just opened. Run each example in the place its label names.

Next: choose your colors and icons
3

Choose your appearance

Install a prompt design, then choose a palette, icons, and suggestion style.

Install a prompt theme

A fresh installation starts with the original default prompt. Optional designs are bundled with K Shell and install offline, without downloading scripts or fonts.

  1. Inside the installed K Shell, run theme to open the theme picker.
  2. Use ↑ and ↓ to preview a design: Powerline, Atomic, Bubblesline, Cert, or Negligible.
  3. Press Enter to install and activate your selection. It is saved automatically for future sessions. Press Esc or Ctrl + C to cancel.
K Shell · open the theme picker
theme
Install a theme with commands instead

Run each line inside K Shell. List the designs, install Atomic, then activate it:

K Shell · run each line
theme list
theme install atomic
theme atomic
theme status

Replace atomic in both commands with powerline, bubblesline, cert, or negligible. Installing makes a design available; activating it saves your prompt choice.

To restore and save the original prompt, run theme default. Prompt selections are stored in %APPDATA%\kshell and survive upgrades. These installation commands require the installed shell; the browser Playground supports palette changes only.

Adjust colors, icons, and suggestions

Choose your settings below, check the illustrative preview, then copy the commands. These settings are separate from your installed prompt design.

Color palette

Quiet cyan with muted sage.

K Shell

C:\Users\you\projects

› ls

README.mdsrcapp.tsCargo.tomlnotes.txt

› cargo build --release

Illustrative previewTab accept suggestion
Icons
Suggestions

The Windows Terminal installer selects Nerd Font icons when a compatible Nerd Font is installed, with Unicode as the fallback.

Select an installed Nerd Font Mono in your terminal to display these file-type icons. Without one, choose Unicode above.

Apply to your current session

Copy these commands and run them one line at a time inside K Shell.

K Shell · run each line
theme midnight
theme icons nerd
theme suggestions soft

Palette, icon, and suggestion changes last for this session. theme status shows your current choices; theme reset restores the default prompt, Ocean, Unicode icons, and soft suggestions for this session. Use theme default to save the original prompt for future sessions. Your terminal controls its background and font.

Next: keep this look for future sessions
4

Save your preferences

Your installed prompt choice is already saved. Save your palette, icons, and suggestion style in the Windows Terminal profile so new tabs use those settings too.

  1. Open Windows Terminal’s dropdown beside +, then choose Settings.
  2. Under Profiles, select K Shell and open its Command line field.
  3. Paste the command below, select Save, then open a new K Shell tab.
Windows Terminal · Command line field
"%LOCALAPPDATA%\Programs\KShell\kshell.exe" --theme midnight --icons nerd --suggestions soft

This uses the standard install location. If you installed elsewhere, replace the quoted executable path with your own. The command stays in sync with the choices in step 3.

Adjust the terminal around your shell

In the K Shell profile’s Appearance settings, choose your font, text size, and background. For a larger prompt, try a font size of 16. Select an installed Nerd Font Mono before enabling Nerd icons.

Open K Shell by default in Windows Terminal

Go to Settings → Startup → Default profile, choose K Shell, then select Save. This changes the profile used for new Terminal windows and tabs.

Windows Terminal startup reference
Set defaults for launching kshell from other terminals

Run these lines in PowerShell to save preferences for your Windows user account. Restart your terminal app, then launch kshell.

PowerShell · save user defaults
[Environment]::SetEnvironmentVariable('KSHELL_THEME', 'midnight', 'User')
[Environment]::SetEnvironmentVariable('KSHELL_ICONS', 'nerd', 'User')
[Environment]::SetEnvironmentVariable('KSHELL_SUGGESTION_STYLE', 'soft', 'User')

Startup flags such as --theme midnight take priority over environment values. Update the Terminal profile above if it still opens with a different look. These values control the palette, icons, and suggestions; prompt designs are saved separately by the theme picker or theme <design>.

Windows Terminal profile reference

Next: try your first commands
5

Try your first commands

Start by looking around your current folder. Run each line separately inside K Shell.

K Shell · explore your files
pwd
ls -la
tree -L 2

Create a small practice project

Use a new folder name if kshell-demo already exists. These commands create a folder and write a sample note inside it.

K Shell · run each line
mkdir kshell-demo
cd kshell-demo
write notes.txt 'Hello from K Shell'
cat notes.txt

You should see Hello from K Shell printed below your command.

A few commands to keep nearby
CommandUse it to
cd ..Go up one folder
history 10See your last 10 history entries
themePreview, install, and select a prompt theme
theme statusCheck your current appearance settings
helpBrowse available commands and shortcuts
exitLeave K Shell

Installed developer tools come along, too. Try git status in a Git repository, cargo --version if Rust is installed, or code . if you use VS Code.

Setup complete

Your shell is installed and your preferences are saved.

Developer tools

Install and switch tools with KPM

Install developer tools, keep isolated versions where supported, and choose which version K Shell runs.

Available in the updated source build

The existing v0.1.6 download does not include KPM yet. Build the updated source, open that K Shell executable, and run kpm --help to check availability.

Choose one tool and a version

K Shell · interactive installation
kpm list
kpm install
kpm install node
kpm install java

Run each line separately. kpm install opens a single-tool menu. Giving a tool opens its version menu: a separate Latest Stable shortcut, the five newest distinct stable releases, and Other version for manual input. Versions are fetched from the provider; the entries need not have different major versions. Prereleases are excluded, and providers with fewer releases show fewer entries.

Use ↑ / ↓ to move, Enter to select, and Esc or Ctrl + C to cancel. From version selection, Esc returns to tool selection if you began without a tool. Discovery failures offer Retry/Cancel. Installed and saved active versions are marked.

K Shell · inspect available releases
kpm versions node
kpm versions java
kpm search java

Pin a release or install without prompts

K Shell · version syntax examples
kpm install node@22.15.0
kpm install python@3.13.2
kpm install go@1.24.1
kpm install rust@1.85.0
kpm install php@8.4.3
kpm install git@2.47.1
kpm install java@21

These version numbers illustrate syntax; KPM checks that the provider still offers the release. An exact version skips the selection menu and proceeds to confirmation. For Java, java@21 resolves the newest available Temurin JDK 21 patch/build. You can also specify the provider’s full version, such as java@21.0.6+7.

K Shell · noninteractive installation
kpm install node@latest --yes
kpm install java@21 --yes

Noninteractive installation and upgrade require an explicit version or @latest and --yes. The flag skips confirmation, never version validation. In a terminal, kpm install node --yes still asks you to select a version. Multiple tools in one installation command are rejected.

Know what each provider supports

KPM providers · Windows x64
ToolNameInstallation and switching
Node.jsnodeOfficial ZIP + SHA-256; isolated versions and switching. npm/npx use the selected Node.
PythonpythonWinGet, user scope. One managed version; switching and in-place upgrade are unsupported.
GogoOfficial SDK ZIP + SHA-256; isolated versions and switching.
RustrustExisting rustup client; private Rust/Cargo homes and pinned MSVC toolchains with switching.
PHPphpOfficial NTS x64 ZIP + SHA-256; isolated versions and switching. Requires the matching Visual C++ runtime.
GitgitWinGet, user scope. One managed version; switching and in-place upgrade are unsupported.
JavajavaEclipse Temurin JDK 17+ with compiler; isolated JDKs, switching, and child JAVA_HOME.

Python and Git require Microsoft’s App Installer/WinGet. The installer must support user scope, KPM’s custom destination, and a matching current-user registry InstallLocation. KPM refuses an existing unmanaged package and leaves unverifiable partial work pending for inspection. Confirmed WinGet installs accept package/source agreements; the installer may update user settings. To replace a managed Python/Git version, uninstall it before installing the next one.

Rust requires an existing native rustup client; KPM does not bootstrap it. Toolchains and Cargo data stay in KPM-private homes. PHP discovery covers the provider’s published releases JSON, so archive-only historical versions are unavailable. KPM never requests administrator elevation or changes system PATH.

Switch an installed version

K Shell · inspect and activate managed tools
kpm installed
kpm installed node
kpm current node
kpm use node
kpm use node@22.15.0
kpm use java@21
java -version
javac -version

use lists only installed, recorded versions and never downloads software. KPM verifies the selected executable before saving the change. For Java, it verifies both runtime and compiler, prioritizes that JDK’s bin folder, and sets JAVA_HOME for K Shell’s child processes.

Selections affect the next command immediately and persist across K Shell restarts. Managed PATH, JAVA_HOME, GOROOT, and Rust variables apply to child processes; the parent terminal’s environment stays unchanged. The shell still lacks variable expansion, so check Java using the version commands above.

The first switchable installation activates automatically after verification. With another version active, an interactive installation offers to activate the new one; --yes preserves the existing selection. Use kpm use to switch explicitly.

Upgrade, remove, or recover

K Shell · maintenance
kpm upgrade node
kpm upgrade node@latest --yes
kpm uninstall node@22.15.0
kpm recover

Upgrade selects a newer isolated release and retains older versions. Active uninstall confirmation includes deactivation; --yes authorizes that too. KPM removes only recorded managed installations, and WinGet removal rechecks the exact version and current-user installation location.

After a failed or cancelled installation, kpm recover verifies completed work before recording it, or cleans marked staging when no installation exists. If WinGet confirms its package is absent, recovery also cleans the marked incomplete destination. Recovered installations are not activated automatically. Unverifiable partial work stays pending for inspection; do not delete the store to bypass an error.

Progress and storage

Installation progress is an indeterminate marker moving left to right on stderr, without invented percentages. It uses about 30 refreshes per second and restores the cursor on completion, failure, or cancellation. Set KSHELL_KPM_FPS to 5–60 for a different refresh rate. Redirected stderr stays plain.

Storage defaults to %LOCALAPPDATA%\KShell\kpm. KSHELL_KPM_HOME selects an absolute private root; an empty value disables storage. KPM checks HTTPS sources and archive hashes, guards extraction paths and reparse points, serializes changes with a file lock, and saves installation records atomically. Brokered installers can outlive cancellation, so recovery checks the actual result; removal is not transactional.

Verification scope

The implementation is tested with mock providers, local archives, and test-owned native binaries. Live installation across all seven upstream providers still needs separate verification with their prerequisites. The browser Playground does not install software or run KPM.

Developer tools

HTTP requests with kreq

Test APIs and download files with K Shell’s built-in HTTP client. No separate curl installation is needed.

Available in the updated source build

The current v0.1.6 download does not include this command yet. After obtaining the updated source, follow Build from source and launch target/debug/kshell.exe. Run kreq --help to check availability.

Make your first request

Use kreq <METHOD> <URL> [OPTIONS] [content|headers]. Methods and response views are case-insensitive, and options can appear before or after the URL or view. The API addresses below are placeholders: replace them with your own service.

K Shell · response summary
kreq get 'https://api.example.com/users/1'

In an interactive K Shell session, responses show StatusCode, Content, RawContent, and Headers. StatusCode includes both the code and its description, such as 200 OK or 404 Not Found. Content shows the original compact text unless you request JSON formatting.

Example · terminal summary
StatusCode        : 200 OK
Content           : {"id":1,"name":"John","active":true}
RawContent        : HTTP/1.1 200 OK
                    content-type: application/json

                    {"id":1,"name":"John","active":true}
Headers           : {[content-type, application/json]}

Format JSON when you need it

K Shell · run either line
kreq get 'https://api.example.com/users/1' --json
kreq GET 'https://api.example.com/users/1' -j
Example · formatted Content field
StatusCode        : 200 OK
Content           : {
                      "active": true,
                      "id": 1,
                      "name": "John"
                    }

The other summary fields remain available. Objects, arrays, strings, numbers, booleans, and null are supported. Invalid or empty JSON writes an error to stderr and returns a nonzero status. This flag controls response formatting only; set the request’s Content-Type explicitly.

Choose content or headers

K Shell · select the response fields
kreq get 'https://api.example.com/users/1' --json content
kreq get 'https://api.example.com/users/1' content
kreq get 'https://api.example.com/users/1' headers
kreq get 'https://api.example.com/users/1' header

Both views keep StatusCode : 200 OK. Content view shows only that status and Content; headers view shows only that status and Headers. The singular header is an alias for headers. Headers view skips downloading the response body and ignores --json. Content view omits headers even with -i.

Example · JSON content view
StatusCode        : 200 OK
Content           : {
                      "active": true,
                      "id": 1,
                      "name": "John"
                    }

In raw, redirected, or batch output, content writes only the body; headers writes the HTTP status line and response headers. Use headers -o headers.txt to save that header block. The --fail exit-status behavior applies to both views.

Show only the response body

K Shell · body-only output
kreq get 'https://api.example.com/users/1' --raw
kreq get 'https://api.example.com/users/1' --raw --json

File output, redirected stdout, and batch or kshell -c execution omit the summary automatically. Raw output preserves the exact body bytes without added newlines or colors. With --json, body-only output is formatted JSON.

Terminal text previews retain up to 64 KiB; explicit JSON formatting displays the full parsed body. Binary bodies show their byte count. RawContent shows normalized response status and headers with up to 240 characters of the original body. Summary headers redact credentials and terminal controls are escaped. Forms are not parsed. The -i flag is redundant in a summary and keeps its header-output behavior in raw, batch, and file modes.

Send headers and a request body

Single-quote JSON to preserve its double quotes and Windows backslashes. Run each command on one line inside K Shell.

K Shell · JSON and plain-text requests
kreq post 'https://api.example.com/users' -H 'Content-Type: application/json' -d '{"name":"John","age":22}'
kreq post 'https://api.example.com/messages' -H 'Content-Type: text/plain' -d 'Hello World'
K Shell · other HTTP methods
kreq put 'https://api.example.com/users/1' -d 'replacement'
kreq patch 'https://api.example.com/users/1' -H 'Content-Type: application/json' -d '{"active":true}'
kreq delete 'https://api.example.com/users/1'
kreq head 'https://api.example.com/users/1' -i
kreq options 'https://api.example.com/users' -i
kreq -X PATCH 'https://api.example.com/users/1' -d 'updated'

Authenticate to your API

K Shell · replace TOKEN with your credential
kreq get 'https://api.example.com/profile' -H 'Authorization: Bearer TOKEN'
kreq get 'https://api.example.com/data' -H 'X-API-Key: TOKEN'

Headers are forwarded as supplied. Verbose logs redact authorization, API-key, token, secret, and cookie headers, including known request credentials reflected in response headers. URL query strings and fragments are omitted from logs; avoid verbose mode for private URL paths. Raw bodies and explicitly included headers remain server data. URL user/password credentials are rejected. With sensitive request headers, cross-origin redirects are refused to protect credentials.

Save a download or inspect a failure

K Shell · downloads and diagnostics
kreq get 'https://example.com/download' -L -o 'download.bin'
kreq get 'https://api.example.com/users' -o 'users.json'
kreq get 'https://api.example.com/users' --timeout 5 --fail -v
kreq --help

-o writes original bytes relative to the shell’s current folder; the parent folder must exist. With --json -o, JSON is validated first and the file retains the original bytes. Invalid JSON leaves the destination untouched. Raw downloads stream; explicit JSON formatting buffers the response in memory. Interrupted or failed transfers can leave partial raw output or files.

kreq options
OptionBehavior
-j, --jsonPretty-print the response as JSON. Invalid or empty JSON returns an error.
--rawShow only the body, without the terminal summary. Combine with --json for body-only formatted JSON.
-H, --headerAdd a request header as 'Name: value'. Repeat for multiple headers.
-d, --dataSend the supplied text exactly, without an added newline.
-o, --outputSave raw response bytes to a file, overwriting an existing regular file.
-i, --includeInclude final response headers on stdout. With -o, the file contains only the body.
-v, --verboseShow request method and URL, headers, response status, and elapsed time on stderr.
-L, --locationFollow up to 10 HTTP/HTTPS redirects. Redirects are off by default.
-X, --requestOverride the method, or supply it when only a URL is given.
--timeoutTotal network timeout in seconds. Default 30; positive fractions accepted, maximum 86400.
--failReturn status 22 on HTTP 4xx/5xx while still writing the response body.
-h, --helpShow all options and usage inside K Shell.

HTTP transactions return 0, including error responses unless --fail is used. HTTP failures with that flag return 22; usage errors return 2; network, TLS, timeout, JSON, and file errors return 1. Interactive Windows Ctrl + C cancels a request with status 130. These statuses also become the exit code of kshell -c.

Saving output inside K Shell

Internal pipes, shell redirection, variable expansion, and conditional scripting are still under development. Use -o for file output today. External host pipes and redirection preserve raw stdout. Quote URLs that contain & and paths that contain spaces.

Everyday use

Keyboard shortcuts

Complete commands, recall history, and move through your input.

Tab
Accept a visible suggestion, or complete and cycle through commands and paths.
→
Accept the suggestion at the end of your input. Enter runs it.
↑ / ↓
Move through command history.
Ctrl + R
Search previous commands.
Ctrl + L
Clear the terminal screen and scrollback.
Ctrl + C
Cancel the current input line.
Ctrl + D
Exit when the input line is empty.
Help

Troubleshooting

Find a fix for common installation and appearance problems.

“kshell is not recognized” after installation

Close all windows of your terminal app, then open it again. If the command still isn’t found, test the standard install path from PowerShell:

PowerShell · check the installed executable
& "$env:LOCALAPPDATA\Programs\KShell\kshell.exe" --help

If that works, add %LOCALAPPDATA%\Programs\KShell to your Windows user PATH, or rerun the installer. For a custom installation, use its actual path.

The K Shell profile is missing from Windows Terminal

Restart all Windows Terminal windows. You can still run kshell from PowerShell. To regenerate the profile after a standard installation, run:

PowerShell · regenerate the Terminal profile
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\Programs\KShell\Install-KShellProfile.ps1"

This restores the installed profile’s Midnight preset. Your executable stays installed. If you have a user override in Terminal settings, check its Command line field as well.

Icons appear as empty squares

Switch back to standard Unicode icons inside K Shell:

K Shell
theme icons unicode

For Nerd icons, install and select a compatible Nerd Font Mono in the terminal’s Appearance settings. K Shell does not install fonts. You can also turn icons off with theme icons off.

My theme changes disappear in a new tab

The theme picker and theme <design> save your prompt choice automatically. Palette, icon, and suggestion changes apply to the current session; follow step 4 to save those startup settings. Explicit --theme, --icons, and --suggestions flags override environment defaults.

If your prompt choice is not saved, check whether KSHELL_CONFIG_DIR is set: an empty value disables persistence; a custom directory must be writable. If theme install is unavailable, close K Shell and rerun the installer to update.

How do I update or remove K Shell?

To update, close your K Shell sessions and run the command from step 1 again. Setup keeps backups of the previous executable and profile.

To remove K Shell, follow the step-by-step uninstall guide below.

Remove K Shell

Uninstall K Shell

Follow these steps for a standard per-user installation. You can keep your command history for a future reinstall.

  1. Choose another default profile, then close K Shell.

    If K Shell is your Windows Terminal default, open Settings → Startup → Default profile and choose PowerShell or Command Prompt. Save, then close your K Shell tabs.

  2. Remove the application folder.

    Open File Explorer and paste the path below into its address bar. Back up any personal files you saved there, then delete the KShell folder, including its old executable backups. For a custom installation, use the folder you chose during setup.

    File Explorer · installation folder
    %LOCALAPPDATA%\Programs\KShell
  3. Remove the Windows Terminal profile.

    In File Explorer, delete the dedicated K Shell fragment folder at this path. Also remove any K Shell profile entries or overrides you added in Windows Terminal Settings.

    File Explorer · Terminal fragment folder
    %LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\K Shell
  4. Remove the user PATH entry.

    Search Windows for Edit environment variables for your account. Under User variables, select Path → Edit, remove the entry for your K Shell installation folder, and save. The standard entry is %LOCALAPPDATA%\Programs\KShell, or its expanded full path. Skip this step if you installed without adding PATH.

  5. Restart your terminal app.

    Close all Windows Terminal windows and reopen it so the removed profile and PATH change take effect.

Keep your history if you plan to return

Your default history file is %APPDATA%\mysh\history.txt. It lives separately from the installation. Leave it in place to reuse your commands after reinstalling. If you chose a custom KSHELL_HISTORY_FILE, keep that file instead.

Optional: clear saved appearance preferences

If you saved user environment defaults in step 4, run these lines in PowerShell to remove them, then restart your terminal app:

PowerShell · remove saved user preferences
[Environment]::SetEnvironmentVariable('KSHELL_THEME', $null, 'User')
[Environment]::SetEnvironmentVariable('KSHELL_ICONS', $null, 'User')
[Environment]::SetEnvironmentVariable('KSHELL_SUGGESTION_STYLE', $null, 'User')

If you added these settings to a PowerShell profile instead, remove those lines from that profile. A custom KSHELL_HISTORY_FILE setting can be removed separately; removing its environment setting does not delete the history file.

Optional: delete command history

To remove saved commands too, delete only the history file you used. The default is %APPDATA%\mysh\history.txt. If you configured a custom history path, use that file’s location. Deleting history removes those saved commands permanently.

Used the portable ZIP?

Close K Shell and delete the extracted portable folder after saving any personal files inside it. If you never ran the installer or registered a Terminal profile, the installation, PATH, and Terminal cleanup steps do not apply. Your separately stored history can still be kept.

Reinstall K Shell whenever you’re ready

For contributors

Build from source

Install stable Rust and the Windows MSVC build tools. In the Rust source folder containing Cargo.toml, run:

PowerShell · Rust source folder
cargo build
cargo run

Your debug executable is target/debug/kshell.exe. To build the distributable Windows x64 ZIP, first cache the full locked dependency graph:

PowerShell · Rust source folder
cargo fetch --locked
.\scripts\Build-Release.ps1

The packaging script builds offline and includes dependency license notices. Find the ZIP and checksum in target/packages. Recipients do not need Rust.

Explore the source on GitHub
Current release

Current limitations

K Shell supports single commands, native Windows applications, history, completion, and the configuration shown in this guide. Pipes, shell redirection, aliases, variable expansion, and full scripting are still under development.

Use write and append for file output today. Git, Node/npm, VS Code, and other developer tools are separate installations. Linux executables require their own compatible environment.

See what’s next for K Shell