run_cmd

By Goblin Docs ~ 8 min read

:run_cmd spawns a shell command and returns the result as a JSON string containing ok, code, stdout, and stderr.

Overview

:run_cmd takes a command string and an optional working directory. It always returns — it never raises an error on non-zero exit codes. Check ok yourself.

Note

The intrinsic (colon) prefix : is optional to denote that you are using a built-in action (rather than a user-created one). It is optional, but you may find it helpful. All Goblin docs use this prefix in our code snippets.

See more on this here: Intrinsic Prefix

Try this in the REPL:

gbln(1): result | :json_parse(:run_cmd("echo hello"))
gbln(2): result["ok"]
true
gbln(3): result["stdout"]
hello

gbln(4): result["code"]
0

gbln(1): result | :json_parse(:run_cmd("echo hello"))
gbln(2): result["ok"]
true
gbln(3): result["stdout"]
hello

gbln(4): result["code"]
0

:run_cmd returns a raw JSON string — wrap it in :json_parse to access individual fields.

Basic Usage

Run a command and capture output

raw    | :run_cmd("deno run build.ts")
result | :json_parse(raw)
output | result["stdout"]

raw    | :run_cmd("deno run build.ts")
result | :json_parse(raw)
output | result["stdout"]

Check for failure

result | :json_parse(:run_cmd("goblin build.gbln"))

if result["ok"] == false
    :say("Failed: " + result["stderr"])
    return
xx

result | :json_parse(:run_cmd("goblin build.gbln"))

if result["ok"] == false
    :say("Failed: " + result["stderr"])
    return
xx

With a working directory

result | :json_parse(:run_cmd("goblin build.gbln", "../site/portals/my-site"))

result | :json_parse(:run_cmd("goblin build.gbln", "../site/portals/my-site"))

Return Value

Key	Type	Description
`ok`	bool	`true` if exit code was 0
`code`	int or nil	exit code from the process
`stdout`	string	everything written to stdout
`stderr`	string	everything written to stderr

Platform Notes

Note

On Windows, the command runs via cmd /C. On Unix, it runs via sh -lc. Keep command strings portable if you intend to run on both platforms.

Important

If the process fails to spawn (command not found, invalid working directory), Goblin raises a runtime error. If the process runs but exits with a non-zero code, no error is raised — that is reflected in ok and code.