foxshell/README.md

FoxShell

A powerful and user-friendly configuration for Zsh that works out of the box. FoxShell combines the best Zsh plugins into a coherent whole that feels like a finished product rather than a DIY starter kit.

If you want a great shell that just works, this project is for you.

Table of contents

• 1. Features
• 2. Installation
• 3. Usage
  • 3.1. Accepting autosuggestions
  • 3.2. Completing commands
  • 3.3. Searching command history
  • 3.4. Interactive search with fzf
  • 3.5. SSH
• 4. Customization
  • 4.1. Customizing prompt
  • 4.2. Customizing appearance
  • 4.3. Additional Zsh startup files
• 5. Updating
• 6. Uninstalling
• 7. Advanced configuration tips

Features

• Powerful POSIX-based shell preconfigured to work great out of the box.
• Easy-to-use installation wizard. Does not require git, zsh or sudo.
• Syntax highlighting for the command line.
• Autosuggestions for commands based on command history.
• Command prompt configurable through a builtin configuration wizard.
• Command completions and history searchable with fzf.
• Super fast. No lag when you open a new tab in the terminal or run a command.
• The complete shell environment can be automatically teleported to the remote host when connecting over ssh. This does not require git, zsh or sudo on the remote host.
• Command history can be shared across different hosts. For example, history from ssh foo can be made available within ssh bar and/or on the local machine.

Installation

Run this command in bash, zsh, or sh:

if command -v curl >/dev/null 2>&1; then
  sh -c "$(curl -fsSL https://git.foxdale.tech/Arctic/foxshell/raw/branch/main/install)"
else
  sh -c "$(wget -O- https://git.foxdale.tech/Arctic/foxshell/raw/branch/main/install)"
fi

The installer backs up the existing Zsh startup files, creates new ones, installs everything necessary for FoxShell, starts a new shell, and configures it as login shell. It asks for confirmation on every step so that you are always in control. Installation requires curl or wget. It does not require git, zsh, sudo or anything else.

Usage

If you've used Zsh, Bash or Fish before, FoxShell should feel familiar. For the most part everything works as you would expect.

Accepting autosuggestions

All key bindings that move the cursor can accept command autosuggestions. For example, moving the cursor one word to the right will accept that word from the autosuggestion. The whole autosuggestion can be accepted without moving the cursor with Alt+M/Option+M.

Autosuggestions in FoxShell are provided by zsh-autosuggestions. See its homepage for more information.

Completing commands

When completing with Tab, suggestions come from completion functions. For most commands completion functions are provided by Zsh proper. Additional completion functions are contributed by zsh-completions. See its homepage for the list of commands it supports.

Ambiguous completions automatically start fzf. Accept the desired completion with Enter. You can also select more than one completion with Ctrl+Space or all of them with Ctrl+A.

Searching command history

Up and Down keys fetch commands from history that contain what you've already typed on the command line. For example, if you press Up after typing grep, you'll see the last executed command that contains grep.

Ctrl+R starts fzf to search over history.

Interactive search with fzf

Several UI elements in FoxShell use fzf to quickly select an item from a potentially large list of candidates. You can type multiple search terms delimited by spaces. For example:

^music .mp3$ sbtrkt !fire

Token	Match type	Description
wild	substring	Items with the substring wild
^music	prefix	Items that start with music
.mp3$	suffix	Items that end with .mp3
!wild	inverse substring	Items without the substring wild
!^music	inverse prefix	Items that do not start with music
!.mp3$	inverse suffix	Items that do not end with .mp3

A single bar (|) acts as an OR operator. For example, the following query matches entries that start with core and end with either go, rb, or py.

^core go$ | rb$ | py$

See fzf homepage for more information.

SSH

When you connect to a remote host over SSH, your local FoxShell environment can be teleported over to it. The first login to a remote host may take some time. After that it's as fast as normal ssh.

Search for "ssh" in your ~/.zshrc for information on how to enable and configure SSH teleportation.

Customization

You can (and should) edit ~/.zshrc to customize your shell. It's a very good idea to read through the whole file to see which customization options are in there and to flip some of them to your liking.

When adding your customizations, put them next to the existing lines that do similar things. The default ~/.zshrc contains the following types of customizations that should serve as examples:

• Export environment variables.
• Extend PATH.
• Define aliases.
• Add flags to existing aliases.
• Define functions.
• Source additional local files.
• Load Oh My Zsh plugins.
• Clone and load external Zsh plugins.
• Set shell options.
• Autoload functions.
• Change key bindings.

Customizing prompt

Prompt in FoxShell is provided by Powerlevel10k. Run p10k configure to access its interactive configuration wizard. Further customization can be done by editing ~/.p10k*.zsh files. There can be more than one configuration file to account for terminals with limited capabilities. Most users will ever only see ~/.p10k.zsh. When in doubt, consult $POWERLEVEL9K_CONFIG_FILE. This parameter is set by FoxShell and it always points to the Powerlevel10k config file currently in use.

Customizing appearance

FoxShell uses a dark theme by default. You can customize colors and appearance by editing the configuration files or using the built-in configuration wizard.

Additional Zsh startup files

FoxShell sources additional files if they exist:

• ~/.env.zsh - Environment variables and other shell configuration
• ~/.zshrc.local - Additional personal configuration

Updating

Run foxshell update to update FoxShell and all its components.

Uninstalling

To uninstall FoxShell:

rm -rf -- "${XDG_CACHE_HOME:-$HOME/.cache}/foxshell"

Then restore your original zsh configuration files if you have backups.

Advanced configuration tips

FoxShell is designed to be highly configurable. Here are some advanced tips:

• Use zstyle commands to configure various aspects of the shell
• Add custom key bindings with foxshell bindkey
• Install additional plugins with foxshell install
• Use foxshell source to source additional files
• Use foxshell load to load plugins

For more information, see the configuration files in ~/.zshrc.