> ## Documentation Index
> Fetch the complete documentation index at: https://recircles.rekosk.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line reference

> Open a built-in or custom menu by name, register and pin JSON files, manage main-ring entries, generate a fresh configuration, or clear usage history.

Run `recircles` with no arguments to open the main ring. For a compositor shortcut that goes straight to one menu, bind the full command, such as `recircles --run files`.

## Launch a menu

| Invocation | Result |
| - | - |
| `recircles` | Open the main ring. |
| `recircles --run <name>` | Start directly in a built-in or installed custom menu. At its outermost level, **Esc** closes the launcher. |
| `recircles --run=<name>` | Equivalent form using an equals sign. |
| `recircles --help` or `recircles -h` | Print usage. |
| `recircles --version` or `recircles -V` | Print the installed version. |

### Built-in names

| Name | Alias | Opens |
| - | - | - |
| `files` | — | Folder and file browser |
| `apps` | `applications` | Application launcher |
| `windows` | `alt-tab` | Window switcher |
| `wifi` | `wi-fi` | Wi-Fi networks |
| `bluetooth` | `bt` | Bluetooth devices |
| `settings` | — | Graphical configuration editor |

Built-in names and aliases are case-insensitive. For a custom menu, use the installed filename without `.json`, preserving its case.

## Register and pin

| Invocation | Effect |
| - | - |
| `recircles add <name> <config.json>` | Validate the source JSON and copy it to the configuration directory as `<name>.json`. An existing menu of that name is replaced. |
| `recircles add <name> <config.json> --main-menu <icon>` | Register the file and pin the menu. If already pinned, update the icon. |
| `recircles add <name> --main-menu <icon>` | Pin an existing custom or built-in menu without supplying a file. |

`<config.json>` is a filesystem path. `<icon>` is required with `add --main-menu` and accepts a GTK icon name or an image path. You can also write `--main-menu=<icon>`. Quote paths that contain spaces.

```sh theme={null}
recircles add places ./places.json --main-menu folder
recircles --run places
```

## Unpin or remove

| Invocation | Effect |
| - | - |
| `recircles remove <name> --main-menu` | Remove only the pin. The menu remains available through `--run`. This also works for built-ins. |
| `recircles remove <name>` | Delete the installed custom menu JSON and remove its pin. Built-ins support unpinning only. |

## Configuration and history

| Invocation | Effect |
| - | - |
| `recircles config` | Generate the default `recircles.json`. If the file already exists, report its path and stop. |
| `recircles config --force` or `recircles config -f` | Overwrite `recircles.json` with defaults, including the main-ring order, appearance, palette, and keybindings. Separate menu and theme files are retained. |
| `recircles reset` | Clear the file and application usage counts used for ranking. |

To check the supported environment variables or choose a different configuration directory, see [Launcher configuration](https://recircles.rekosk.dev/docs/reference/configuration.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.