Shortcuts on Jingyuan

Run Shell Commands from Spotlight on Mac with SpotlightShell

Wed, 30 Sep 2026 00:00:00 +0000

SpotlightShell is a small native macOS 26+ app that exposes a Run Shell Command action to Spotlight and Shortcuts.

For a short command such as checking the current directory or producing a small text result, opening Terminal can feel like an extra step. SpotlightShell supplies a command field at runtime instead of maintaining a fixed catalogue of predefined commands.

It uses ordinary user-level shell execution. It does not translate a natural-language request into a command, grant administrator rights, or make the command itself harmless.

Install and let macOS discover the action

A DMG is available in Releases. Follow the release instructions, open the installed app once, and allow macOS time to discover its App Shortcut.

Open Spotlight with Command-Space, use Command-3 to filter Actions, and search for Run Shell Command or SpotlightShell (see Figure 1). If the action is missing, check Shortcuts → Apps → SpotlightShell and reopen the app before troubleshooting further.

Figure 1: Discover the action through Spotlight. Screenshot from the project repository.

To call up the action with sh, find it in Spotlight, click Add quick keys beside it, type sh, and confirm. Then use Command-Space, type sh, and enter your command.

Start with a harmless command

Enter a command whose output you recognize:

`1`	`printf 'Hello from SpotlightShell\n'`

Run it in the background and inspect the report. The result includes stdout, stderr, and the exit status, rather than treating every nonempty message as success (see Figure 2).

Figure 2: Check both the output and exit status. Spotlight controls how much of the report is visible.

You can also try printf 'example error\n' >&2; exit 7: it produces an error message and exit status 7. This makes the difference between “printed something” and “succeeded” visible. In Shortcuts, the action returns text for Show Result; a workflow that branches on failure should inspect its status.

Choose Background or Terminal deliberately

Background mode is for short, noninteractive commands. It runs login zsh with no interactive stdin, captures stdout and stderr separately, and enforces a 20-second execution limit. Each stream retains up to 64 KiB and reports truncation. The visible dialog can be shorter still.

Commands needing a terminal, interactive input, or a longer session belong in Terminal mode. This opens Apple Terminal and hands the command to a new session. Successful handoff means Terminal received the request, not that the program finished successfully; its output stays there.

The working directory is a separate parameter. Use an absolute path, ~, or ~/…, without surrounding shell quotes in the directory field.

Fill the command and directory separately

To inspect a project under Documents, put ~/Documents/My Project in the working-directory field and pwd; ls in Command. The directory is a path parameter: spaces need no surrounding quotes. The command is shell source. Do not put a cd command or a $HOME expression into the directory field.

pwd prints the starting location before ls lists its contents. Keep this check while learning the action. An empty directory defaults to your home folder. Use a complete path rather than assuming Spotlight inherits the directory you last visited in Terminal.

Quoting inside the command is different. A command that opens a filename containing spaces still needs normal shell quoting for that argument. The directory field says where to start; Command says what zsh should do. Keeping those responsibilities separate makes mistakes easier to locate.

Let Terminal handle interaction

Try printf 'hello\n'; tty in Terminal mode. The text appears in a new Terminal window, and tty identifies its terminal device. A continuously updating program such as top also belongs here; press q in Terminal to quit. A command that prints once in Background is not necessarily suited to long-running monitoring.

macOS may ask whether SpotlightShell can control Terminal on the first handoff. This consent is used to open a terminal and send the command; Background does not need that handoff. If you previously denied it and Terminal fails to open, inspect Automation permissions before repeatedly submitting the command.

After handoff, Terminal lives independently of SpotlightShell. Enter passwords or other interactive responses there. A handoff-success report means Terminal received the command, while completion and errors remain visible in its window. If transport times out, inspect Terminal before retrying so you do not accidentally run the same operation twice.

Save a frequent check in Shortcuts

