Shale outside the prompt

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.

another shell
$ shale -e 'grep -c milk notes.txt'
1

$ shale -e ',(* 6 7)'
42

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.

another shell
$ shale -c 'for f in *.md; do echo "$f"; done'
README.md

For Shale syntax, use -e. To run a Sigil script, use sigil script.sgl.

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:

another shell
$ 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

line

The line Shale ran.

cause, status

How the line ended, and its exit status. The cause is exited for a command that ran to the end; others include signaled, spawn-failed when a program couldn't start, and refused when Shale wouldn't run the line. In a stage, closed-early marks a command that stopped because the command reading its output finished first and succeeded.

stdout, stderr

What the line wrote, up to 64 KiB of each. Output that isn't valid UTF-8 also appears as hexadecimal in stdout_hex or stderr_hex.

truncated

Whether Shale cut the output short, either at the size limit or because a process kept the stream open after the command ended.

stages

One entry for each command on the line, with its arguments, how it ended and what it wrote to standard error.

duration, cwd

How long the line took in seconds, and the directory it ran in.

files, files_reason

Reserved for the files a line changed. They're null and not sandboxed today.

A failed command still prints its JSON, and Shale exits with the line's status, the same as with -e:

another shell
$ 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 $?
1

With -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.