Keep text as data through every parser. Check the receiving command's help; use only documented arguments and input modes.
| Available interface | Pass text with |
|---|---|
| Structured tool or process argv API | A string field or one argv element, without a shell |
| CLI file/stdin input | A tool-written file or quoted heredoc; e.g. gh pr create --body-file PATH |
| Shell and positional/flag value only | Quoted heredoc into a variable, then one quoted argument |
Use the owning skill's storage rules first (Markdown, one-line status, context
scope). This skill handles transport, not authorization or formatting policy.
Use -- for leading-hyphen positional text only if the CLI documents it.
Shell quoting does not disable option parsing.
Bash text argument
Choose a delimiter absent from every complete payload line; place both delimiter lines at column 1. Never interpolate payload into an unquoted heredoc.
CLI_TEXT=$(cat <<'CLI_TEXT_84_END'
O'Reilly: `literal` $(literal) $HOME \path — Привет
CLI_TEXT_84_END
)
note-cli set "$CLI_TEXT"
Command substitution removes ALL trailing newlines. This recipe is suitable
only when that matches the requested text. If exact trailing newlines matter,
use file/stdin when supported, or append a sentinel inside the substitution
and remove only that sentinel afterward. Empty text is one argument: "".
NUL cannot be represented in argv or Bash variables; use documented binary
file/stdin input or report that the interface cannot carry it.
Codex JavaScript → Bash
This complete snippet assumes body is an existing string and note-cli set
accepts one text argument. It preserves empty text and exact trailing newlines.
It needs no Node APIs, encoder or filesystem in the JavaScript isolate.
if (body.includes("\0")) throw new Error("CLI argv cannot contain NUL");
let delimiter = "CLI_TEXT_END";
const lines = body.split("\n");
while (lines.includes(delimiter)) delimiter += "_";
const cmd = "CLI_TEXT=$(cat <<'" + delimiter + "'\n" + body +
"\n" + delimiter + "\nprintf .\n)\n" +
'CLI_TEXT=${CLI_TEXT%.}\nCLI_TEXT=${CLI_TEXT%?}\n' +
'note-cli set "$CLI_TEXT"';
const result = await tools.exec_command({cmd});
if (result.exit_code !== 0) throw new Error("Text write did not finish successfully");
The sentinel preserves the heredoc's trailing newlines; the second removal removes exactly the ONE newline added before the closing delimiter. Wait for any running tool process before checking its exit status. After a successful write, use the documented read API when available and compare saved text with the intended value (allow only documented storage normalization). Verify before retrying an uncertain write to avoid duplicate comments or messages.
Common mistakes
JSON.stringify serializes JSON; it does not quote for a shell. Backticks
and $() still execute inside shell double quotes. Never use eval, rebuild
a command from text, or hand-roll Base64 to repair quoting. Treat generated,
user, and log text alike. Check each actual parser boundary, including remote
shells; avoid an extra shell when a direct argv API exists.