Run an Ispell-Expecting Program with GNU Aspell

run-with-aspell tricks an Ispell-only program into talking to GNU Aspell instead, no global setup changes needed. It prepends the Aspell install to PATH for the child process, then replaces itself with the command you name. Allow about ten minutes for a smoke test.

1. Check the wrapper and its purpose

Start with read-only checks. No elevated privileges are needed:

$ command -v run-with-aspell
/usr/bin/run-with-aspell
$ dpkg-query -W -f='${Package} ${Version}\n' aspell
aspell 0.60.8.1-1build1
$ aspell --version
@(#) International Ispell Version 3.1.20 (but really Aspell 0.60.8.1)

The wrapper is not itself a spell-checking mode. Its one documented argument is a command, with optional arguments, and its job is purely to make Ispell-compatible helpers findable before running that command.

Checkpoint: If command -v finds nothing, stop and install or repair the package through your normal system-management process. Do not copy a script into a system directory to work around it.

2. Run a harmless command through the wrapper

Use a command whose output and exit status are obvious, to confirm the wrapper can hand off to a child process at all:

$ run-with-aspell /bin/printf '%s\n' 'aspell-wrapper-ok'
aspell-wrapper-ok
$ printf 'exit status: %s\n' "$?"
exit status: 0

The manual page shows the form run-with-aspell <command>. In the installed script, the command runs after /usr/lib/aspell is placed at the front of PATH. Here is the detail worth knowing: the wrapper does not stick around as a supervising process. It uses exec, so the final exit status you see is the command's own, not the wrapper's.

There is nothing to undo after this test. It changes no service and writes no configuration; the modified PATH exists only inside the launched process and its children.

3. Use it with an Ispell-compatible operation

For a direct demonstration, send one line to Aspell's Ispell-compatible pipe mode through the wrapper:

$ printf '%s\n' 'mispelled word' | run-with-aspell aspell -a
@(#) International Ispell Version 3.1.20 (but really Aspell 0.60.8.1)
& mispelled 13 0: misspelled, dispelled, mi spelled, mi-spelled, spelled, misapplied, miscalled, respelled, misspell, misled, misplaced, misplayed, spilled
*

The exact suggestions depend on the installed dictionary and configuration, so treat the status markers as the useful check in a script rather than matching every suggestion. This example calls aspell directly to make the protocol visible; in normal use, replace it with the real Ispell-oriented program and its arguments:

$ run-with-aspell PROGRAM -- INPUT_FILE

Replace PROGRAM and INPUT_FILE with real, separately quoted values. The wrapper does not translate an arbitrary program's own options; it only arranges the command-lookup environment its manual page describes.

4. Keep command arguments predictable

Quote paths and values that can contain spaces or shell metacharacters:

$ run-with-aspell /usr/local/bin/legacy-editor --file '/path with spaces/notes.txt'

Do not pass a whole command line as one quoted argument. This is one command word, not a request for a shell to parse the contents:

$ run-with-aspell '/usr/local/bin/legacy-editor --file notes.txt'
/usr/bin/run-with-aspell: 4: exec: /usr/local/bin/legacy-editor --file notes.txt: not found

The installed wrapper is a small POSIX shell script that expands its arguments before calling exec. Keep untrusted input away from this line: shell expansion and the program's own option parsing are separate concerns. If you need shell syntax such as a pipeline, invoke a shell deliberately and quote its script carefully, or build the pipeline outside the wrapper:

$ printf '%s\n' 'mispelled' | run-with-aspell aspell -a

5. Diagnose the common failures

A missing command produces a shell error and exit status 127. Check the command path without changing anything:

$ run-with-aspell definitely-not-installed
/usr/bin/run-with-aspell: 4: exec: definitely-not-installed: not found
$ printf 'exit status: %s\n' "$?"
exit status: 127

If the named program is installed but still behaves as though Ispell is absent, run command -v PROGRAM first and check the program's own documentation. The wrapper only prepends /usr/lib/aspell to PATH; it cannot fix a program that hard-codes a different executable, needs a library API, or speaks an incompatible protocol.

Warning: the manual specifically warns against globally mapping ispell to Aspell, because some programs genuinely require real Ispell, including Ispell's own scripts. Prefer a per-command invocation with run-with-aspell. Do not replace /usr/bin/ispell, edit global shell startup files, or reach for sudo to make this work: those changes widen the compatibility risk and are not needed for the documented workflow.

Recovery: If you already changed a shell startup file or a symlink while troubleshooting, restore the previous file or link from your normal configuration backup. The wrapper itself keeps no persistent state and needs no rollback command of its own.

Done means