10 — Shell Execution

10 — Shell Execution

Two modes of shell execution in String.

Two Modes

	/exec	bash:name
State	None (stateless)	Full shell state
cwd	Document dir or home	Cumulative
Env	base + {var}	Cumulative
Use case	Quick one-shot	Long-running work

/exec — Stateless One-Shot

• Syntax: /exec <command>
• Spawns a new /bin/bash -c process every time
• cwd: current document directory → falls back to home if no document open
• env: process.env + session variables ({var}) exported as environment variables
  • Variables starting with _ (config variables) are excluded
• Timeout: 30 seconds
• stderr + stdout merged into single output
• Empty input → COMMAND_UNSUPPORTED error

Practical Notes

Everything after /exec is passed verbatim to bash -c. Write commands as you would type them in a terminal — do NOT wrap the whole command in quotes.

/exec pwd                              ✅ single command
/exec pwd; echo '---'; ls -la          ✅ chained commands
/exec for f in *.md; do wc -l "$f"; done   ✅ shell constructs work
/exec echo $HOME                       ✅ shell variables expand normally

/exec "pwd; echo test"                 ❌ quotes become part of the command
                                          → bash tries to run literal "pwd; echo test"
                                          → EXIT_127 (command not found)

bash:name — Stateful Terminal

⚠️ Meta-commands in bash sessions use // prefix.

• Correct: //help, //info, //close
• Incorrect: /help (may be sent to bash and fail)

• Topic scheme: bash:name (ChanFlow: <𝒞=string:bash:name>)
• All input is sent to shell stdin — plain text works as-is (no / prefix needed)
• // prefix → String meta-command (//help, //info, //close)
• State preserved: cwd, env vars, shell history

echo hello                 ✅ plain text → shell stdin
/bin/echo hello            ✅ absolute path → shell stdin
cd /tmp && pwd             ✅ chained commands
//help                     ✅ String meta-command
//close                    ✅ String meta-command
/help                      ❌ sent to bash as-is → "bash: /help: No such file or directory"

Common

Output Format

exit: N | cwd: /path
---
output here

• exit: 0 → ok: true
• exit: non-zero → ok: false

Session Variable Export

Both modes export session {var} as environment variables:

• {MY_VAR} → MY_VAR=value in env
• Variables starting with _ are excluded (config/internal)
• $var (runtime variables) are never exported