Looking through Unreal’s source tree I noticed that there is a small CLI tool called ushell located under following directory: [UnrealEngine]/Engine/Extras/ushell
Based on its README.txt, it looks very similar to ue4cli which is a wrapper for platform-dependent build scripts.
I use ue4cli daily and really like it, however said project is stale for past few years so I was searching for some alternatives and thinking about writing something similar on my own. ushell might be what I was looking for, as it still seems to be updated with the latest commit to 5.4 branch being only few days old.
However, besides the source code and README, I was unable to find any information about this tool. Googling, searching through Unreal Forum, nothing… like if it never existed at all… I was only able to find this small note in UnrealBuildTool by ripgrep’ing the files.
The problem is that I’m unable to use this tool on my current Linux machine.
I tried to follow the guide by calling source [UnrealEngine]/Engine/Extras/ushell/ushell.sh from my project’s working directory, but I’m getting:
UShell is a command-line interface to basically make it easier to do common things in Unreal via command line that would otherwise usually be a headache to invoke UAT or P4 commands, which are long and require you to remember their parameter names. Many programmers at Epic Games use it for quality of life. We’ve made it available to the public to use but it’s offered “as is”, we don’t offer support for it.
UShell has tab completion and wraps many common commands into much shorter and convenient aliases.
If you look at that Readme you linked, you’ll see some examples of how to use it.
.build editor
.build game ps4
.build program UnrealInsights shipping
.cook game ps4
.stage game ps4
.run editor
.run game ps4 --trace -- -ExecCmds="Zippy Bungle Rainbow"
.run program UnrealInsights shipping
.p4 cherrypick 1234567
.sln generate
.info
You can write .help in the tool to see more help text. All the information about that tool currently available is in that Readme file and from UShell’s own help texts (try writing just .p4 or .build to see what the command does).
Per README: Ensuring a suitable version of Python is available (and possibly a toolchain to build Pips) is left to the user to take care of. - which might be a problem on Linux distros that forbid pip. For example on Arch-based distros, one must use pacman or pipx instead of pip.
ushell requires exactly Python 3.11. I have 3.12 and script was not detecting its executable. I had to download a separate version. On Arch-based distros said version is accessible here: AUR (en) - python311
README.txt says that ushell.sh must be sourced, but executing it also works just fine. This is important, because sourcing would NOT work with non-POSIX-compliant shells.
[project].uproject file must be associated with proper UE version, otherwise ushell won’t detect it. This is not a big deal on Windows because of UnrealVersionSelector.exe, but on other platforms it may must be done manually. On Linux, engine associations are stored under: ~/.config/Epic/UnrealEngine/Install.ini
For anyone who will be using this on POSIX, I highly suggest to create an alias for ushell - e.g. for bash, it would be alias name="/absolute/path/to/ushell.sh" inside of ~/.bashrc
I’m not sure, if everything works as it should. I’m still testing it on Linux.
I’ll keep this post open for a while as it is the only public information about ushell right now. Literally, the only one that shows up when googling. I’ll try to update the post with any good findings.
As metioned by @dzemzmcdonalda,
Unreal 5.4 prebuilt version as downloaded from Epic Games Launcher does not provide the needed files to run ushell, only a few .tps file.
Is this a known issue?
Any option to have ushell available with prebuilt binaries?
Thank you
