The K Shell handbook
Install on Windows, choose a theme, and run your first commands.
- 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.
Install K Shell
Open PowerShell from the Start menu. Paste this command and press Enter.
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 sourcePrefer 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 -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1 -PathScope UserThe repository’s install.ps1 also accepts -InstallDirectory, -Version, -NoTerminalProfile, and -PathScope None. Download the script first to use these options.
Open your first session
Close and reopen your terminal app to refresh PATH. In a new PowerShell or Command Prompt window, run:
kshellUsing Windows Terminal? Open its dropdown beside + and select K Shell. Once you see the › prompt, you’re inside K Shell.
› help
Type help and press Enter to see the available commands.
PowerShell means your Windows setup shell. K Shell means the new shell you just opened. Run each example in the place its label names.
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.
- Inside the installed K Shell, run
themeto open the theme picker. - Use ↑ and ↓ to preview a design: Powerline, Atomic, Bubblesline, Cert, or Negligible.
- Press Enter to install and activate your selection. It is saved automatically for future sessions. Press Esc or Ctrl + C to cancel.
themeInstall a theme with commands instead
Run each line inside K Shell. List the designs, install Atomic, then activate it:
theme list
theme install atomic
theme atomic
theme statusReplace 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.
C:\Users\you\projects
› ls
› cargo build --release
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.
theme midnight
theme icons nerd
theme suggestions softPalette, 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.
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.
- Open Windows Terminal’s dropdown beside +, then choose Settings.
- Under Profiles, select K Shell and open its Command line field.
- Paste the command below, select Save, then open a new K Shell tab.
"%LOCALAPPDATA%\Programs\KShell\kshell.exe" --theme midnight --icons nerd --suggestions softThis 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.
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 referenceSet 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.
[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 commandsTry your first commands
Start by looking around your current folder. Run each line separately inside K Shell.
pwd
ls -la
tree -L 2Create 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.
mkdir kshell-demo
cd kshell-demo
write notes.txt 'Hello from K Shell'
cat notes.txtYou should see Hello from K Shell printed below your command.
| Command | Use it to |
|---|---|
cd .. | Go up one folder |
history 10 | See your last 10 history entries |
theme | Preview, install, and select a prompt theme |
theme status | Check your current appearance settings |
help | Browse available commands and shortcuts |
exit | Leave 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.
Your shell is installed and your preferences are saved.
Install and switch tools with KPM
Install developer tools, keep isolated versions where supported, and choose which version K Shell runs.
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
kpm list
kpm install
kpm install node
kpm install javaRun 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.
kpm versions node
kpm versions java
kpm search javaPin a release or install without prompts
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@21These 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.
kpm install node@latest --yes
kpm install java@21 --yesNoninteractive 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
| Tool | Name | Installation and switching |
|---|---|---|
| Node.js | node | Official ZIP + SHA-256; isolated versions and switching. npm/npx use the selected Node. |
| Python | python | WinGet, user scope. One managed version; switching and in-place upgrade are unsupported. |
| Go | go | Official SDK ZIP + SHA-256; isolated versions and switching. |
| Rust | rust | Existing rustup client; private Rust/Cargo homes and pinned MSVC toolchains with switching. |
| PHP | php | Official NTS x64 ZIP + SHA-256; isolated versions and switching. Requires the matching Visual C++ runtime. |
| Git | git | WinGet, user scope. One managed version; switching and in-place upgrade are unsupported. |
| Java | java | Eclipse 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
kpm installed
kpm installed node
kpm current node
kpm use node
kpm use node@22.15.0
kpm use java@21
java -version
javac -versionuse 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
kpm upgrade node
kpm upgrade node@latest --yes
kpm uninstall node@22.15.0
kpm recoverUpgrade 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.
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.
HTTP requests with kreq
Test APIs and download files with K Shell’s built-in HTTP client. No separate curl installation is needed.
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.
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.
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
kreq get 'https://api.example.com/users/1' --json
kreq GET 'https://api.example.com/users/1' -jStatusCode : 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
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' headerBoth 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.
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
kreq get 'https://api.example.com/users/1' --raw
kreq get 'https://api.example.com/users/1' --raw --jsonFile 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.
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'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
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
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.
| Option | Behavior |
|---|---|
-j, --json | Pretty-print the response as JSON. Invalid or empty JSON returns an error. |
--raw | Show only the body, without the terminal summary. Combine with --json for body-only formatted JSON. |
-H, --header | Add a request header as 'Name: value'. Repeat for multiple headers. |
-d, --data | Send the supplied text exactly, without an added newline. |
-o, --output | Save raw response bytes to a file, overwriting an existing regular file. |
-i, --include | Include final response headers on stdout. With -o, the file contains only the body. |
-v, --verbose | Show request method and URL, headers, response status, and elapsed time on stderr. |
-L, --location | Follow up to 10 HTTP/HTTPS redirects. Redirects are off by default. |
-X, --request | Override the method, or supply it when only a URL is given. |
--timeout | Total network timeout in seconds. Default 30; positive fractions accepted, maximum 86400. |
--fail | Return status 22 on HTTP 4xx/5xx while still writing the response body. |
-h, --help | Show 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.
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.
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.
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:
& "$env:LOCALAPPDATA\Programs\KShell\kshell.exe" --helpIf 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 -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:
theme icons unicodeFor 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.
Uninstall K Shell
Follow these steps for a standard per-user installation. You can keep your command history for a future reinstall.
- 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.
- 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 - 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 - 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. - Restart your terminal app.
Close all Windows Terminal windows and reopen it so the removed profile and PATH change take effect.
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:
[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.
Build from source
Install stable Rust and the Windows MSVC build tools. In the Rust source folder containing Cargo.toml, run:
cargo build
cargo runYour debug executable is target/debug/kshell.exe. To build the distributable Windows x64 ZIP, first cache the full locked dependency graph:
cargo fetch --locked
.\scripts\Build-Release.ps1The packaging script builds offline and includes dependency license notices. Find the ZIP and checksum in target/packages. Recipients do not need Rust.
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.