# OpenCore UEFI Shell

## OpenCore UEFI Shell for Hackintosh troubleshooting

You may have never used the OpenCore UEFI Shell before. Here is a little Hackintosh focused introduction.

* The OpenCore UEFI Shell can be used for
  * editing Config.plist, even when Hackintosh is unbootable
  * restoring a Config.plist or an EFI folder from backup
  * finding full device partition paths for Windows & Linux boot entries
  * dumping your DSDT
  * checking devices
  * just for fun, to take a closer look under the hood

You have access to the builtin *OpenShell.efi* which is intended for fixing and troubleshooting. - Press the *space bar* and then select *OpenShell* from the OpenCore boot menu or the GUI:

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FvGm3QNqmwt5qyKk06iTN%2Fimage.png?alt=media\&token=b50fbb3e-7b66-4db8-98d4-d1687ce9ae0d)

You will be greeted with a *Mapping table* showing partitions named FS0, FS1, FS2, etc. 

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2F2ktdupJUSgWyRYj4ijFv%2FEFI-mapping-table.png?alt=media\&token=a327c78e-8247-4a16-8f2a-be1d7774c754)

The command-line interface has many similarities with the macOS BSD-Unix based CLI and other CLIs which you may know from Windows or Linux. Some of the basic commands are very similar, while others are unique to the UEFI Shell.

Type `fs0:` to make the root of the partition the active directory. Type `vol` to check what partition you are on. Then type `ls` to list the files. You may be able to recognise this as the EFI partition of the main macOS drive or it could be a different partition, for example if you have USB drives plugged in. 

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2Fn2eaIeGRMl5KgldVc2rf%2FEFI-shell-show-volume.png?alt=media\&token=a4fcef70-6e87-4880-afa3-700b01a4e9e6)

If you have newly plugged in a USB drive, refresh the mapping table by typing `map -r`. To see more details of the storage devices, type the `map -v -b` command. (`-v` gives more *verbose* output and `-b` will *break* the output of the command into screens to allow you to read it all)

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FnEmo5LKEEONZRJUTyIcv%2FEFI-mapping-detail.png?alt=media\&token=82327533-fb88-4ee9-b6a2-f8ec36bbf3aa)

In this example you can more easily find a USB drive partition (*FS0 and FS1*) by looking for the *Removable: Yes* devices.

Next use the command `devtree -b` to look for the location of the EFI partition on the main macOS drive. As my screenshots come from within a Parallels VM, the device names are different than what will be displayed on a Hackintosh. Under Mojave-0 the first *FAT File System* should be our EFI partition. The handle is `B7`.

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2Fj1QA5ICuUAyzk8HrVC0e%2Fimage.png?alt=media\&token=abc4a2db-0d5d-49b3-8c23-933873e6abe6)

On a Hackintosh, you will likely see the name of the storage drive manufacturer, for example *Kingston* or *WDC*, which will make the partition handles easier to locate. 

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FBkgKpqG56zq25qbDwJRa%2FB50A9159-DCD2-4B82-9C01-3305771D4C24.png?alt=media\&token=e5b884ab-bd1f-4430-9554-a0eb872f00e8)

We can find the `B7` handle in the Mapping Table by using the command `map -b -v` 

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FJqjbHXvOO3Q5G88FLDhz%2FEFI-shell-mapping-lookup.png?alt=media\&token=1b8a7da2-71db-42c3-a806-c6d0c61372cb)

After having confirmed the identity of the partition, we can now make the root of the FS2 partition the active directory by typing `fs2:` and listing its files with `ls`. Change directory with `cd efi\oc` into your OC directory

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FO21DPRTGvrPiDDfluz0w%2FEFI-shell-list-OC.png?alt=media\&token=60b208a5-37e1-48e4-90d7-8ffb6a28e1ec)

Before making changes, backup at least your Config.plist with the command `cp Config.plist Config.plist.bak` 

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2Fu4JcVp8HYRpXcfEoE0pl%2FEFI-shell-backup-config.png?alt=media\&token=3a510f64-0f96-411a-a753-d5d5a3c27d79)