For a recurring short command, create a Shortcut containing SpotlightShell’s Run Shell Command action, set the directory and mode, and add Show Result. A fixed folder-listing check then avoids retyping the path each time. Begin with a short, read-only operation before adapting the flow to everyday work.

Do not use the presence of output as your success condition. A command can print text and fail, or succeed silently. If another step will act on files, inspect the exit-status text first. Timeouts and truncation notices also require attention before trusting the report as a complete result.

Use Terminal for a full, long log. Background works best as one input followed by a short result, while Terminal supports continuing interaction. Spotlight supplies a quick entry point; choosing the right destination keeps the workflow understandable.

Why commands can behave differently

Background mode reads login-shell setup but does not load interactive .zshrc configuration. Aliases, functions, or PATH changes defined only there may be unavailable. Terminal mode uses an interactive login shell and a TTY.

Choose the mode by asking whether the command needs keyboard input or should keep running. Use Terminal for those commands; use Background for a short result.

The app does not upload commands, but shell history, Terminal restoration, Spotlight, Shortcuts, and invoked programs can retain information according to their own settings. It runs with the current user’s abilities, so review a command before submitting it.

For installation, signing, working-directory handling, and output limits, see the project README. For a different Finder automation pattern, Auto Filename Helper shows a Shortcut handing results to a native app.

Suggest Better Filenames on Mac with Shortcuts and Auto Filename Helper

Wed, 30 Sep 2026 00:00:00 +0000

Auto Filename Helper is a native macOS companion that validates and applies filename suggestions supplied by a Shortcut.

A download called document (3).pdf says little about its contents. A meaningful name makes later search easier, but an automated suggestion still needs checking: it may be too vague, contain an unsafe character, or collide with another file.

Auto Filename Helper separates those jobs. The Shortcut derives the suggested name; the native app checks the request and handles the actual rename. The helper itself is not an AI model and does not inspect a document to invent its title.

Build the helper and connect the Shortcut

The project currently provides source and an included Auto Filename.shortcut, rather than a packaged GitHub Release. Building requires macOS 13 or later and Xcode Command Line Tools.

Download the repository, inspect its installation script, then run:

`1`	`./build_and_install.sh`

The script installs ~/Applications/AutoFilenameHelper.app. Import Auto Filename.shortcut into Shortcuts and replace its execution step with the repository’s shortcut_shell_replacement.sh, as the README describes.

This connection matters. Merely opening the app does not create a filename suggestion; the Shortcut must send the selected path and analysis result to the helper.

Think of it as a handoff with a checkpoint: select a file such as document (3).pdf in Finder, let the Shortcut propose a descriptive name, and let the helper check the path, extension, and possible conflict. A proposal such as “project meeting notes.pdf” is only an example; the real name depends on what the Shortcut derives from your file.

Try one file before a batch

Start with a disposable copy of a supported file. Run the Shortcut from Finder, inspect the suggested filename and reason, and check the result in Finder.

The helper receives fields including the path, suggestion, confidence, and reason. It validates the request, preserves the original extension by default, and uses moves that do not overwrite an existing file. It rejects unsafe or hidden names, symlinks, unsupported file types, and unchanged names.

Those checks protect the rename operation; they do not prove that the proposed title describes the contents accurately. Keep names factual and easy to recognize later.

Decide when confirmation is required

The app’s settings include a rename threshold, extension handling, conflict behaviour, appearance, and English/Chinese interface choices. Ambiguous names, low-confidence suggestions, executables, and disabled automatic renaming can trigger confirmation.

Quick Look, Reveal in Finder, and Copy Path help inspect the original before accepting. For files with uncertain contents, the right answer may simply be to keep the existing name until you have checked it.

On the first run, use a copy and check three things: whether the proposed name really describes the content, whether .pdf or another extension stays intact, and whether the folder already contains that name. Even a high confidence value is a reason to inspect the file, not a substitute for opening it.

