# a-Shell: A Unix Terminal for iOS and iPadOS

> a-Shell brings a Unix-like command line to iOS and iPadOS, with one window per context and a command set drawn from the ios_system ecosystem. It suits iPad users who want Python, Lua or a compiler on the device; it is not a Linux emulator.

**holzschu/a-shell** — A terminal for iOS, with multiple windows

- Repository: https://github.com/holzschu/a-shell
- Stars: 3,946 · Forks: 214
- Language: Perl
- License: BSD-3-Clause
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/holzschu-a-shell

## What a-Shell actually is, and who it is for

a-Shell is an iOS and iPadOS app that provides a Unix-like terminal. The README states the goal directly: to provide a simple Unix-like terminal on iOS. It is built on ios_system for command interpretation and ships the commands from that ecosystem, which the README lists as examples: nslookup, whois, python3, lua, pdflatex and lualatex.

The audience is narrower than "anyone who wants a terminal on a phone". If you write shell scripts on a server and want the same muscle memory on an iPad, a-Shell is aimed at you. If you want to run a Linux distribution with its own package manager, you are looking at the wrong project. The README describes a terminal and a set of bundled commands, not a virtual machine running a Linux kernel.

The project also ships a smaller variant. The repository layout contains resources for a-Shell mini, and the README notes that a-Shell mini can run on the devices and the simulator, while the full app runs on devices. That split matters if you plan to build from source rather than install from the App Store.

## Multiple windows, each with its own context

The distinguishing feature is the window model. a-Shell uses the iPadOS 13 ability to create and manage multiple windows. Each window has its own context, appearance, command history and current directory. The commands are `newWindow` to open a window and `exit` to close the current one.

That design has practical consequences. You can keep a Python session in one window and a directory listing in another without either disturbing the other's working directory or scrollback. Appearance is per window too: `config` changes font, font size, background color, text color and cursor color and shape. `config -p` makes the current window's settings permanent for future windows. `config -t` configures the toolbar.

Startup customization runs through a familiar mechanism. When a new window opens, a-Shell executes the file `.profile` if it exists, which the README suggests using for custom environment variables or cleanup of temporary files. Anyone who has maintained a `.profile` on a Unix box will recognize the pattern; the difference is that here it fires per window.

## Where files can live: the sandbox and bookmarks

This is the part that surprises people. On iOS you cannot write in the `~` directory, only in `~/Documents/`, `~/Library/` and `~/tmp`. Most Unix programs assume configuration files live in `$HOME`, so a-Shell changes several environment variables to point at `~/Documents`. Typing `env` shows them. The README adds that most configuration files, including Python packages, TeX files and the Clang SDK, live in `~/Library`.

Reaching outside the app's own container is possible but explicit. a-Shell uses the iOS 13 ability to access directories in another app's sandbox. `pickFolder` opens a directory picker; once a directory is selected, the README warns that you can do pretty much anything you want there. Every directory accessed this way is bookmarked, so it can be revisited without repeating the picker.

The bookmark commands form a small vocabulary: `bookmark` bookmarks the current directory, `showmarks` lists existing bookmarks, `jump mark` and `cd ~mark` change to a specific bookmark, `renamemark` renames one, and `deletemark` removes one. A user-configurable option in Settings lets you use `s`, `g`, `l`, `r` and `d` instead or as well. If you get lost, `cd` returns to `~/Documents/` and `cd -` goes to the previous directory.

## Installing a-Shell and running a first script

The README points to the App Store: a-Shell is available on the App Store, linked from the project's GitHub Pages site. There is no package manager install and no Homebrew formula. On the device, the first thing to do is ask the shell what it has.

```bash
help -l
```

That lists all available commands. The README gives a filtering idiom for checking whether a specific command is present:

```bash
help -l | grep command
```

Replace `command` with the name you are looking for. If it does not appear, it is not installed, and the README does not document a way to add arbitrary prebuilt binaries.

For a first real use, Python is the obvious entry point since `python3` is part of the bundled set. The README lists `python3` among the commands in the ios_system ecosystem, so it is available at the prompt. For compiled code, the workflow differs from a normal Unix box. The README states that you compile C and C++ programs with `clang program.c` and it produces a webAssembly file. You then execute it with either `wasm a.out` or `a.out`. Object files can be linked together and static libraries made with `ar`. Once a program is moved to a directory in `$PATH`, such as `~/Documents/bin`, typing `program` on the command line runs it.

## Shortcuts, and the extension versus app split

a-Shell integrates with Apple Shortcuts, which is how it becomes scriptable from outside the terminal. Three shortcuts are documented: `Execute Command`, which takes a list of commands and runs them in order (the input can also be a file or a text node, in which case the commands inside the node run), plus `Put File` and `Get File` for transferring files to and from a-Shell.

The execution mode is the detail worth understanding. Shortcuts can run "In Extension" or "In App". In Extension means the shortcut runs in a lightweight version of the app with no graphical user interface, which suits light commands that do not need configuration files or system libraries: the README names mkdir, nslookup, whois, touch, cat and echo. In App opens the main application, which has access to all commands but takes longer. The default is to try to run in Extension as much as possible based on the content of the commands, and you can force a specific shortcut either way, with the README's own warning that it will not always work. After a shortcut opens the app, `open shortcuts://` returns you to Shortcuts.

