# Plugin Commands

URL: https://tuios.dev/docs/cli-reference/plugin-commands

> Plugin Commands: part of the CLI Reference of TUIOS.

This page is one part of `docs/CLI_REFERENCE.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/CLI_REFERENCE.md). The [CLI Reference](https://tuios.dev/docs/cli-reference) page lists every part.

## Plugin Commands

An enabled plugin runs with your rights. Grants are not a sandbox. See
[PLUGINS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/PLUGINS.md).

### `tuios plugins` (Added in v0.9.0)

Install, list and run plugins (also `tuios plugin`). A plugin is a folder with a
manifest: `tuios-plugin.toml` for a tuios plugin, or `herdr-plugin.toml` for a
herdr plugin.

tuios finds plugins in five places: the folders `[plugins] dirs` names, the
tuios plugins folder, `plugins.lock`, the `plugins.json` of herdr and the
managed checkouts of herdr. To find a plugin runs nothing. A plugin runs only
after you enable it.

| Command                                                                                                                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tuios plugins install SOURCE [--ref REF] [--subdir DIR] [--yes] [--no-enable] [--no-build] [--replace] [--grant admin]` | Get a plugin with git, build it, pin its commit in `plugins.lock` and enable it. `SOURCE` is the name of a plugin of the tuios release, such as `pr-status` (give a folder of that name as `./pr-status`), `owner/repo[/dir][@ref]` on github.com, a git URL (`https://`, `ssh://`, `git@host:path`, `file://`) with an optional `@ref`, or a local folder. tuios shows the plan and asks first. A native plugin that asks for `admin` needs `--grant admin`. Each install builds into a new folder. A failed build changes nothing that runs. Needs `git`. Refused inside a pane |
| `tuios plugins update [ID...] [--check] [--yes] [--grant admin]`                                                         | Move installed plugins to the newest commit of their ref. tuios shows the commits and asks. It asks again, also with `--yes`, on a change to what the plugin runs or asks for, a rewritten history or a tag that moved or is gone. `--check` changes nothing. Exits 3 when a source cannot be reached. Refused inside a pane                                                                                                                                                                                                                                                      |
| `tuios plugins uninstall ID [--yes]`                                                                                     | Undo `tuios plugins install`. Disable the plugin, stop its processes and close its panes. Remove it from `plugins.lock`, remove its folder in `$XDG_DATA_HOME/tuios/plugins/` and remove its approval. `ID` can also be the source you installed from. The config and state folders of the plugin stay. Refused for a plugin that `install` did not install: use `unlink` for a linked folder. Refused inside a pane                                                                                                                                                              |
| `tuios plugins approve ID [--deny] [--grant admin] [--yes]`                                                              | Allow a tuios plugin to run on this machine, or deny it. tuios shows what the plugin runs and its grants, and asks first. A plugin that asks for `admin` needs `--grant admin`. When the plugin's manifest changes, it waits for a new answer. Refused inside a pane and from a plugin                                                                                                                                                                                                                                                                                            |
| `tuios plugins new NAME [--id ID]`                                                                                       | Make a plugin folder that works: a manifest, a shell script, a README and a GitHub workflow that runs `check` and attaches the plugin to the release of a tag                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `tuios plugins check [PATH]`                                                                                             | Read a plugin folder as tuios would. Print each problem and warning, and exit 1 when the plugin cannot load. Runs nothing, needs no daemon                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `tuios plugins dev PATH`                                                                                                 | Install a folder in place and reload it each time a file changes, until Ctrl-C. Asks once at the start. Refused inside a pane                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `tuios plugins install [--yes]`                                                                                          | With no `SOURCE`: install each plugin in `plugins.lock` at its pinned commit. It does not enable them. `--yes` trusts the author of `plugins.lock`                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `tuios plugins list [--json]`                                                                                            | List the plugins tuios finds, with the state of each and the reason: `on`, `off`, `error`, `waiting for approval` or `denied`. An installed plugin shows `managed` and its source and commit. Reads the files only. It runs no plugin code                                                                                                                                                                                                                                                                                                                                        |
| `tuios plugins info ID [--json]`                                                                                         | Show a plugin's build and startup commands, actions, panes, event hooks and link handlers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `tuios plugins enable ID`                                                                                                | Add the plugin to `[plugins] enabled`. A running daemon starts it at once. Refused inside a pane                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `tuios plugins disable ID`                                                                                               | Remove the plugin from `[plugins] enabled` and stop its processes. Refused inside a pane                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `tuios plugins link DIR [--enable]`                                                                                      | Add a plugin folder to `[plugins] dirs`. The plugin stays off unless you add `--enable`. Refused inside a pane                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `tuios plugins unlink ID`                                                                                                | Remove a linked folder from `[plugins] dirs`, disable the plugin and close its panes. Refused inside a pane                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `tuios plugins build ID`                                                                                                 | Run the plugin's `[[build]]` commands in its folder. Each command is shown before it runs. Refused inside a pane                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `tuios plugins run ID ACTION [--wait]`                                                                                   | Run an action of an enabled plugin. `--wait` waits for it to end and prints its output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `tuios plugins open ID PANE [--placement P]`                                                                             | Open a pane of an enabled plugin. `P` is `overlay`, `popup`, `split`, `tab` or `zoomed`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `tuios plugins stats [--json]`                                                                                           | Show each plugin's processes and memory now, and its runs and run time since the daemon started. No memory on macOS. Needs the daemon                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `tuios plugins log [ID] [--limit N] [--json]`                                                                            | Show the last runs of plugin commands, with their exit codes and output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

Run `install`, `update`, `uninstall`, `approve`, `enable`, `disable`, `link`,
`unlink` and `build` from a terminal outside tuios. To write a plugin, read
[PLUGINS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/PLUGINS.md) or run `tuios --skill plugins`.

### `tuios plugin-cell` and `tuios plugin-notify`

Two commands for a plugin with the `ui` grant. They run from the commands of the
plugin.

| Command                                                                         | What it does                                                                                                            |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `tuios plugin-cell set ID TEXT [--action ACTION]`, `tuios plugin-cell clear ID` | From a plugin with the `ui` grant: set or clear a dock cell its manifest names. A click runs `ACTION`                   |
| `tuios plugin-notify TEXT [--level LEVEL]`                                      | From a plugin with the `ui` grant: show a notification under the plugin's name. `LEVEL` is `info`, `warning` or `error` |

The manifest names each cell in `[[cell]]`. The daemon keeps the text of a
cell, so the command can exit.