A confidence value is supplied by the workflow, not an independent certification from the helper. Moving the threshold should be a deliberate convenience choice, especially when filenames influence your later search or filing rules.

Find the project folder before building

If you use Code → Download ZIP on GitHub, unzip the archive and locate the folder containing build_and_install.sh. That is the folder Terminal needs as its current directory. Type cd , drag the folder into Terminal, and press Return before running the build command. This also handles spaces in the path.

If the script reports missing Xcode Command Line Tools, run xcode-select --install, complete the system installer, then return to the project. The script rebuilds and replaces ~/Applications/AutoFilenameHelper.app. Keep a copy first if you have customized an existing installation. The source folder is useful for future updates, while the Shortcut should call the executable inside the installed app.

In the Shortcut editor, find the shell action that invokes the helper and preserve the preceding analysis actions. The supplied replacement script handles the handoff; it does not create a missing analysis workflow. If you choose a different app location, update that invocation too. Otherwise a suggested name may exist while the Shortcut cannot find the program that applies it.

Choose a naming convention you can keep using

Think about the words you will search for later. For meeting documents, a project, topic, and a date actually present in the document can be useful. For invoices, the supplier or invoice number may matter more. A polished title that invents a year, person, or version is harder to trust than a modest, accurate description.

Renaming document (3).pdf to quarterly budget discussion.pdf helps if “budget” is what you will remember. If that name already exists, inspect both documents rather than relying on a numbered suffix to explain their relationship. Keeping the extension is sensible: changing .pdf to .docx does not convert a PDF into a Word document.

Try several copies before choosing a threshold: a clearly named file, an ambiguous one, and a case that conflicts with an existing name. Watch which suggestions are accepted, questioned, or rejected. This gives the threshold a practical meaning in your own workflow instead of treating it as an abstract accuracy score.

When the Shortcut runs but the name stays unchanged

Follow the chain: selected file, generated suggestion, handoff, then rename. If only Settings opens, check whether the Shortcut is passing the payload to standard input. If a confirmation window appears, it may still be waiting for your decision. If the helper reports an unchanged name or unsupported type, resolve that message before rerunning the same input.

Always verify the path. A similarly named document in Downloads, on the Desktop, and in a cloud folder can be three separate files. Use Reveal in Finder to locate the intended original, then check that folder after the rename. If a script or project configuration refers to the old filename, account for those references before changing it.

Local renaming and upstream analysis are separate

The helper makes no network requests. The Shortcut is responsible for deriving the suggestion and may use an AI service depending on its actions and configuration.

Review that Shortcut before applying it to personal documents. “The rename happens locally” does not automatically mean the whole analysis workflow stays on the Mac.

For an explanation of an unfamiliar file before renaming it, see What File Is This. To find the renamed item later, MacHunt provides local filename search. Setup details remain in the project README.

What Is This File? Explain Unfamiliar Files from Finder on Mac

Wed, 30 Sep 2026 00:00:00 +0000

What File Is This combines a Finder Shortcut with a native result window to explain an unfamiliar file or folder in plain language.

An extension is not always enough to answer the useful questions: what produced this file, which app might open it, and is it a companion to something else? What File Is This gathers bounded local evidence through a Shortcut and displays the resulting analysis in a focused Mac window.

The project’s README currently requires macOS 27 or later. Check that requirement before downloading; this is not a tool to assume will run on every recent Mac.

Install both halves

Download the DMG from Releases, drag What File Is This into Applications, and open it once. Import What file is this?.shortcut into Shortcuts as well.

The two components have different responsibilities. The Shortcut gathers evidence and performs the analysis; the app displays its output locally. The app is not an independent file-identification engine that can generate the same result without the Shortcut.

Run it from Finder

Select one file or folder, open Finder’s contextual menu, and choose Quick Actions → What file is this?. A loading window appears while analysis is prepared.

