Commands

Commands are things Tinycast does, reachable by name from the launcher. Some are built in. Others are shell commands you write.

Built-in commands

Every built-in command lives in exactly one Settings pane. A feature's commands sit in that feature's own pane, and only appear while the feature is on. The rest live in Settings → Commands.

Two more appear only for what you type: Open in Browser and Run Shell Command. See Fallbacks.

Each command's row has a launcher checkbox, a shortcut recorder and an alias field.

Every built-in command can take a global shortcut, except Open in Browser and Run Shell Command, which need text to work on, and Quit Tinycast, so no stray key press can quit the app.

A command that opens a screen works like a toggle: press its shortcut again to close it.

Enable Commands at the top of Settings → Commands switches off every command listed in that pane, along with their shortcuts. Unticking one row only hides it from search; its shortcut keeps working.

Custom commands

Give a shell command a name, and run it from search or its own global shortcut.

Settings → Commands → Custom Commands holds the switch. It ships off.

Show in launcher off hides the section but keeps every shortcut working.

Only the name is searchable. The command itself is not, so you cannot run something by half-remembering its flags.

Each command has an Enabled checkbox on its row. Unticking it keeps the command, its shortcut and its settings, but nothing can run it until you tick it again.

The editor

How a command runs

There is no Terminal window and no timeout. Tinycast never stops a running command on its own, and a command keeps running if Tinycast quits. The one exception is the Stop button in the output window.

If the Run In folder no longer exists, the command does not run, and Tinycast tells you which folder is missing. Running it somewhere else would be worse.

Arguments

A command with arguments asks for each one first, in order, right in the palette. The search field becomes the input, and the screen lists every argument with what you have answered so far.

• return moves to the next one. On the last, it runs.
• delete in an empty field goes back one and brings back what you typed.
• esc clears your answer, and a second press cancels the run.
• A required argument cannot be left empty.

This works from the launcher, a favorite number, or a global shortcut.

Values are passed to the shell as $1, $2 …, never pasted into the command text. A value like ; rm -rf ~ is just a string your script reads, not a second command. An empty optional argument still keeps its place, so $2 never slides into $3.

Load shell environment

This is off by default, and it is the most common reason a command fails.

zsh only reads ~/.zshrc for interactive shells. The default -lc reads .zprofile and .zlogin, but not .zshrc. So your aliases, functions and PATH changes are missing, and the command exits with 127.

Turning it on uses -ilc, which reads .zshrc. That also runs everything else your shell startup does, like oh-my-zsh's auto-update or a theme's background helpers.

TINYCAST=1 lets your .zshrc skip that work:

[[ -n $TINYCAST ]] && return

Measured against a real .zshrc: about 10 ms to start with it off, about 65 ms with it on.

When a command exits with 127 and this is off, the error says so and offers Open Settings….

The other fix is to not rely on the shell at all. Use full paths:

/opt/homebrew/bin/gh pr list --limit 5

Show output

With Show output on, a window opens as soon as the command starts and fills in as it prints, in the right order, with colors.

The window shows the command's name and text, the output, the result and how long it took. Copy is always there. Stop ends the command and everything it started; once it finishes, the button becomes Run Again. Progress bars redraw in place instead of printing a line per update.

The window keeps the last 256 KB of output. Scroll up and it stops following new lines; scroll back to the bottom and it follows again.

With Load shell environment on, anything your .zshrc prints shows up here too. The TINYCAST=1 check above keeps it quiet.

Needs confirmation

On by default for every command. The palette closes, then a dialog shows the command's name and full text. return runs it and esc cancels.

It looks calm rather than alarming. Running a command you wrote deserves a second look, not a red warning. It cannot be skipped from the palette or from a shortcut, and holding a shortcut down never stacks up dialogs.

When it finishes

• Success, with Show confirmation on: a small message shows the command's last line of output, or "Ran " if it printed nothing.
• Failure: a dialog shows the error output, up to the last 8 KB.
• With Show output on: the output window reports the result instead, so you never get told twice.

The command text is never written to logs.

Editing and backups

Editing a command keeps its favorite, visibility and shortcut. Deleting it removes all three.

Custom commands and their shortcuts are included in backups. Importing warns you before it adds commands, because a backup that quietly adds shell commands would be a real hazard.

Importing Raycast script commands

Settings → Commands → Import Raycast Scripts reads a folder of Raycast script commands and adds one custom command per script. It is a one-time import: afterwards they are ordinary commands you can edit or delete.

A file counts as a script command when it has both a shebang line and an @raycast.title. Helper scripts in the same folder are left alone.

Raycast icons are not imported; imported commands use the terminal symbol, and you can pick another. The import warns you first, and skips any name you already have, so importing the same folder again only adds new scripts.