KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

thefly

★ 84 Open GitHub ↗

shell teleporter plugin/dotfiles manager (bash/zsh/ksh/fish)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Joknarf Tools](https://img.shields.io/badge/Joknarf%20Tools-Visit-darkgreen?logo=github)](https://joknarf.github.io/joknarf-tools)
[![Build and Release Packages](https://github.com/joknarf/thefly/actions/workflows/release.yml/badge.svg)](https://github.com/joknarf/thefly/actions/workflows/release.yml)
[![Shell](https://img.shields.io/badge/shell-bash%20|%20zsh%20|%20ksh%20|%20fish%20-blue.svg)]()
[![OS](https://img.shields.io/badge/OS-Linux%20|%20macOS%20|%20SunOS%20...-blue.svg)]()
[![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](https://shields.io/)
[![Packages](https://img.shields.io/badge/Packages-%20rpm%20|%20deb%20|%20pkg%20|%20apk%20|%20brew%20-darkgreen.svg)](https://github.com/joknarf/thefly/releases/latest)

# thefly

<br/>
bash/zsh/ksh/fish plugin/dotfiles manager and teleporter

Your shell env and plugins are available everywhere (hosts/users)

bzzz bzzz !

<br/>

What's the point to have a fine tuned local shell environment if you lose it as soon as you connect to another server / sudo to another user ?

## Demo

![thefly_demo](https://github.com/user-attachments/assets/76fd9863-f99e-4865-a3c5-9599ea9a2be3)

Get full coherent new shell experience using joknarf plugins ! (you may install any other plugins too)

|link                                                         |description                                                             |
|-------------------------------------------------------------|------------------------------------------------------------------------|
|[joknarf/nerdp](https://github.com/joknarf/nerdp)            |nerd dynamic customizable nice prompt                                   |
|[joknarf/seedee](https://github.com/joknarf/seedee)          |access/search dir history with ctrl or shift down arrow, and much more  |
|[joknarf/redo](https://github.com/joknarf/redo)              |access/search shell history command menu with shift-tab, and much more  |
|[joknarf/complete-ng](https://github.com/joknarf/complete-ng)|tab completion with interactive menu                                    |
|[__joknarf/shell-ng__](https://github.com/joknarf/shell-ng)  |__optimized joknarf compilation of the above plugins__                  |
|[joknarf/pgtree](https://github.com/joknarf/pgtree)          |process search / tree / kill command line                               | 
|[joknarf/lsicon](https://github.com/joknarf/lsicon)          |ls command enhancer (colors/icons/tree)                                 | 
|[joknarf/dfbar](https://github.com/joknarf/dfbar)            |df command enhancer (colors/usage bar)                                  |

need to test before adopting thefly ? Just try my own [flypack](https://github.com/joknarf/flypack) (temporary install in `/tmp/.fly.$UID`, xz needed):
```
. <(curl -Ls https://raw.githubusercontent.com/joknarf/flypack/main/fly.pak)
```

## features

Keep your full shell environment anywhere you go, just maintain it once and teleport it !

* supports bash / zsh / ksh / fish (on Linux / MacOS / ...)
  * fish needs a bash installed on hosts (teleport code relies on POSIX+) and has limitations
* multi-shell plugin manager to install / update / uninstall shell plugins
* multi-shell dotfiles manager
* teleport dotfiles and plugins through sudo (`flyas`)
* teleport dotfiles and plugins through ssh (`flyto`)
* teleport dotfiles and plugins though docker (`flyin`)
* chain env teleportations though sudo and ssh (`flyto <host> -- flyas <user>...`)
* nothing to install on remote servers (standard gnu/unix tools only)
* no configuration modification on target user/host when teleporting, resides on `/tmp`
* automatic cleaning of tmp teleportation directory when last fly session exits (`flock` needed)
* force specific destination shell when sudo or ssh (not using target user shell)
* directly execute commands using teleported env (fish excluded)
* flyto (ssh) connection history / completion (`sqlite` needed)
* lightweight/fast, only few KB / pure shell
* create a single pak env file including dotfiles and plugins to be used anywhere (`flypack >pak`, `. ./pak`)
* get a full coherent nice/powerfull environment with joknarf plugins: visit [Joknarf Tools](https://joknarf.github.io/joknarf-tools)

## Install

```
. <(curl https://raw.githubusercontent.com/joknarf/thefly/main/thefly) install
```
or
```
git clone https://github.com/joknarf/thefly
. thefly/thefly install
```
Creates `~/.fly.d/fly` and activate thefly manager for current user

under `fish` do not source, execute `thefly install` then `. ~/.fly.d/fly.fish activate`

or use your prefered method according to your OS:

```
brew install joknarf/tools/thefly
```

```
sudo dnf install https://github.com/joknarf/thefly/releases/latest/download/thefly.rpm
```

```
curl -OL https://github.com/joknarf/thefly/releases/latest/download/thefly.deb
sudo dpkg -i thefly.deb
```

```
curl -OL https://github.com/joknarf/thefly/releases/latest/download/thefly.apk
sudo apk add --allow-untrusted thefly.apk
```

```
curl -OL https://github.com/joknarf/thefly/releases/latest/download/thefly.pkg
sudo installer -pkg thefly.pkg -target /
```

then run:
```
thefly install
. ~/.fly.d/fly activate
```

Add in your rc file (.profile .bash_profile .bashrc .zshrc):
```
. ~/.fly.d/fly source
```
for `fish` add in your `.config/fish/config.fish`:
```
. ~/.fly.d/fly.fish source
```
Get some help
```
fly help
```
## Plugins management

* add plugin from github repo `fly add <githubuser>/<repo>`, example:
```
fly add joknarf/redo
```
clones `https://github.com/joknarf/redo` in `~/.fly.d/plugins/redo` and sources the `plugin.<shell>`

(all plugins in `~/fly.d/plugins/*/*.plugin.<shell>` will be sourced at login with `fly source` in your shell rc file)

for fish plugins, the sourced files are in `~/.fly.d/plugins/*/conf.d/*.fish`, (`thefly` will add `functions/completions` directories to fish if present). Need to execute `fly.fish source` after adding plugin to activate.

* update plugin
```
fly update [plugin]
```

* remove plugin
```
fly del [plugin]
```

* update user fly
```
fly upgrade
```

## Teleport plugins/shell env

thefly is able to duplicate your .fly.d directory through sudo and ssh to login with your full environment.

When teleporting the .fly.d is duplicated (without cvs files/tests) in :
```
/tmp/.fly.$UID/<id>/.fly.d
```
files are owned by target user, `$FLY_HOME` is set to `/tmp/.fly.$UID/<id>`

You can use all teleport method multiple times (`flyto host` then `flyas user`...)

### To another user

sudo login interactive shell to another user with your env
(current user need to have sudo privilege to target user)

```
$ flyas <user> [<command> [<arg>]...]
or
$ fsu <user> [<command> [<arg>]...]
```
By default uses `<user>`'s shell.
To force destination shell, use `bsu` (bash) `zsu` (zsh) `ksu` (ksh)

shellcode/command executed using PATH of your fly env, and can use any function/alias defined.

### To another host

ssh connect with interactive shell to another host with your env
```
$ flyto [<ssh opts>] <user>[<@host>] [-- <shellcode>|<command> [<arg>]...] 
or
$ fssh [<ssh opts>] <user>[<@host>] [-- <shellcode>|<command> [<arg>]...]
```

by default uses `<user>` shell, to force your favorite shell use `fsshb` (bash) - `fsshz` (zsh) - `fsshk` (ksh)

shellcode/command executed using PATH of your fly env, and can use any function/alias defined.

you can, for example, cumulate multiple teleportations:
```
fsu user1 fto host1 -- fsu user2 fto host2
```

flyto history located at `~/.fly_history` (`sqlite` package need to be installed)  
it can be accessed using: `flyto -H <search>`  
or just using flyto tab completion (bash/zsh)  
(better rendering with `joknarf/shell-ng` plugin)

### To a container

Enter a docker/podman container with your full environment using `flyin`
```
flyin [<user>@]<container> [cmd]
```

### To another shell

Change current shell and load your env/plugins :  
```
$ flysh <shell> # shell in bash ksh zsh
```
or `fbash` - `fzsh` - `fksh`  
 
## Customize env

* You can use `FLY_TMPDIR` variable to set the teleportation destination directory instead of default `/tmp` (/tmp could be mounted as noexec, or being full...):

```
FLY_TMPDIR=/var/tmp
flyto myserver
flyas myuser
````

* `FLY_TARZ` variable can be set to customize tar compression used for teleportation (default `-z` uses gzip, recommended `-J` to use xz is your servers have xz installed).

`thefly` is using a ssh embedded RemoteCommand containing compressed tar/base64 of your `.fly.d` if size under 128K (maximum command size), if size exceeds 128K, thefly will need to connect twice (once to transfer fly package, then spawn shell)

* Putting your env in `~/.fly.d/.flyrc` will be automatically sourced (must be compatible with different shells, using fish won't source `.flyrc`)

* Putting additional shell specific env in `~/.fly.d/.<shellname>rc` (.bashrc/.kshrc/.zshrc), will be automatically sourced for shell.

anything in `~/.fly.d` will be available through ssh/sudo (flyto/flyas) in `$FLY_HOME/.fly.d`

For example, just put your `.vimrc` in `~/.fly.d` and add in `~/.fly.d/.flyrc`:
```
export VIMINIT="source $FLY_HOME/.fly.d/.vimrc"
```
same for `.inputrc`, put it in `~/.fly.d` and add in `~/.fly.d/.flyrc`:
```
export INPUTRC="$FLY_HOME/.fly.d/.inputrc"
```
You can create a `.fly.d/bin` directory and put scripts you want to teleport and add in your `.fly.d/.flyrc`:
```
export PATH="$PATH:$FLY_HOME/.fly.d/bin"
```

## Standalone fly package

Save your whole shell environment to use everywhere with standalone fly package.

All your ~/.fly.d environment saved in autoextractable file. The fly package enables your env when sourced.

Build your fly package (you can copy and use it directly to get your env or make it available on web server to remote download)  
```
flypack >fly.pak
```
Then use your fly.pak anywhere :

`. ./fly.pak` : to activate your environment (in `/tmp/.fly.$UID`)

`. ./fly.pak install` : to extract in ~/.fly.d and activate

under `fish` shell, do not source as not fish code, you can do `bash fly.pak [install]` then source the `fly.fish`

To activate from url:
```
. <(curl -sL https://raw.githubusercontent.com/joknarf/flypack/main/fly.pak)
```
to connect to a server with your env in `/tmp/.fly.$UID`, your can use:
```
$ ssh -t <host> '. <(curl -sL https://raw.githubusercontent.com/joknarf/flypack/main/fly.pak) [bash|ksh|zsh]'
```
Connect to all servers with your fly pak from url with ssh config:
```
RequestTTY yes
RemoteCommand . <(curl -sL https://raw.githubusercontent.com/joknarf/flypack/main/fly.pak)
```

## Activate from git repo or url

put your .fly.d directory into a git repo and activate all your env/plugins in your current user
```
. <(curl https://raw.githubusercontent.com/joknarf/thefly/main/thefly) install joknarf/myfly
```

create a tgz file with your .fly.d exposed on web server and activate env/plugins in your current user
```
. <(curl https://raw.githubusercontent.com/joknarf/thefly/main/thefly) install https://myserver/myfly.tgz
```

## joknarf cool plugins

```
$ fly add joknarf/nerdp        # bash/ksh/zsh nerd prompt
$ fly add joknarf/seedee       # bash/ksh/zsh cd history
$ fly add joknarf/redo         # bash/zsh     command history
$ fly add joknarf/complete-ng  # bash/zsh     completion next-gen
or just add the optimized compilation of these shell plugins using just:
$ fly add joknarf/shell-ng

$ fly add joknarf/pgtree       # bash/ksh/zsh process hierarchy
$ fly add joknarf/lsicon       # ls enhancer (colors/icons)
$ fly add joknarf/dfbar        # df enhancer (colors/usage bar)
```

## Don't teleport a human with your fly !

Remember that `~/.fly.d` directory will be duplicated in `/tmp` when teleporting, don't put huge data in your `~/.fly.d` directory, the consequences could be dramatic ! (ask Jeff G. ;-)

The files will remain and will be only be cleared by OS tmpfiles mechanism, the ideal size is to stay below 128K.

(typically thefly will use a ssh config RemoteCommand for the duplication+connect, but if size is over 128K, will use 2 ssh connection, ssh duplicate + ssh interactive connect)

Bzzz Bzzz

thefly

Was this content helpful?

Recent Feedback

Download README