Both kinds run in the same directory by default, `$SHORTCUTS` or `~shortcuts`. Since `cd` and `jump` work inside a shortcut, that default is a starting point rather than a boundary.

## Building from source is a serious undertaking

The README does not present self-compilation as a casual option, and the numbers back that up. The steps are: download the project and its submodules with `git submodule update --init --recursive`, then run `downloadFrameworks.sh` to fetch the standard Apple frameworks into `xcfs/.build/artefacts/xcfs` with checksum control.

Python is the obstacle. The README states there are more than 2000 Python frameworks, too many for automatic download. You either remove them from the Embed step in the project or compile them yourself. Compiling requires the Xcode command line tools (`sudo xcode-select --install`), the OpenSSL libraries (libssl and libcrypto), XQuartz for freetype, and Node.js for npm on macOS. Then you change into `cpython` and run `sh ./downloadAndCompile.sh`, which the README says takes several hours on a 2GHz i5 MacBook Pro, with the usual caveat that your mileage may vary.

For device builds there are further steps: copy `Configuration.sample.xcconfig` to create `Configuration.xcconfig` and replace the team ID and prefixes with your own. The minimum iOS version is 14.0 because Python 3.x uses functions only available in the iOS 14 SDK, and the README notes this also reduces binary size, with ios_system and the other frameworks using the same setting. Running on an iOS 13 device would mean recompiling most frameworks. For most users the App Store build is the only realistic path.

## Limits, and how it differs from iSH

The clearest limitation is the one described above: no writes outside `~/Documents/`, `~/Library/` and `~/tmp`, and access to other apps' directories only through `pickFolder`. A second limit is the command set. a-Shell is not a Linux distribution; it bundles the ios_system commands and whatever the app provides. There is no documented apt, no documented package manager for arbitrary Linux binaries. If your workflow depends on installing a tool from a distribution repository, a-Shell will not serve it.

The natural comparison is iSH, which appears in the related searches as "a-shell vs ish". The difference in approach is architectural. iSH emulates a Linux environment, so programs inside it expect a Linux userland. a-Shell does not emulate a kernel; it provides a terminal and a curated set of commands, with C and C++ compiled to webAssembly rather than to native ARM. That makes a-Shell lighter and more predictable in what it ships, and it makes iSH the better answer when you need the Linux environment itself rather than a terminal on iOS. The README does not make this comparison, so treat it as a description of two designs rather than a benchmark of either.

## Maintenance, licence and what to check first

The repository is not archived, and the last push was on 2026-09-22. The most recent release listed is `cpython_05_22`, tagged as precompiled binaries for cpython, dated 2022-05-22. That gap is worth noting: the release channel has not moved in years even though the repository has. If you depend on a specific Python version, check which one the current build ships rather than assuming the release tag reflects it.

The licence is BSD-3-Clause. That is a permissive licence, and it is the same family used by many of the bundled components. It does not by itself settle the licensing of every framework the build downloads, and the README's build instructions pull in OpenSSL, freetype via XQuartz, and Python. If you plan to redistribute a build, review the licences of those dependencies; this is a description of what the repository states, not legal advice.

Upgrade cost for an App Store user is low: install the update, and note that `config -p` settings and bookmarks persist per the app's own mechanisms. Upgrade cost for a self-builder is high, because the Python framework compilation step is measured in hours and depends on Xcode, OpenSSL, XQuartz and Node.js being present and compatible.

## Conclusion

Adopt a-Shell if you want a real command line on an iPad or iPhone for scripting, Python, Lua or small C programs, and you accept that the sandbox limits where files can live. Do not adopt it if you need a Linux userland with apt, systemd or arbitrary binaries; that is a different class of tool. Before committing, check three things: that your device runs iOS 14.0 or later, that the commands you need appear in the output of help -l, and that your working directories can be reached through pickFolder or a bookmark.

## FAQ

### What is a shell in iOS, and what does a-Shell provide?

a-Shell is an iOS and iPadOS app that provides a Unix-like terminal, using ios_system for command interpretation and including the commands from that ecosystem. It is not part of iOS itself; it is a third-party app available on the App Store.

### How do I use a-Shell?

Open a window and type help for general help, or help -l to list all available commands. Appearance is changed with config, and .profile is executed when a new window opens if that file exists.

### How do I install a-Shell?

The README states that a-Shell is available on the App Store. There is no package manager install documented; building from source is a separate, much longer process involving submodules, downloadFrameworks.sh and the cpython compilation script.

## Sources

- [holzschu/a-shell on GitHub](https://github.com/holzschu/a-shell)
- [Issues](https://github.com/holzschu/a-shell/issues)
- [License: BSD-3-Clause](https://github.com/holzschu/a-shell/blob/master/LICENSE)
- [README](https://github.com/holzschu/a-shell/blob/master/README.md)
- [Releases](https://github.com/holzschu/a-shell/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/holzschu-a-shell