Shale outside the prompt
One line at a timePermalink to One line at a time#
To run a single line of Shale without starting a session, pass it to -e. Shale reads your configuration, runs the line and exits with its status, so commands you defined work here too. Abbreviations expand only at the prompt.
$ shale -e 'grep -c milk notes.txt'
1
$ shale -e ',(* 6 7)'
42When a program expects a POSIX shellPermalink to When a program expects a POSIX shell#
Some programs run commands through your login shell with -c and expect POSIX shell syntax, such as an editor running a build or ssh running a remote command. Shale passes the text of -c unchanged to /bin/sh, so those programs keep working when Shale is your login shell.
$ shale -c 'for f in *.md; do echo "$f"; done'
README.mdFor Shale syntax, use -e. To run a Sigil script, use sigil script.sgl.
JSON for programs and agentsPermalink to JSON for programs and agents#
A program that runs commands for you, such as a coding agent, needs more than text: whether each command succeeded, what it wrote to which stream, and whether the output was cut short. shale --json -e runs one line of Shale and prints its outcome as one JSON object, on a single line. Here it's spread out so you can read it:
$ shale --json -e 'grep milk notes.txt | wc -l'
{
"line": "grep milk notes.txt | wc -l",
"cause": "exited",
"status": 0,
"stdout": "1\n",
"stderr": "",
"truncated": false,
"stages": [
{"argv": ["grep", "milk", "notes.txt"],
"cause": "exited", "status": 0, "stderr": ""},
{"argv": ["wc", "-l"],
"cause": "exited", "status": 0, "stderr": ""}
],
"duration": 0.075,
"cwd": "/home/ada/project",
"files": null,
"files_reason": "not sandboxed"
}Field | What it holds |
|---|---|
| The line Shale ran. |
| How the line ended, and its exit status. The cause is |
| What the line wrote, up to 64 KiB of each. Output that isn't valid UTF-8 also appears as hexadecimal in |
| Whether Shale cut the output short, either at the size limit or because a process kept the stream open after the command ended. |
| One entry for each command on the line, with its arguments, how it ended and what it wrote to standard error. |
| How long the line took in seconds, and the directory it ran in. |
| Reserved for the files a line changed. They're |
A failed command still prints its JSON, and Shale exits with the line's status, the same as with -e:
$ shale --json -e 'grep plumber README.md'
{
"line": "grep plumber README.md",
"cause": "exited",
"status": 1,
"stdout": "",
"stderr": "",
"truncated": false,
"stages": [
{"argv": ["grep", "plumber", "README.md"],
"cause": "exited", "status": 1, "stderr": ""}
],
"duration": 0.07,
"cwd": "/home/ada/project",
"files": null,
"files_reason": "not sandboxed"
}
$ echo $?
1With -e, JSON mode runs foreground commands only, so a line ending in & comes back with the cause refused and status 2.
For text written for Bash, shale --json --bash runs it unchanged through Bash and reports it in the same shape, with the Bash command as a single stage. Background jobs work there the way they do in Bash. Shale runs /bin/bash unless whoever packaged it chose another path when building it.