weinguyenandGitHub
c67f0739dc
* Add Quick Shell plugin for launcher commands Introduces `/qs` launcher prefix to run shell commands in an interactive terminal. Features dynamic shell completions (Fish/Bash), command history, user snippets, and directory navigation. * Rename quick-shell plugin to shell command plugin * Update thumbnail.webp * Document shell dependencies and filter completions by current word Filter bash compgen completions to the current word being typed. Declare `sh`, `ls`, `fish`, and `bash` as plugin dependencies.
124 lines
5.2 KiB
Markdown
124 lines
5.2 KiB
Markdown
# Shell Command
|
|
|
|
Run a shell command straight from the Noctalia launcher. Type `/sh` followed by
|
|
any command and press Enter to open it in your default terminal — a **real,
|
|
interactive shell** with live output, TUI apps, and your own native history.
|
|
|
|
No hardcoded completion table: suggestions come from the shell's own completion
|
|
engine and your command history, so they stay in sync with what's actually on
|
|
your system. Commands run through your own `$SHELL` in interactive mode, so
|
|
aliases, functions and environment from your rc config are available.
|
|
|
|
## Features
|
|
|
|
- **Instant command run** — `/sh ls -la ~/projects` opens the command in your
|
|
default terminal.
|
|
- **Fish-style autosuggestions** — completions fetched live from Fish's
|
|
completion engine (`fish -c 'complete -C "<query>"'`), falling back to bash
|
|
`compgen -c` when Fish isn't installed. Type `/sh git st` and get `git status`,
|
|
`git stash`, etc. Suggestions dynamically follow your system — no hardcoded
|
|
list to maintain.
|
|
- **Snap-complete** — when a prefix has exactly one completion, the "Run" entry
|
|
jumps to the completed command, so one Enter runs it instead of fill-then-run.
|
|
- **History** — previously run commands are remembered (per-plugin state, capped
|
|
at 100) and offered as you type, most recent first.
|
|
- **Snippets** — user-defined commands shown when `/sh` is typed with an empty
|
|
query.
|
|
- **Folder jump** — `/sh cd` lists subdirectories and lets you drill into nested
|
|
folders. Select the "Open in:" row to launch a terminal inside the current
|
|
directory.
|
|
- **Navigate and run in one launch** — `/sh cd ~/proj && make` changes into that
|
|
directory and runs the command, so tools open in the right folder.
|
|
- **Suggestion fills, explicit launch runs** — completion/history/snippet rows
|
|
fill the input (so you can keep typing or drill deeper); only "Run:" and
|
|
"Open in:" rows actually launch a terminal.
|
|
- **Stay-open terminal** — after a fast command (e.g. `git status`) the terminal
|
|
holds its output, shows a `[Press Enter to continue]` prompt, then drops you
|
|
into an interactive shell.
|
|
- **Workspace-aware** — when a default workspace is set, commands start in that
|
|
directory.
|
|
|
|
## Plugin
|
|
|
|
| Field | Value |
|
|
| --------------- | ----------------------------- |
|
|
| ID | `weinguyen/shell-command` |
|
|
| Entry | Launcher provider: `provider` |
|
|
| Launcher Prefix | `/sh` |
|
|
|
|
## Requirements
|
|
|
|
- Noctalia v5.0.0 or higher.
|
|
- `runInTerminal` needs a default terminal configured in Noctalia.
|
|
- A shell at `$SHELL` (falls back to `sh`).
|
|
- Optional: Fish (richer completions; falls back to bash otherwise).
|
|
- `ls` for the folder-jump listing.
|
|
|
|
Declared in `plugin.toml`
|
|
`dependencies`: `sh`, `ls`, plus `fish` and `bash` for the completion fallback
|
|
(the user's own `$SHELL` at runtime is whatever shell they have configured).
|
|
|
|
## Usage
|
|
|
|
Open the launcher and type `/sh` followed by a command:
|
|
|
|
```
|
|
/sh
|
|
/sh ls -la ~/projects
|
|
/sh git status
|
|
```
|
|
|
|
Press Enter to run the command in your default terminal.
|
|
|
|
With an empty query, recent commands and configured snippets are offered. As you
|
|
type a command, suggestions from the shell's completion engine appear under the
|
|
exact command you typed. Selecting a suggestion fills the input; run the filled
|
|
command by pressing Enter again (or use snap-complete when only one completion
|
|
matches).
|
|
|
|
### Navigate inside a folder first
|
|
|
|
```
|
|
/sh cd # list top-level folders
|
|
/sh cd proj # list folders starting with "proj"
|
|
/sh cd ~/Builds/ # list everything directly inside ~/Builds
|
|
```
|
|
|
|
Folder rows let you drill deeper (each selection fills the path with a trailing
|
|
slash so you can keep going). The top "Open in:" row launches a terminal inside
|
|
the current parent directory.
|
|
|
|
### Run a command in a directory
|
|
|
|
```
|
|
/sh cd ~/Builds && make
|
|
```
|
|
|
|
Navigates into `~/Builds` and runs `make` there. Paths may contain spaces,
|
|
quotes and `\ ` escapes.
|
|
|
|
## Settings
|
|
|
|
| Setting | Type | Default | Description |
|
|
| ------------------- | ------------- | ------- | ------------------------------------------------------------------------------- |
|
|
| `default_workspace` | `folder` | `""` | Working directory commands (and the `cd` listing) start in. Empty uses `$HOME`. |
|
|
| `snippets` | `string_list` | `[]` | Commands shown when `/sh` is typed with an empty query. |
|
|
|
|
## Notes
|
|
|
|
- Commands run in a real interactive terminal, so tools like `vim`, `htop` and
|
|
`tmux` work normally.
|
|
- Commands execute via `$SHELL -ic`, so aliases and functions from your rc
|
|
config are available. Note that completion — not alias expansion — is what
|
|
powers suggestions; an alias defined only transitively may still need its
|
|
underlying command.
|
|
- Completion suggestions update dynamically as Fish completions and installed
|
|
binaries change — there is no hardcoded list to maintain.
|
|
- History is stored per-plugin (XDG state directory), capped at 100 entries,
|
|
deduplicated, most recent command first.
|
|
|
|
## Development
|
|
|
|
- `shell_provider.luau` — the launcher provider entry.
|
|
- `translations/en.json`, `translations/vi.json` — user-facing strings.
|