The result can explain the likely type, associated software, ways to open it, and reasons for caution before removal. The repository’s DICOM example demonstrates the format rather than validating any medical interpretation (see Figure 1).

Figure 1: A repository example shows the explanation alongside its evidence. This is a file-format example, not a medical assessment.

Copy the result or reveal the original in Finder when you want to verify a detail. Separate runs receive separate windows; closing the final window quits the app.

Read the evidence, not just the conclusion

A file’s name, signature, metadata, nearby companions, and readable fragments can suggest its purpose. They cannot always establish which application created it or whether a project still depends on it.

An answer such as “possibly a cache” is a hypothesis. Check its location, the owning app, and any related files before deleting it. A confident explanation is also not a malware scan or a guarantee that opening a file is safe.

For example, a same-named .aae beside a photo may look disposable if you only know the extension. The neighbouring photo and its edit history suggest it could contain Apple Photos adjustments. Even then, whether you can remove it depends on whether you still need those edits.

For an archive, Archive Peek can provide another view of its contents without immediately extracting it. For media parameters, View Media Info offers a more direct metadata view.

Interface language and answer language

The app’s English/Chinese interface setting takes effect after quitting and reopening. The Shortcut’s response language is configured separately.

Open the Shortcut, find the text line $language$ = Chinese, and change the language value if needed (see Figure 2). Switching the app interface alone does not rewrite the analysis prompt.

Figure 2: The Shortcut prompt controls the response language independently of the app interface.

Read the answer in three stages

Start with a file whose origin you know but whose extension is unfamiliar, such as a camera sidecar or a configuration file from a known project. This provides a reference while you learn the result window, before investigating material with an uncertain history.

Read the explanation as three questions: what kind of file is it, what can open it, and should you keep it here? The first can be answered from format clues. The last depends on its role in your current project. A configuration file opening in a text editor does not make it a disposable note; another program may still depend on it.

When the analysis offers several possibilities, treat them as investigation leads. Reveal the item in Finder and inspect neighboring files, location, and origin. A lone download and a similarly named item inside an app’s resources can need different treatment. Returning to the folder puts the explanation back into context.

Investigate a folder without mistaking a summary for an inventory

For an unfamiliar project directory, inspect the folder first to understand its likely purpose, then examine important files individually. The Shortcut gathers bounded evidence. A summary of a large directory does not imply every file or dependency was examined.

A folder can contain source documents, generated output, and caches together. “Contains a cache” is not a reason to remove the entire project. Locate the specific subfolder and establish whether the originating software can recreate it. Keep original material, personal edits, and generated files distinguishable in Finder.

For research or specialized formats, separate file identification from content interpretation. Recognizing DICOM can help locate an appropriate viewer, but does not interpret the image. Recognizing a database does not establish that its records can be changed safely. The explanation is most useful when it points you toward a concrete next check.

Diagnose the two halves separately

If the Finder action is missing, confirm that the Shortcut was imported and configured to receive Finder Quick Action input. If it runs without opening a result window, open the installed app once and check that both components are present. Reinstalling one half may not fix a call to the other.

If the result window stays loading, return to Shortcuts and inspect which stage stopped: reading input, preparing evidence, analysis, or delivery. Try a small, readable local file to distinguish a particular-file problem from a broken workflow. Confirm that a cloud item is actually accessible too.

For mixed languages, check the correct setting: app menus come from Settings, while the analysis response comes from the Shortcut prompt. Change the prompt for an English answer under Chinese menus; quit and reopen the app when only its menus need updating. These independent controls serve different parts of the workflow.

Check the Shortcut before sensitive files

The app does not modify the selected item and displays results locally. Review the Shortcut’s evidence-gathering and analysis actions to understand what information it reads and whether an analysis service receives it.

The useful role of this workflow is to make a file easier to investigate. For deletion decisions, irreplaceable data, or specialist material, the explanation should lead you back to verifiable evidence rather than replace it. Installation and transport details are in the README.