Alternatively backup your complete EFI folder, which may take a little while...

```
cd \
mkdir bak
cp -r EFI bak
```

Then type `edit Config.plist`. Scenario: Maybe you cannot boot, because you forgot to exclude your dGPU (a dedicated Nvidia 1660 card) in the *boot-args* . Therefore in this hypothetical example we will make a small change to the `boot-args` to exclude the dedicated GPU by adding `-wegnoegpu` . - Scroll down to the NVRAM section by using the *page down* key. Then edit the string to look like is shown below. (Don't do this for real, if you actually use your dedicated GPU, as this is just for illustration purposes. Instead just add or delete the verbose setting `-v`, if you want to make a minimal edit.)

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FuuAcLliceEVLqvQIAZhI%2FEFI-shell-edit-config.png?alt=media\&token=80ec8dec-dbc4-4ac8-9973-b2f94e11055e)

Save the changes by pressing `Ctrl S` or `F2` and then `Enter`. Exit the editor with `Ctrl Q` or `F3` . To test your changes type `reset`, which will restart your Hackintosh with these new settings.

If you are able to find your main EFI partition quickly (try `fs0:`and then `vol` first), these kind of changes can be made within less than a minute. It does take a while to learn and memorize some of the commands though.

To list all commands type `help -b`. Then get more detailed help for a specific command, for example by typing `drivers -? -b`

### Useful Commands

**File related & commonly used commands**

```
cd, ls, cp, mv, mkdir, rm, cls
help -b
edit file.name
map -v -b
devtree -b
vol
ver
reset
```

**Device & driver related commands**

```
acpiview
devices
dh
drivers
memmap
pci
smbiosview
```

[**acpiview**](https://chriswayg.gitbook.io/opencore-visual-beginners-guide/advanced-topics/opencore-uefi-shell/acpiview) is able to display and dump ACPI table information.

**Redirect command output to text file**

You should be able to redirect the output of most commands to a file. For example, to be able to use full device partition paths for Windows & Linux boot entries in *OpenCore -> Config.plist -> Misc -> Entries,* it will be useful to save the data to a file in the current directory. 

```
map -v > mapping.txt
```

There are many more commands to explore and you may use the linked documentation below.

### Links

* Introduction to basic commands: [How to Use UEFI Interactive Shell and Its Common Commands](https://linuxhint.com/use-uefi-interactive-shell-and-its-common-commands/#9)
* [Dualbooting with Linux - Identifying your UEFI paths and devices | OpenCore Multiboot](https://dortania.github.io/OpenCore-Multiboot/oc/linux.html#method-c-chainloading-the-kernel-must-support-efistub)
* [Getting a copy of your DSDT via UEFI Shell | Getting Started With ACPI](https://dortania.github.io/Getting-Started-With-ACPI/Manual/dump.html#uefi-shell)
* Official UEFI Manual: [Specifications | Unified Extensible Firmware Interface Forum](https://uefi.org/specifications)
  * **All UEFI Shell commands:** [**UEFI Shell Specification Version 2.2**](http://www.uefi.org/sites/default/files/resources/UEFI_Shell_2_2.pdf)
    * see from page 87 for command reference
  * Thousands of pages: [UEFI Specification Version 2.9 (March 2021)](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_9_2021_03_18.pdf)

![](https://3366797968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwXl0c-BaUDNDvUg8TP%2Fuploads%2FFgodoVfQ9J7nzfXa4rSu%2Fby-nc-license.svg?alt=media\&token=03a208c0-37c6-488e-b564-b57cd43c75c9) *Except where otherwise noted, content on this site is licensed under the* [*Creative Commons — Attribution-NonCommercial 4.0 International — CC BY-NC 4.0*](https://creativecommons.org/licenses/by-nc/4.0/) *license. Attribution by link to* [*chriswayg · GitHub*](https://github.com/chriswayg)*.*